API reference · Schema
ServerlessJob
objectstringrequiredAlways `serverless_job`: the type of this object
One of
serverless_jobidstringrequiredUnique ID (`sjb_…`)
ID with prefix sjb_
endpoint_idstringrequiredID of the endpoint
ID with prefix sep_
statestringrequired`queued`: waiting for a worker. `running`: a worker is on it. Final states: `succeeded` (result in `output` or `output_url`), `failed` (the handler reported an error, or retries ran out after lost workers; see `error`), `timed_out` (ran past its execution deadline), `canceled` (by request, a purge or the endpoint being deleted), `expired` (not started within its queue TTL).
One of
queuedrunningsucceededfailedtimed_outcanceledexpiredoutputany JSONThe handler result (inline results)
output_urlstring | nullrequiredTime-limited link to a large result kept in object storage
output_bytesinteger | nullrequiredSize of the result in bytes; null until there is one
ShowHide 3 fields of
errorcodestringrequiredMachine-readable code
messagestringrequiredOne sentence for people
detailsany JSONExtra JSON the handler reported with the error, if any
progressany JSONThe latest progress the handler reported (any JSON); null when none
attemptintegerrequiredHow many times a worker has taken the job (0 while it has never started)
retriesintegerrequiredTimes the job was re-queued because its worker was lost
max_retriesintegerrequiredRetries allowed before the job fails with `worker_lost`
worker_idstring | nullrequiredID of the worker
release_idstring | nullrequiredID of the release
queue_delay_msinteger | nullrequiredMilliseconds from submission until a worker first took the job; null while it has never started
execution_msinteger | nullrequiredMilliseconds the last attempt ran, from its start to the end of the job; null until the job finishes after starting
created_atstring (date-time)requiredWhen it was created (ISO 8601, UTC)
started_atstring (date-time) | nullrequiredWhen it started (null until then) (ISO 8601, UTC)
finished_atstring (date-time) | nullrequiredWhen it finished (null until then) (ISO 8601, UTC)
queue_expires_atstring (date-time)requiredTime queue expires (ISO 8601, UTC)
execution_deadlinestring (date-time) | nullrequiredWhen the current attempt times out; null while the job waits in the queue
result_expires_atstring (date-time) | nullrequiredTime result expires (ISO 8601, UTC)
result_expiredbooleanrequiredTrue once the result has been deleted after `result_expires_at`
inputany JSONThe submitted input. Only when fetching one job (`GET /serverless/jobs/{job_id}`).
attempt_historyarray of objectFinished attempts, oldest first. Only when fetching one job (`GET /serverless/jobs/{job_id}`).
ShowHide 5 fields of
attempt_historyattemptintegerrequiredAttempt number, from 1
worker_idstring | nullrequiredID of the worker
started_atstring (date-time) | nullrequiredWhen it started (null until then) (ISO 8601, UTC)
ended_atstring (date-time) | nullrequiredWhen it ended (null until then) (ISO 8601, UTC)
outcomestringrequired`succeeded`, `failed`, `timed_out`, `canceled`, `returned` (handed back by the worker) or `worker_lost`
{
"object": "serverless_job",
"id": "sjb_01jc5zq4m8k3v6x9t2w7r0b1e4",
"endpoint_id": "sep_01jc5zq4m8k3v6x9t2w7r0b1e4",
"state": "queued",
"output": {},
"output_url": "string",
"output_bytes": 1,
"error": {
"code": "string",
"message": "string",
"details": {}
},
"progress": {},
"attempt": 1,
"retries": 1,
"max_retries": 1,
"worker_id": "string",
"release_id": "string",
"queue_delay_ms": 1,
"execution_ms": 1,
"created_at": "2026-01-01T00:00:00.000Z",
"started_at": "2026-01-01T00:00:00.000Z",
"finished_at": "2026-01-01T00:00:00.000Z",
"queue_expires_at": "2026-01-01T00:00:00.000Z",
"execution_deadline": "2026-01-01T00:00:00.000Z",
"result_expires_at": "2026-01-01T00:00:00.000Z",
"result_expired": true,
"input": {},
"attempt_history": [
{
"attempt": 1,
"worker_id": "string",
"started_at": "2026-01-01T00:00:00.000Z",
"ended_at": "2026-01-01T00:00:00.000Z",
"outcome": "string"
}
]
}Used by
- List jobs of an endpoint, newest first
GET /v1/serverless/endpoints/{endpoint_id}/jobs - Submit a job. With `wait`, answer once it finishes or the wait runs out (then poll the job).
POST /v1/serverless/endpoints/{endpoint_id}/jobs - Job status and result. With `wait`, long-poll until it finishes.
GET /v1/serverless/jobs/{job_id} - Cancel a queued or running job (a running handler is told to stop)
POST /v1/serverless/jobs/{job_id}/cancel