Skip to content
Hayonix

API reference · Serverless

Workers of the endpoint with their state (live ones and those removed in the last hour)

GET/v1/serverless/endpoints/{endpoint_id}/workers
API keyserverless_endpoint:readProjectPaginated
TypeScript
client.serverless.listWorkers()
Python
client.serverless.list_workers()
CLI
hayonix serverless workers

At most 500 workers. Use live=true to leave out removed workers; for a worker that is not starting, scheduling_status and scheduling_message say why.

Project API key (Authorization: Bearer sk_…), or a console session. Requires the serverless_endpoint: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/endpoints/sep_01jc5zq4m8k3v6x9t2w7r0b1e4/workers" \
  -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

  • endpoint_idstringrequired

    ID of the endpoint

    ID with prefix sep_

Query parameters

  • limitinteger

    1–200, default 50

    1–200

  • cursorstring

    `next_cursor` of the previous page

    up to 200 characters

  • liveboolean | string

    Only workers that are not terminated

Response

200 a page of results — Workers, newest first

  • The items of this page.

    Show 25 fields of data
    • objectstringrequired

      Always `serverless_worker`: the type of this object

      One ofserverless_worker

    • idstringrequired

      Unique ID (`swk_…`)

      ID with prefix swk_

    • endpoint_idstringrequired

      ID of the endpoint

    • release_idstringrequired

      ID of the release

    • workload_idstringrequired

      ID of the workload

    • node_idstring | nullrequired

      The node the worker runs on, once placed

    • skustringrequired

      Hardware type code

    • statestringrequired

      `paused`: frozen in place (fast resume), not charged; `resuming`: unfrozen, taking work again once it proves itself

      One ofprovisioningidlebusydrainingpausedresumingterminated

    • running_jobsintegerrequired

      Queue endpoints: jobs this worker is running (0 for HTTP endpoints)

    • in_flightintegerrequired

      HTTP endpoints: requests in flight at this worker (0 for queue endpoints)

    • healthstring | nullrequired

      HTTP endpoints: the health check (null when unknown)

      One ofstartinghealthyunhealthy

    • drain_reasonstring | nullrequired

      While `draining`: why, for example `idle`, `over_max` (above `max_workers`), `outdated` (an older release), `pause` (about to be paused) or `endpoint_deleted`; null otherwise

    • cold_start_msinteger | nullrequired

      Milliseconds from the worker being created until it was ready; null until then

    • paused_atstring (date-time) | nullrequired

      Time paused (ISO 8601, UTC)

    • resumed_atstring (date-time) | nullrequired

      Time resumed (ISO 8601, UTC)

    • resume_countintegerrequired

      Times the worker was resumed from pause

    • created_atstring (date-time)required

      When it was created (ISO 8601, UTC)

    • ready_atstring (date-time) | nullrequired

      Time ready (ISO 8601, UTC)

    • last_seen_atstring (date-time) | nullrequired

      Time last seen (ISO 8601, UTC)

    • idle_sincestring (date-time) | nullrequired

      Since when the worker has had no work; null while it is working or not ready

    • terminated_atstring (date-time) | nullrequired

      Time terminated (ISO 8601, UTC)

    • termination_reasonstring | nullrequired

      Why the worker was removed, for example `idle`, `drained`, `outdated`, `startup_timeout`, `placement_timeout`, `unhealthy`, `silent` (stopped reporting), `paused_expired` or `endpoint_deleted`; null while it is live

    • scheduling_statusstring | nullrequired

      Placement on a host: `pending` (waiting for capacity), `placed`, `refused` or `unschedulable` (no host can take it; see `scheduling_message`); null when unknown

    • scheduling_messagestring | nullrequired

      Why placement is waiting or failed; null when there is nothing to say

    • How the worker started, in order: pulling its image, making each model present (from the host’s model cache or by downloading it), starting the container. Loading inside the container ends at ready_at.

      Show 8 fields of start
      • stepstringrequired

        Which step: pulling the image, making one model present, or starting the container

        One ofimagemodelcontainer

      • statestringrequired

        image: pulling | pulled | present (already on the host) | failed; model: cached (found in the host cache, nothing downloaded) | downloading | downloaded | failed; container: started

      • atstring (date-time) | nullrequired

        When the step reached its state; null for an image already on the host

      • repositorystring

        Model steps: the repository

      • bytes_totalinteger

        Model steps: the size of the model in bytes

      • bytes_doneinteger

        Model steps: bytes present and verified so far

      • bytes_downloadedinteger

        Model steps: bytes downloaded for this start (0 when the host already had the model)

      • secondsinteger | null

        Downloaded model steps: how long the download took, in seconds

  • next_cursorstring | nullrequired

    Pass as `cursor` for the next page; null on the last page.

Example response
Example response
{
  "data": [
    {
      "object": "serverless_worker",
      "id": "swk_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "endpoint_id": "string",
      "release_id": "string",
      "workload_id": "string",
      "node_id": "string",
      "sku": "string",
      "state": "provisioning",
      "running_jobs": 1,
      "in_flight": 1,
      "health": "starting",
      "drain_reason": "string",
      "cold_start_ms": 1,
      "paused_at": "2026-01-01T00:00:00.000Z",
      "resumed_at": "2026-01-01T00:00:00.000Z",
      "resume_count": 1,
      "created_at": "2026-01-01T00:00:00.000Z",
      "ready_at": "2026-01-01T00:00:00.000Z",
      "last_seen_at": "2026-01-01T00:00:00.000Z",
      "idle_since": "2026-01-01T00:00:00.000Z",
      "terminated_at": "2026-01-01T00:00:00.000Z",
      "termination_reason": "string",
      "scheduling_status": "string",
      "scheduling_message": "string",
      "start": [
        {
          "step": "image",
          "state": "string",
          "at": "2026-01-01T00:00:00.000Z",
          "repository": "string",
          "bytes_total": 1,
          "bytes_done": 1,
          "bytes_downloaded": 1,
          "seconds": 1
        }
      ]
    }
  ],
  "next_cursor": "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.