Skip to content
Hayonix

API reference · Serverless

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
API keyserverless_job:createProjectIdempotency-Key
TypeScript
client.serverless.submitJob()
Python
client.serverless.submit_job()
CLI
hayonix serverless run

The job is queued as soon as it is accepted, also while the call waits. A retry with the same Idempotency-Key never creates a second job: it answers with that job in its current state, waiting again if it carries wait.

Project API key (Authorization: Bearer sk_…), or a console session. Requires the serverless_job:create 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/endpoints/sep_01jc5zq4m8k3v6x9t2w7r0b1e4/jobs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "prompt": "a red bicycle"
  }
}'

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.
Idempotency-KeynoMakes a retry safe: the same key and request within 24 hours return the original response (see Idempotency). The SDKs send one for you.

Path parameters

  • endpoint_idstringrequired

    ID of the endpoint

    ID with prefix sep_

Query parameters

  • waitinteger | null

    Wait up to this many seconds (≤ 60) for the job to finish before answering; poll the job afterwards if it has not

    0–60

Body

JSON (application/json): SubmitServerlessJobRequest.

  • inputany JSON

    Any JSON, at most 1048576 bytes serialised

  • webhook_urlstring (uri) | null

    Completion webhook for this job (default: the endpoint's; null for none)

    up to 2048 characters

  • policyobject

    Lower the endpoint's limits for this job

    Show 2 fields of policy
    • execution_timeout_secondsinteger

      Seconds one attempt may run, at most the endpoint's `execution_timeout_seconds` (its default)

      at least 1

    • queue_ttl_secondsinteger

      Seconds the job may wait in the queue, at most the endpoint's `queue_ttl_seconds` (its default)

      at least 1

Response

201 ServerlessJob — The job (finished, if it did so within the wait)

  • 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.
409conflict_error idempotency_in_progressA request with the same Idempotency-Key is still running.
422idempotency_error idempotency_key_reusedThe Idempotency-Key was used with a different request.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.