PT EN

Trabalhos em segundo plano

URL base: $BUSINESS_API

O objecto

idstring · obrigatório
tenant_idstring · opcional
kindstring · obrigatório
statusstring · obrigatório

um de queued, running, succeeded

attemptsinteger · obrigatório
max_attemptsinteger · obrigatório
locked_bystring · opcional
last_errorstring · opcional
request_idstring · opcional
available_atstring (date-time) · obrigatório
created_atstring (date-time) · obrigatório
started_atstring (date-time) · opcional
finished_atstring (date-time) · opcional
O objecto
{
  "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"
}

Listar trabalhos em segundo plano

Registos

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.

Parâmetros

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

statusstring · consulta · opcional

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

um de queued, running, succeeded

kindstring · consulta · opcional

Only jobs of this job kind, matched exactly.

Devolve

200 Jobs

Mostrar atributos
dataarray of JobView · obrigatório
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · opcional
kindstring · obrigatório
statusstring · obrigatório

um de queued, running, succeeded

attemptsinteger · obrigatório
max_attemptsinteger · obrigatório
locked_bystring · opcional
last_errorstring · opcional
request_idstring · opcional
available_atstring (date-time) · obrigatório
created_atstring (date-time) · obrigatório
started_atstring (date-time) · opcional
finished_atstring (date-time) · opcional
has_moreboolean · opcional
next_cursorstring · opcional

Erros 403

Permissões business:jobs:read · Funções: admin, owner

curl -X GET "$BUSINESS_API/jobs" \
  -H "Authorization: Bearer sk_test_..."
Resposta 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"
}

Obter o resumo dos trabalhos

Registos

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.

Devolve

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

Mostrar atributos
enabledboolean · obrigatório

False when this installation runs without the job queue

countsobject · obrigatório

Erros 403

Permissões business:jobs:read · Funções: admin, owner

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

Listar trabalhos falhados

Registos

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.

Parâmetros

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

kindstring · consulta · opcional

Only dead letters of this job kind, matched exactly.

Devolve

200 Dead letters

Mostrar atributos
dataarray of DeadJobView · obrigatório
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · opcional
kindstring · obrigatório
attemptsinteger · obrigatório
last_errorstring · opcional
dead_atstring (date-time) · obrigatório
created_atstring (date-time) · obrigatório
retried_atstring (date-time) · opcional
retried_job_idstring · opcional
has_moreboolean · opcional
next_cursorstring · opcional

Erros 403

Permissões business:jobs:read · Funções: admin, owner

curl -X GET "$BUSINESS_API/jobs/dead-letters" \
  -H "Authorization: Bearer sk_test_..."
Resposta 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"
}

Repetir um trabalho falhado

Registos

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.

Parâmetros

idstring · caminho · obrigatório

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

Devolve

202 The new queued job

Mostrar atributos
idstring · obrigatório
tenant_idstring · opcional
kindstring · obrigatório
statusstring · obrigatório

um de queued, running, succeeded

attemptsinteger · obrigatório
max_attemptsinteger · obrigatório
locked_bystring · opcional
last_errorstring · opcional
request_idstring · opcional
available_atstring (date-time) · obrigatório
created_atstring (date-time) · obrigatório
started_atstring (date-time) · opcional
finished_atstring (date-time) · opcional

Erros 403 · 404 · 409

Permissões business:jobs:retry · Funções: admin, owner

curl -X POST "$BUSINESS_API/jobs/dead-letters/{id}/retry" \
  -H "Authorization: Bearer sk_test_..."
Resposta 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"
}

Obter um trabalho

Registos

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.

Parâmetros

idstring · caminho · obrigatório

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

Devolve

200 The job

Mostrar atributos
idstring · obrigatório
tenant_idstring · opcional
kindstring · obrigatório
statusstring · obrigatório

um de queued, running, succeeded

attemptsinteger · obrigatório
max_attemptsinteger · obrigatório
locked_bystring · opcional
last_errorstring · opcional
request_idstring · opcional
available_atstring (date-time) · obrigatório
created_atstring (date-time) · obrigatório
started_atstring (date-time) · opcional
finished_atstring (date-time) · opcional

Erros 403 · 404

Permissões business:jobs:read · Funções: admin, owner

curl -X GET "$BUSINESS_API/jobs/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 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"
}