API reference · Serverless
Queue depth, jobs by state, workers by state and rollout progress
/v1/serverless/endpoints/{endpoint_id}/health- TypeScript
client.serverless.getEndpointHealth()- Python
client.serverless.get_endpoint_health()- CLI
hayonix serverless health
A snapshot taken now. launch explains queued jobs that no worker picks up (credit, spend limit, suspension or worker quota); requests covers HTTP endpoints' live traffic.
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/health" \
-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_
Response
200 ServerlessEndpointHealth — Health
objectstringrequiredAlways `serverless_endpoint_health`: the type of this object
One of
serverless_endpoint_healthendpoint_idstringrequiredID of the endpoint
queueobjectrequiredThe job queue right now
ShowHide 3 fields of
queuequeuedintegerrequiredJobs waiting for a worker
runningintegerrequiredJobs a worker is running
oldest_queued_atstring (date-time) | nullrequiredTime oldest queued (ISO 8601, UTC)
jobsobjectrequiredJobs by state: live ones and those finished in the last 24 hours
workersobjectrequiredLive workers by state
ShowHide 6 fields of
workersprovisioningintegerrequiredStarting: being placed, pulling the image or booting
idleintegerrequiredReady with no work
busyintegerrequiredReady and running jobs or requests
drainingintegerrequiredTaking no new work, finishing what they have, then leaving
pausedintegerrequiredPaused for fast resume (not charged)
resumingintegerrequiredUnpaused, about to take work again
releaseobjectrequiredRollout progress of the current release
ShowHide 3 fields of
releasecurrent_release_idstring | nullrequiredID of the current release
workers_on_currentintegerrequiredLive workers running the current release
workers_outdatedintegerrequiredLive workers still on an older release, replaced as the rollout proceeds
launchobjectrequiredWhether a new worker could start now. When not, queued jobs wait until credit is added, the spend limit clears or worker quota frees up.
ShowHide 2 fields of
launchallowedbooleanrequiredTrue when a new worker could start now
blocked_bystring | nullrequiredWhy not: `insufficient_credit` (no credit left), `spend_limit_reached` (a spend limit was hit), `organization_suspended`, `quota_exceeded` (the worker quota is used up); null when allowed
One of
insufficient_creditspend_limit_reachedorganization_suspendedquota_exceeded
requestsobject | nullrequiredHTTP endpoints: requests in flight at workers and waiting for one, now (null for queue endpoints)
ShowHide 3 fields of
requestsin_flightintegerrequiredRequests being served by workers
waitingintegerrequiredRequests waiting for a ready worker
ready_workersintegerrequiredWorkers passing their health check and taking requests
Example response
{
"object": "serverless_endpoint_health",
"endpoint_id": "string",
"queue": {
"queued": 1,
"running": 1,
"oldest_queued_at": "2026-01-01T00:00:00.000Z"
},
"jobs": {},
"workers": {
"provisioning": 1,
"idle": 1,
"busy": 1,
"draining": 1,
"paused": 1,
"resuming": 1
},
"release": {
"current_release_id": "string",
"workers_on_current": 1,
"workers_outdated": 1
},
"launch": {
"allowed": true,
"blocked_by": "insufficient_credit"
},
"requests": {
"in_flight": 1,
"waiting": 1,
"ready_workers": 1
}
}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. |
402 | insufficient_credit_error | The organization is out of credit or over a spend limit. |
404 | not_found_error | No such resource in this project (an ID from another project is answered the same way). |
429 | quota_exceeded_error quota_exceeded | An organization quota is reached; param names it. |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |