Skip to content
Hayonix

API reference · Serverless

Cancel a queued or running job (a running handler is told to stop)

POST/v1/serverless/jobs/{job_id}/cancel
API keyserverless_job:updateProject
TypeScript
client.serverless.cancelJob()
Python
client.serverless.cancel_job()
CLI
hayonix serverless cancel

The job ends as canceled at once; a running handler learns it on its next heartbeat. Canceling a canceled job returns it unchanged; a job that already finished otherwise is a conflict.

Project API key (Authorization: Bearer sk_…), or a console session. Requires the serverless_job:update 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 -X POST "$API_BASE_URL/serverless/jobs/sjb_01jc5zq4m8k3v6x9t2w7r0b1e4/cancel" \
  -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_

Response

200 ServerlessJob — The canceled 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).
409conflict_errorThe resource's current state does not allow this.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.