API reference · Serverless
Workers of the endpoint with their state (live ones and those removed in the last hour)
/v1/serverless/endpoints/{endpoint_id}/workers- 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
| Header | Required | Description |
|---|---|---|
Authorization | yes | Bearer and your API key. The key implies its project. |
X-Project-Id | session only | The project to act in, for console sessions. Requests with an API key leave it out. |
Path parameters
endpoint_idstringrequiredID of the endpoint
ID with prefix sep_
Query parameters
limitinteger1–200, default 50
1–200
cursorstring`next_cursor` of the previous page
up to 200 characters
liveboolean | stringOnly workers that are not terminated
Response
200 a page of results — Workers, newest first
The items of this page.
ShowHide 25 fields of
dataobjectstringrequiredAlways `serverless_worker`: the type of this object
One of
serverless_workeridstringrequiredUnique ID (`swk_…`)
ID with prefix swk_
endpoint_idstringrequiredID of the endpoint
release_idstringrequiredID of the release
workload_idstringrequiredID of the workload
node_idstring | nullrequiredThe node the worker runs on, once placed
skustringrequiredHardware type code
statestringrequired`paused`: frozen in place (fast resume), not charged; `resuming`: unfrozen, taking work again once it proves itself
One of
provisioningidlebusydrainingpausedresumingterminatedrunning_jobsintegerrequiredQueue endpoints: jobs this worker is running (0 for HTTP endpoints)
in_flightintegerrequiredHTTP endpoints: requests in flight at this worker (0 for queue endpoints)
healthstring | nullrequiredHTTP endpoints: the health check (null when unknown)
One of
startinghealthyunhealthydrain_reasonstring | nullrequiredWhile `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 | nullrequiredMilliseconds from the worker being created until it was ready; null until then
paused_atstring (date-time) | nullrequiredTime paused (ISO 8601, UTC)
resumed_atstring (date-time) | nullrequiredTime resumed (ISO 8601, UTC)
resume_countintegerrequiredTimes the worker was resumed from pause
created_atstring (date-time)requiredWhen it was created (ISO 8601, UTC)
ready_atstring (date-time) | nullrequiredTime ready (ISO 8601, UTC)
last_seen_atstring (date-time) | nullrequiredTime last seen (ISO 8601, UTC)
idle_sincestring (date-time) | nullrequiredSince when the worker has had no work; null while it is working or not ready
terminated_atstring (date-time) | nullrequiredTime terminated (ISO 8601, UTC)
termination_reasonstring | nullrequiredWhy 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 | nullrequiredPlacement on a host: `pending` (waiting for capacity), `placed`, `refused` or `unschedulable` (no host can take it; see `scheduling_message`); null when unknown
scheduling_messagestring | nullrequiredWhy 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.
ShowHide 8 fields of
startstepstringrequiredWhich step: pulling the image, making one model present, or starting the container
One of
imagemodelcontainerstatestringrequiredimage: 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) | nullrequiredWhen the step reached its state; null for an image already on the host
repositorystringModel steps: the repository
bytes_totalintegerModel steps: the size of the model in bytes
bytes_doneintegerModel steps: bytes present and verified so far
bytes_downloadedintegerModel steps: bytes downloaded for this start (0 when the host already had the model)
secondsinteger | nullDownloaded model steps: how long the download took, in seconds
next_cursorstring | nullrequiredPass as `cursor` for the next page; null on the last page.
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:
| Status | Type | When |
|---|---|---|
400 | invalid_request_error | A parameter or body field is missing or not allowed; param names it. |
401 | authentication_error | The key or session is missing, revoked or expired. |
403 | permission_error | The credential lacks the permission this needs, or the organization is suspended. |
404 | not_found_error | No such resource in this project (an ID from another project is answered the same way). |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |