Jobs

Base URL: $BUSINESS_API

The object

idstring · required
tenant_idstring · optional
kindstring · required
statusstring · required

one of queued, running, succeeded

attemptsinteger · required
max_attemptsinteger · required
locked_bystring · optional
last_errorstring · optional
request_idstring · optional
available_atstring (date-time) · required
created_atstring (date-time) · required
started_atstring (date-time) · optional
finished_atstring (date-time) · optional
The object
{
  "id": "job_2lTgcbHKkT9eq9du0vtmAFf4Mdb",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "kind": "active",
  "status": "queued",
  "attempts": 1,
  "max_attempts": 1,
  "locked_by": "locked by",
  "last_error": "last error",
  "request_id": "req_2JrY4JziCp1C0bFCSLb4M37qGNH",
  "available_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "started_at": "2026-11-19T09:30:00Z",
  "finished_at": "2026-11-19T09:30:00Z"
}

List durable background jobs

Logs

GET /jobs

Pages the background jobs that belong to the caller's tenant, with limit (default 20, max 100) and the after cursor. Each job shows its kind, status, attempts, last error and timestamps; payloads are never returned. When background jobs are not enabled on the installation, the list is empty. Needs the business:jobs:read scope.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

statusstring · query · optional

Only jobs in this status: queued, running or succeeded (jobs that ran out of attempts are listed under the dead-letters endpoint instead).

one of queued, running, succeeded

kindstring · query · optional

Only jobs of this job kind, matched exactly.

Returns

200 Jobs

Show attributes
dataarray of JobView · required
Show child attributes
idstring · required
tenant_idstring · optional
kindstring · required
statusstring · required

one of queued, running, succeeded

attemptsinteger · required
max_attemptsinteger · required
locked_bystring · optional
last_errorstring · optional
request_idstring · optional
available_atstring (date-time) · required
created_atstring (date-time) · required
started_atstring (date-time) · optional
finished_atstring (date-time) · optional
has_moreboolean · optional
next_cursorstring · optional

Errors 403

Permissions business:jobs:read · Roles: admin, owner

curl -X GET "$BUSINESS_API/jobs" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "job_2lTgcbHKkT9eq9du0vtmAFf4Mdb",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "active",
      "status": "queued",
      "attempts": 1,
      "max_attempts": 1,
      "locked_by": "locked by",
      "last_error": "last error",
      "request_id": "req_2JrY4JziCp1C0bFCSLb4M37qGNH",
      "available_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z",
      "started_at": "2026-11-19T09:30:00Z",
      "finished_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Counts of jobs by status, including dead letters

Logs

GET /jobs/summary

Returns enabled together with a counts map holding the number of the tenant's jobs that are queued, running and succeeded, and the number of dead letters not yet retried. When background jobs are not enabled on the installation, enabled is false and counts is empty. Needs the business:jobs:read scope.

Returns

200 Status counts. enabled is false, with empty counts, when this installation runs without the job queue.

Show attributes
enabledboolean · required

False when this installation runs without the job queue

countsobject · required

Errors 403

Permissions business:jobs:read · Roles: admin, owner

curl -X GET "$BUSINESS_API/jobs/summary" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "enabled": true,
  "counts": {
    "key": 1342
  }
}

List jobs that exhausted their attempts

Logs

GET /jobs/dead-letters

Pages the tenant's dead letters, jobs that failed on every attempt, with limit (default 20, max 100) and the after cursor. Each entry shows the attempts, the last error, when it died and, once retried, the ID of the job that replaced it. The list is empty when background jobs are not enabled. Needs the business:jobs:read scope.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

kindstring · query · optional

Only dead letters of this job kind, matched exactly.

Returns

200 Dead letters

Show attributes
dataarray of DeadJobView · required
Show child attributes
idstring · required
tenant_idstring · optional
kindstring · required
attemptsinteger · required
last_errorstring · optional
dead_atstring (date-time) · required
created_atstring (date-time) · required
retried_atstring (date-time) · optional
retried_job_idstring · optional
has_moreboolean · optional
next_cursorstring · optional

Errors 403

Permissions business:jobs:read · Roles: admin, owner

curl -X GET "$BUSINESS_API/jobs/dead-letters" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "dea_2KcdjsYxFWQZhkyxROS1F4erb4i",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "active",
      "attempts": 1,
      "last_error": "last error",
      "dead_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z",
      "retried_at": "2026-11-19T09:30:00Z",
      "retried_job_id": "ret_2fRcy9RK4bpuKTNimr7mknpcehl"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Requeue a dead letter as a new job

Logs

POST /jobs/dead-letters/{id}/retry

Requeue a dead letter as a new job; a dead letter can be retried once

Creates a fresh queued job with the dead letter's kind and payload, marks the dead letter as retried, and answers 202 with the new job. Each dead letter can be retried only once; a second attempt returns 409, as does a call when background jobs are not enabled. Needs the business:jobs:retry scope; a dead letter of another tenant returns 404.

Parameters

idstring · path · required

ID of the dead letter to requeue, as returned by the dead-letters list; it must belong to the caller's tenant.

Returns

202 The new queued job

Show attributes
idstring · required
tenant_idstring · optional
kindstring · required
statusstring · required

one of queued, running, succeeded

attemptsinteger · required
max_attemptsinteger · required
locked_bystring · optional
last_errorstring · optional
request_idstring · optional
available_atstring (date-time) · required
created_atstring (date-time) · required
started_atstring (date-time) · optional
finished_atstring (date-time) · optional

Errors 403 · 404 · 409

Permissions business:jobs:retry · Roles: admin, owner

curl -X POST "$BUSINESS_API/jobs/dead-letters/{id}/retry" \
  -H "Authorization: Bearer sk_test_..."
Response 202
{
  "id": "job_2lTgcbHKkT9eq9du0vtmAFf4Mdb",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "kind": "active",
  "status": "queued",
  "attempts": 1,
  "max_attempts": 1,
  "locked_by": "locked by",
  "last_error": "last error",
  "request_id": "req_2JrY4JziCp1C0bFCSLb4M37qGNH",
  "available_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "started_at": "2026-11-19T09:30:00Z",
  "finished_at": "2026-11-19T09:30:00Z"
}

Read one job

Logs

GET /jobs/{id}

Returns one background job of the caller's tenant: kind, status, attempts and max attempts, the worker holding it, the last error, the originating request ID and its timestamps. The payload is not returned. A job of another tenant, or any job when background jobs are not enabled, returns 404. Needs the business:jobs:read scope.

Parameters

idstring · path · required

ID of the background job to read; it must belong to the caller's tenant.

Returns

200 The job

Show attributes
idstring · required
tenant_idstring · optional
kindstring · required
statusstring · required

one of queued, running, succeeded

attemptsinteger · required
max_attemptsinteger · required
locked_bystring · optional
last_errorstring · optional
request_idstring · optional
available_atstring (date-time) · required
created_atstring (date-time) · required
started_atstring (date-time) · optional
finished_atstring (date-time) · optional

Errors 403 · 404

Permissions business:jobs:read · Roles: admin, owner

curl -X GET "$BUSINESS_API/jobs/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "job_2lTgcbHKkT9eq9du0vtmAFf4Mdb",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "kind": "active",
  "status": "queued",
  "attempts": 1,
  "max_attempts": 1,
  "locked_by": "locked by",
  "last_error": "last error",
  "request_id": "req_2JrY4JziCp1C0bFCSLb4M37qGNH",
  "available_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "started_at": "2026-11-19T09:30:00Z",
  "finished_at": "2026-11-19T09:30:00Z"
}