# Task API

This page lists the `core` methods for registering, removing, and listing tasks, plus the task state constants.

## Add

```go
func (c *cron) Add(spec string, action interface{}, arg ...interface{}) (int64, error)
```

| Parameter | Type | Description |
|---|---|---|
| `spec` | `string` | 5-field cron, descriptor, or `@every <duration>` |
| `action` | `func()` or `func() error` | Task body |
| `arg` | `string`, `time.Duration`, `func()`, `[]Wait`, `[]int64` | Description, execution limit, timeout callback, prerequisites |

| Return | Condition |
|---|---|
| `id > 0, nil` | Registered |
| `0, failed to parse: ...` | Invalid field count, range, step, or duration in `spec`, or `@every` below 30 seconds |
| `0, action need to be func() or func()` | Unsupported `action` type |
| `0, need return value to get dependence support` | `func()` combined with `[]Wait` or `[]int64` |

An empty `spec` is not rejected with an error: the parser reads `spec[0]` first, so `Add("", ...)` panics with `index out of range`.

## Remove and RemoveAll

### Remove

```go
func (c *cron) Remove(id int64)
```

Disables the task with the given ID and removes it from the heap; no-op when the ID does not exist.

### RemoveAll

```go
func (c *cron) RemoveAll()
```

Clears the heap while running; disables every task before `Start`.

## List

```go
func (c *cron) List() []*task
```

Returns pointers to enabled tasks in the heap; the exported field is `ID int64`. `List` holds the scheduler mutex, but after `Start` the event loop goroutine modifies the heap without that mutex, so calling `List` while the scheduler is running is reported as a data race by `go test -race`.

```go
for _, t := range c.List() {
	log.Println(t.ID)
}
```

## Task State Constants

```go
const (
	TaskPending int = iota
	TaskRunning
	TaskCompleted
	TaskFailed
)
```

See [Task Model](/core-concepts#task-states) for state transition rules.