Background tasks tasks
Queue of asynchronous operations; you can view tasks, cancel pending ones and retry failed ones.
Pick an endpoint to see its example call on the right.
Authentication
Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.
X-API-Key
Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).
Conventions
Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.
Times are RFC 3339 (UTC); amounts are in cents.
Writes return 200/201/204 on success; duplicates of a unique key return 409.
/api/v2/tasksList background tasks
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
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. |
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. |
/api/v2/tasks/{id}Get background task
Authentication: User (some parameters admin only)
Background tasks object
| Field | Type | 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 |
idsRequired | integer[] | 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. |
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 |
Responses and errors
Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.
{
"id": 1,
"name": "example"
}{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}{
"code": "validation_failed",
"detail": "Invalid request parameters",
"errors": [
{
"code": "required",
"field": "/name",
"message": "name is required"
}
],
"request_id": "0123456789abcdef",
"status": 422,
"title": "Unprocessable Entity",
"type": "about:blank"
}