Skip to content
Hayonix

API reference · Serverless

Job status and result. With `wait`, long-poll until it finishes.

GET/v1/serverless/jobs/{job_id}
API keyserverless_job:readProject
TypeScript
client.serverless.getJob()
Python
client.serverless.get_job()
CLI
hayonix serverless job

Includes the input and every finished attempt. With wait, the answer comes as soon as the job reaches a final state or the wait runs out, whichever is first. The result is kept until result_expires_at.

Project API key (Authorization: Bearer sk_…), or a console session. Requires the serverless_job:read permission (a key's scope, or a role that includes it).

Examples

The samples read API_KEY and API_BASE_URL from the environment (see Setup). Values are examples.

curl -sS "$API_BASE_URL/serverless/jobs/sjb_01jc5zq4m8k3v6x9t2w7r0b1e4" \
  -H "Authorization: Bearer $API_KEY"

Request

Headers
HeaderRequiredDescription
AuthorizationyesBearer and your API key. The key implies its project.
X-Project-Idsession onlyThe project to act in, for console sessions. Requests with an API key leave it out.

Path parameters

  • job_idstringrequired

    ID of the job

    ID with prefix sjb_

Query parameters

  • waitinteger | null

    Wait up to this many seconds for the job to finish

    0–60

Response

200 ServerlessJob — The job

  • objectstringrequired

    Always `serverless_job`: the type of this object

    One ofserverless_job

  • idstringrequired

    Unique ID (`sjb_…`)

    ID with prefix sjb_

  • endpoint_idstringrequired

    ID 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 ofqueuedrunningsucceededfailedtimed_outcanceledexpired

  • outputany JSON

    The handler result (inline results)

  • output_urlstring | nullrequired

    Time-limited link to a large result kept in object storage

  • output_bytesinteger | nullrequired

    Size of the result in bytes; null until there is one

  • errorServerlessJobErrorrequired
    Show 3 fields of error
    • codestringrequired

      Machine-readable code

    • messagestringrequired

      One sentence for people

    • detailsany JSON

      Extra JSON the handler reported with the error, if any

  • progressany JSON

    The latest progress the handler reported (any JSON); null when none

  • attemptintegerrequired

    How many times a worker has taken the job (0 while it has never started)

  • retriesintegerrequired

    Times the job was re-queued because its worker was lost

  • max_retriesintegerrequired

    Retries allowed before the job fails with `worker_lost`

  • worker_idstring | nullrequired

    ID of the worker

  • release_idstring | nullrequired

    ID of the release

  • queue_delay_msinteger | nullrequired

    Milliseconds from submission until a worker first took the job; null while it has never started

  • execution_msinteger | nullrequired

    Milliseconds the last attempt ran, from its start to the end of the job; null until the job finishes after starting

  • created_atstring (date-time)required

    When it was created (ISO 8601, UTC)

  • started_atstring (date-time) | nullrequired

    When it started (null until then) (ISO 8601, UTC)

  • finished_atstring (date-time) | nullrequired

    When it finished (null until then) (ISO 8601, UTC)

  • queue_expires_atstring (date-time)required

    Time queue expires (ISO 8601, UTC)

  • execution_deadlinestring (date-time) | nullrequired

    When the current attempt times out; null while the job waits in the queue

  • result_expires_atstring (date-time) | nullrequired

    Time result expires (ISO 8601, UTC)

  • result_expiredbooleanrequired

    True once the result has been deleted after `result_expires_at`

  • inputany JSON

    The submitted input. Only when fetching one job (`GET /serverless/jobs/{job_id}`).

  • attempt_historyarray of object

    Finished attempts, oldest first. Only when fetching one job (`GET /serverless/jobs/{job_id}`).

    Show 5 fields of attempt_history
    • attemptintegerrequired

      Attempt number, from 1

    • worker_idstring | nullrequired

      ID of the worker

    • started_atstring (date-time) | nullrequired

      When it started (null until then) (ISO 8601, UTC)

    • ended_atstring (date-time) | nullrequired

      When it ended (null until then) (ISO 8601, UTC)

    • outcomestringrequired

      `succeeded`, `failed`, `timed_out`, `canceled`, `returned` (handed back by the worker) or `worker_lost`

Example response
Example response
{
  "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"
    }
  ]
}

Errors

Errors use the standard envelope. What this operation can answer:

Errors
StatusTypeWhen
400invalid_request_errorA parameter or body field is missing or not allowed; param names it.
401authentication_errorThe key or session is missing, revoked or expired.
403permission_errorThe credential lacks the permission this needs, or the organization is suspended.
404not_found_errorNo such resource in this project (an ID from another project is answered the same way).
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.