Jobs

A job is one unit of work: a handler name, a JSON payload and the queue that should run it. Jobs move through the states described in the job lifecycle.

API referenceBase URL https://api.sextant.example/v25 endpoints

The Job object

idstring

Unique id, prefixed job_.

queuestring

Queue the job runs on.

handlerstring

Name of the registered handler.

statestring

One of scheduled, queued, running, succeeded, failed, cancelled, dead.

payloadobject

The JSON passed to the handler.

attemptinteger

Attempts made so far.

max_attemptsinteger

Attempts allowed before the job is moved to dead.

run_atstring

ISO 8601 time the job becomes runnable.

Create a job

POST/jobs

Enqueues a job. With run_at in the future the job starts as scheduled. Sending the same idempotency_key twice returns the first job instead of creating a second one.

Required scope jobs:write

Request body

queuestring required

Target queue.

handlerstring required

Registered handler name.

payloadobject optional default {}

JSON payload, up to 256 KiB.

run_atstring optional

ISO 8601 time. Omit to run as soon as a worker is free.

priorityinteger optional default 5

0 (lowest) to 9 (highest).

max_attemptsinteger optional default 5

Overrides the queue default.

idempotency_keystring optional

Deduplicates creates for 24 hours.

Request

cURLShell

curl -X POST https://api.sextant.example/v2/jobs \
  -H "Authorization: Bearer $SEXTANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"queue":"emails","handler":"send-receipt","payload":{"order_id":"ord_4412","to":"[email protected]"},"run_at":"2026-10-20T09:15:00Z","idempotency_key":"receipt-ord_4412"}'

NodeTypeScript

const result = await sextant.jobs.create({
  queue: 'emails',
  handler: 'send-receipt',
  payload: {
    order_id: 'ord_4412',
    to: '[email protected]',
  },
  run_at: '2026-10-20T09:15:00Z',
  idempotency_key: 'receipt-ord_4412',
});

PythonPython

result = client.jobs.create(
    queue="emails",
    handler="send-receipt",
    payload={
        "order_id": "ord_4412",
        "to": "[email protected]",
    },
    run_at="2026-10-20T09:15:00Z",
    idempotency_key="receipt-ord_4412",
)

GoGo

result, err := client.Jobs.Create(ctx, &sextant.JobCreateParams{
	Queue: "emails",
	Handler: "send-receipt",
	Payload: map[string]any{
		"order_id": "ord_4412",
		"to": "[email protected]",
	},
	RunAt: "2026-10-20T09:15:00Z",
	IdempotencyKey: "receipt-ord_4412",
})
if err != nil {
	return err
}

Responses

The job was created.

201JSON

{
  "id": "job_8f3k2m9q",
  "queue": "emails",
  "handler": "send-receipt",
  "state": "queued",
  "priority": 5,
  "payload": {
    "order_id": "ord_4412",
    "to": "[email protected]"
  },
  "attempt": 0,
  "max_attempts": 5,
  "run_at": "2026-10-20T09:15:00Z",
  "created_at": "2026-10-20T09:14:58Z",
  "idempotency_key": "receipt-ord_4412"
}

A job with this idempotency key already exists; it is returned unchanged.

200JSON

{
  "id": "job_8f3k2m9q",
  "queue": "emails",
  "handler": "send-receipt",
  "state": "queued",
  "priority": 5,
  "payload": {
    "order_id": "ord_4412",
    "to": "[email protected]"
  },
  "attempt": 0,
  "max_attempts": 5,
  "run_at": "2026-10-20T09:15:00Z",
  "created_at": "2026-10-20T09:14:58Z",
  "idempotency_key": "receipt-ord_4412"
}

Validation failed, for example an unknown queue.

422JSON

{
  "error": {
    "code": "validation_failed",
    "message": "queue 'emial' does not exist",
    "param": "queue",
    "request_id": "req_c1f0a2"
  }
}

List jobs

GET/jobs

Returns jobs newest first, with cursor pagination.

Required scope jobs:read

Query parameters

queuestring optional

Only jobs on this queue.

statestring optional

Filter by state. Repeat the parameter to match several.

handlerstring optional

Only jobs for this handler.

created_afterstring optional

ISO 8601 lower bound.

limitinteger optional default 50

Page size, 1 to 200.

cursorstring optional

The next_cursor of the previous page.

Request

cURLShell

curl https://api.sextant.example/v2/jobs?limit=20 \
  -H "Authorization: Bearer $SEXTANT_TOKEN"

NodeTypeScript

const result = await sextant.jobs.list({
  limit: 20,
});

PythonPython

result = client.jobs.list(limit=20)

GoGo

result, err := client.Jobs.List(ctx, &sextant.ListParams{Limit: 20})
if err != nil {
	return err
}

Responses

A page of jobs.

200JSON

{
  "data": [
    {
      "id": "job_8f3k2m9q",
      "queue": "emails",
      "handler": "send-receipt",
      "state": "failed",
      "priority": 5,
      "payload": {
        "order_id": "ord_4412",
        "to": "[email protected]"
      },
      "attempt": 2,
      "max_attempts": 5,
      "run_at": "2026-10-20T09:15:00Z",
      "created_at": "2026-10-20T09:14:58Z",
      "idempotency_key": "receipt-ord_4412",
      "last_error": {
        "code": "handler_error",
        "message": "SMTP 451: mailbox busy",
        "at": "2026-10-20T09:15:03Z"
      },
      "next_run_at": "2026-10-20T09:15:33Z"
    }
  ],
  "next_cursor": "cur_Xk92"
}

Retrieve a job

GET/jobs/{job_id}

Returns one job with its last error, if any. Use the runs endpoint of the CLI or the dashboard for the full attempt history.

Required scope jobs:read

Path parameters

job_idstring required

The job id.

Request

cURLShell

curl https://api.sextant.example/v2/jobs/job_8f3k2m9q \
  -H "Authorization: Bearer $SEXTANT_TOKEN"

NodeTypeScript

const result = await sextant.jobs.get('job_8f3k2m9q');

PythonPython

result = client.jobs.get("job_8f3k2m9q")

GoGo

result, err := client.Jobs.Get(ctx, "job_8f3k2m9q")
if err != nil {
	return err
}

Responses

The job.

200JSON

{
  "id": "job_8f3k2m9q",
  "queue": "emails",
  "handler": "send-receipt",
  "state": "failed",
  "priority": 5,
  "payload": {
    "order_id": "ord_4412",
    "to": "[email protected]"
  },
  "attempt": 2,
  "max_attempts": 5,
  "run_at": "2026-10-20T09:15:00Z",
  "created_at": "2026-10-20T09:14:58Z",
  "idempotency_key": "receipt-ord_4412",
  "last_error": {
    "code": "handler_error",
    "message": "SMTP 451: mailbox busy",
    "at": "2026-10-20T09:15:03Z"
  },
  "next_run_at": "2026-10-20T09:15:33Z"
}

Cancel a job

POST/jobs/{job_id}/cancel

Cancels a scheduled or queued job. A running job receives a cancellation signal and is marked cancelled once its handler returns; finished jobs cannot be cancelled.

Required scope jobs:write

Path parameters

job_idstring required

The job id.

Request

cURLShell

curl -X POST https://api.sextant.example/v2/jobs/job_8f3k2m9q/cancel \
  -H "Authorization: Bearer $SEXTANT_TOKEN"

NodeTypeScript

const result = await sextant.jobs.cancel('job_8f3k2m9q');

PythonPython

result = client.jobs.cancel("job_8f3k2m9q")

GoGo

result, err := client.Jobs.Cancel(ctx, "job_8f3k2m9q")
if err != nil {
	return err
}

Responses

The job, now cancelled (or still running if the signal is pending).

200JSON

{
  "id": "job_8f3k2m9q",
  "queue": "emails",
  "handler": "send-receipt",
  "state": "cancelled",
  "priority": 5,
  "payload": {
    "order_id": "ord_4412",
    "to": "[email protected]"
  },
  "attempt": 0,
  "max_attempts": 5,
  "run_at": "2026-10-20T09:15:00Z",
  "created_at": "2026-10-20T09:14:58Z",
  "idempotency_key": "receipt-ord_4412"
}

Retry a job

POST/jobs/{job_id}/retry

Puts a failed or dead job back in its queue with a fresh attempt counter.

Required scope jobs:write

Path parameters

job_idstring required

The job id.

Request

cURLShell

curl -X POST https://api.sextant.example/v2/jobs/job_8f3k2m9q/retry \
  -H "Authorization: Bearer $SEXTANT_TOKEN"

NodeTypeScript

const result = await sextant.jobs.retry('job_8f3k2m9q');

PythonPython

result = client.jobs.retry("job_8f3k2m9q")

GoGo

result, err := client.Jobs.Retry(ctx, "job_8f3k2m9q")
if err != nil {
	return err
}

Responses

The job was re-queued.

202JSON

{
  "id": "job_8f3k2m9q",
  "queue": "emails",
  "handler": "send-receipt",
  "state": "queued",
  "priority": 5,
  "payload": {
    "order_id": "ord_4412",
    "to": "[email protected]"
  },
  "attempt": 0,
  "max_attempts": 5,
  "run_at": "2026-10-20T09:15:00Z",
  "created_at": "2026-10-20T09:14:58Z",
  "idempotency_key": "receipt-ord_4412"
}