---
title: "List serverless endpoint workers"
method: GET
path: "/v2/serverless/{id}/workers"
tags: ["Serverless"]
---

# List serverless endpoint workers

`GET /v2/serverless/{id}/workers`

Lists the active workers for a serverless endpoint.

**Returns.** A `200` with a `ListEndpointWorkersResponse`: a
`workers` array (one entry per active worker, each carrying its `id`,
`status`, and runtime details) plus a `summary` of worker counts
grouped by status. Only currently active workers are included;
scaled-down workers are not returned.

**How `status` is determined.** Each worker's `status` is derived by
reconciling the worker pod's lifecycle status with the endpoint's
live job-queue view (which workers are actively serving requests).
When the job-queue view is unavailable, the response degrades
gracefully: the shape is unchanged, but each `status` and the summary
counts fall back to pod lifecycle alone.

## Response `200`

OK

- ListEndpointWorkersResponse
  - `workers` Worker[], required
    - `id` string, required
    - `status` 'RUNNING' | 'IDLE' | 'INITIALIZING' | 'THROTTLED' | 'UNHEALTHY', required — Derived worker state, reconciled from the worker pod's lifecycle status and the live job-queue view. - `RUNNING` — actively processing a job - `IDLE` — ready and polling for jobs - `INITIALIZING` — starting up, not yet ready - `THROTTLED` — waiting on compute capacity - `UNHEALTHY` — failing health checks
    - `isStale` boolean, required — True when the worker is running an older endpoint configuration than the current one (e.g. mid rolling-update). This is the authoritative flag: it is derived from `version` vs the response's `endpointVersion`, except on legacy endpoints (`endpointVersion` 1) where it falls back to a container-image comparison.
    - `version` integer, nullable — Endpoint configuration version this worker is running. Compare with the response's `endpointVersion`. Null if unknown.
    - `gpuCount` integer, required — GPUs allocated to the worker.
    - `image` string, nullable — Container image the worker is running.
    - `uptimeSeconds` integer, nullable — Seconds the worker has been running. Null until the worker is placed and running.
    - `gpuTypeId` string, nullable — GPU type the worker is placed on. Null until the worker is placed.
    - `dataCenterId` string, nullable — Data center the worker is placed in. Null until the worker is placed.
    - `startedAt` string, date-time, nullable — When the worker last started. Null if it has not started.
  - `summary` WorkerSummary, required — Histogram of the returned workers by status. The per-status counts are a roll-up of the `workers` array, so `running + idle + initializing + throttled + unhealthy == total == len(workers)`.
    - `running` integer, required — Workers actively processing a job.
    - `idle` integer, required — Ready workers polling for jobs.
    - `initializing` integer, required — Workers starting up, not yet ready.
    - `throttled` integer, required — Workers waiting on compute capacity.
    - `unhealthy` integer, required — Workers failing health checks.
    - `total` integer, required — All workers currently allocated to the endpoint.
  - `endpointVersion` integer, nullable — The endpoint's current configuration version. A worker whose `version` differs is running stale config (see `worker.isStale`). Null if unknown.

## Other responses

- `401` — Authentication failed because the bearer token is missing, malformed, expired, or invalid.
- `403` — The bearer token is valid, but it does not grant access to the requested resource or action.
- `404` — The requested resource was not found or is not accessible to the caller.
- `429` — The caller exceeded its per-user rate limit. The response identifies the window that was exceeded and how long to wait. The `RateLimit` and `RateLimit-Policy` headers (per the IETF ratelimit-headers draft) also accompany successful responses, so clients can track quota before a 429.
- `default` — Error

---

[API](https://skmtc.dev/runpod/apis/runpod-rest-api.md) · [All operations](https://skmtc.dev/runpod/apis/runpod-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/runpod/runpod-rest-api/revisions/504cd0394ed6/schema)