## Background tasks (`tasks`)

Queue of asynchronous operations; you can view tasks, cancel pending ones and retry failed ones.

Authentication: Admin only · Docs: https://www.gocdn888.com/en/docs/api/tasks

### GET `/api/v2/tasks`

List background tasks · Authentication: User (some parameters admin only)

Query parameters:

| Field | Type | Required | Description |
|---|---|---|---|
| `page` | integer |  | Page number, starting from 1 Default: 1 |
| `page_size` | integer |  | Items per page Default: 20 |
| `sort` | string |  | Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id` |
| `tenant_id` | integer |  | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
| `status` | TaskStatus |  | Filter by status. Values: ["pending","running","done","failed"] |
| `ids` | string |  | Only list these IDs: comma-separated positive integers, at most 200 after deduplication (same as the page_size limit; more, or a malformed value, returns 422); an empty value is the same as omitting it. Combined with other filters as an intersection; IDs you cannot see are silently left out. Pagination is unchanged: set page_size to at least the number of IDs to get them in one page |
| `type` | string |  | Filter by task type. |
| `types` | string |  | Only these display types (Task.subject): comma-separated, at most 200 after deduplication and 64 characters each (otherwise 422); matches any of them. node.cmd matches every node command (node.cmd:*). Combined with type as an intersection. |
| `q` | string |  | Search: #123 or a bare number matches the task ID and sites, nodes or certificates with that ID; an IP or CIDR matches that IP object; other text fuzzily matches node names, site names, site domains and certificate names. Tenant credentials never match nodes. Tasks created before the upgrade are not searchable. |
| `routine` | boolean |  | Routine tasks (scheduled or read-only queries): false lists only non-routine ones, true only routine ones; omitted lists all. |
| `open_failed` | boolean |  | When false, leaves out open failures (failed, not cancelled, not ignored, not auto-recovered; GET /tasks/fail-groups lists them in groups); omitted or true leaves them in. |

```sh
curl "https://panel.example.com/api/v2/tasks" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/tasks/{id}`

Get background task · Authentication: User (some parameters admin only)

```sh
curl "https://panel.example.com/api/v2/tasks/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

Background tasks object:

| Field | Type | Required | Description |
|---|---|---|---|
| `attempts` | integer |  | Attempts made so far. |
| `auto_recovered` | integer |  | Number of auto-recovered failures under the same filters. |
| `cancelled` | boolean |  | Cancelled (status failed and last_error is cancelled). |
| `created_at` | string |  | Created at |
| `done` | integer[] |  | IDs processed successfully. |
| `duration_s` | number |  | Duration in seconds (finish minus start, fractional below one second); only for done or failed tasks with a start time, otherwise null. |
| `finished_at` | string |  | Finish time; null if not finished. |
| `groups` | TaskFailGroup[] |  | Groups, most recent failure first. |
| `id` | integer |  | Record ID |
| `ids` | integer[] | Yes | Task IDs. |
| `ignored` | boolean |  | The failure has been ignored. |
| `last_error` | string |  | Last error |
| `max_attempts` | integer |  | Maximum number of attempts. |
| `object` | TaskObject |  | Objects the task acts on; tenant credentials do not see node items. |
| `progress` | TaskProgress |  | Progress; only for running tasks, otherwise null. |
| `reason` | TaskReason |  | Structured failure reason; only for failed tasks that were not cancelled, otherwise null. |
| `recovered` | boolean |  | The failure was auto-recovered (a later task of the same type on the same object succeeded). |
| `retryable` | boolean |  | Whether it can be retried: an allow-listed type (ban, unban, cache purge, prefetch), not routine, failed (including cancelled), not auto-recovered. Staleness is only checked when retrying. |
| `routine` | boolean |  | Routine task (scheduled or read-only query), hidden in the panel by default. |
| `run_after` | string |  | Earliest time the task may run. |
| `skipped` | TaskBatchSkip[] |  | Skipped tasks with reasons. |
| `started_at` | string |  | Time of the latest start; null if never started or created before the upgrade. |
| `status` | TaskStatus |  | Task status: pending, running, done or failed. Values: ["pending","running","done","failed"] |
| `subject` | string |  | Display type: the queue kind; node commands are node.cmd:<command name>. |
| `tenant_id` | integer |  | Tenant that started the task; null for system tasks. |
| `title` | string |  | Short description given by the initiator. |
| `truncated` | boolean |  | There are more than 2000 open failures; only the latest 2000 are grouped. |
| `type` | string |  | Task type (queue kind). |
| `updated_at` | string |  | Updated at |
