Version 2.4.8 · latest

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.

Operations and systemAuthentication: Admin only2 endpoints

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.

GET/api/v2/tasksList background tasks

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
sortstring Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id`
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
statusTaskStatus Filter by status.
Values ["pending","running","done","failed"]
idsstring 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
typestring Filter by task type.
typesstring 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.
qstring 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.
routineboolean Routine tasks (scheduled or read-only queries): false lists only non-routine ones, true only routine ones; omitted lists all.
open_failedboolean 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.
GET/api/v2/tasks/{id}Get background task

Authentication: User (some parameters admin only)

Background tasks object

FieldTypeDescription
attemptsinteger Attempts made so far.
auto_recoveredinteger Number of auto-recovered failures under the same filters.
cancelledboolean Cancelled (status failed and last_error is cancelled).
created_atstring Created at
doneinteger[] IDs processed successfully.
duration_snumber Duration in seconds (finish minus start, fractional below one second); only for done or failed tasks with a start time, otherwise null.
finished_atstring Finish time; null if not finished.
groupsTaskFailGroup[] Groups, most recent failure first.
idinteger Record ID
idsRequiredinteger[] Task IDs.
ignoredboolean The failure has been ignored.
last_errorstring Last error
max_attemptsinteger Maximum number of attempts.
objectTaskObject Objects the task acts on; tenant credentials do not see node items.
progressTaskProgress Progress; only for running tasks, otherwise null.
reasonTaskReason Structured failure reason; only for failed tasks that were not cancelled, otherwise null.
recoveredboolean The failure was auto-recovered (a later task of the same type on the same object succeeded).
retryableboolean 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.
routineboolean Routine task (scheduled or read-only query), hidden in the panel by default.
run_afterstring Earliest time the task may run.
skippedTaskBatchSkip[] Skipped tasks with reasons.
started_atstring Time of the latest start; null if never started or created before the upgrade.
statusTaskStatus Task status: pending, running, done or failed.
Values ["pending","running","done","failed"]
subjectstring Display type: the queue kind; node commands are node.cmd:<command name>.
tenant_idinteger Tenant that started the task; null for system tasks.
titlestring Short description given by the initiator.
truncatedboolean There are more than 2000 open failures; only the latest 2000 are grouped.
typestring Task type (queue kind).
updated_atstring 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.

Success
{
  "id": 1,
  "name": "example"
}
List
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
Error
{
  "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"
}
Get started

Try the live demo

Open the live demo, or contact us for a quote and the install command