> ## Documentation Index > Fetch the complete documentation index at: https://runpod-b18f5ded-lg-apiv2-new.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # List serverless endpoint 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. ## OpenAPI ````yaml get /v2/serverless/{id}/workers openapi: 3.1.0 info: title: Runpod REST API version: 2.0.0 description: Runpod public REST API — v2 servers: - url: https://api.runpod.io description: Runpod API v2 production server security: - bearerAuth: [] tags: - name: Pods description: GPU and CPU pod lifecycle, configuration, actions, and log streaming. - name: Serverless description: >- Serverless endpoint lifecycle, worker visibility, releases, and worker log streaming. - name: Templates description: Reusable pod and endpoint configuration templates. - name: Network Volumes description: Persistent network storage volumes for workloads. - name: Registries description: Container registry credentials used to pull private images. - name: Catalog description: Available GPU, CPU, and data center catalog metadata. - name: Billing description: Billing history and usage cost records across resource types. paths: /v2/serverless/{id}/workers: parameters: - name: id in: path required: true schema: type: string description: Serverless endpoint identifier example: ep_abc123 get: tags: - Serverless summary: List serverless endpoint workers description: | 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. operationId: listEndpointWorkers responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ListEndpointWorkersResponse' examples: workers: summary: Successful response value: endpointVersion: 4 summary: running: 1 idle: 1 initializing: 0 throttled: 0 unhealthy: 0 total: 2 workers: - id: 8g3n5t6r status: RUNNING isStale: false version: 4 gpuCount: 1 image: runpod/pytorch:2.8.0-py3.11-cuda12.8.1 uptimeSeconds: 3600 gpuTypeId: NVIDIA GeForce RTX 4090 dataCenterId: US-KS-2 startedAt: '2026-06-01T12:05:00Z' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '429': $ref: '#/components/responses/TooManyRequestsError' default: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: ListEndpointWorkersResponse: type: object required: - workers - summary properties: workers: type: array items: $ref: '#/components/schemas/Worker' summary: $ref: '#/components/schemas/WorkerSummary' endpointVersion: type: - integer - 'null' description: | The endpoint's current configuration version. A worker whose `version` differs is running stale config (see `worker.isStale`). Null if unknown. examples: - 4 ErrorResponse: type: object required: - title - status - detail properties: title: type: string description: Short human-readable summary examples: - Not Found status: type: integer description: HTTP status code examples: - 404 detail: type: string description: Human-readable explanation examples: - pod not found errors: type: array description: Individual request-validation failures. items: type: string examples: - - '$: additional properties ''bogus'' not allowed' Worker: type: object required: - id - status - gpuCount - isStale properties: id: type: string examples: - worker_abc status: $ref: '#/components/schemas/WorkerStatus' isStale: type: boolean description: > 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. examples: - false version: type: - integer - 'null' description: | Endpoint configuration version this worker is running. Compare with the response's `endpointVersion`. Null if unknown. examples: - 4 gpuCount: type: integer minimum: 0 description: GPUs allocated to the worker. examples: - 1 image: type: - string - 'null' description: Container image the worker is running. examples: - my-org/sdxl-worker:latest uptimeSeconds: type: - integer - 'null' minimum: 0 description: >- Seconds the worker has been running. Null until the worker is placed and running. examples: - 3600 gpuTypeId: type: - string - 'null' description: GPU type the worker is placed on. Null until the worker is placed. examples: - NVIDIA RTX 4090 dataCenterId: type: - string - 'null' description: >- Data center the worker is placed in. Null until the worker is placed. examples: - US-TX-3 startedAt: type: - string - 'null' format: date-time description: When the worker last started. Null if it has not started. examples: - '2026-03-26T00:00:00Z' WorkerSummary: type: object description: | 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)`. required: - running - idle - initializing - throttled - unhealthy - total properties: running: type: integer minimum: 0 description: Workers actively processing a job. examples: - 2 idle: type: integer minimum: 0 description: Ready workers polling for jobs. examples: - 1 initializing: type: integer minimum: 0 description: Workers starting up, not yet ready. examples: - 0 throttled: type: integer minimum: 0 description: Workers waiting on compute capacity. examples: - 0 unhealthy: type: integer minimum: 0 description: Workers failing health checks. examples: - 0 total: type: integer minimum: 0 description: All workers currently allocated to the endpoint. examples: - 3 WorkerStatus: type: string description: | 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 x-enum-varnames: - WorkerStatusRunning - WorkerStatusIdle - WorkerStatusInitializing - WorkerStatusThrottled - WorkerStatusUnhealthy enum: - RUNNING - IDLE - INITIALIZING - THROTTLED - UNHEALTHY responses: UnauthorizedError: description: >- Authentication failed because the bearer token is missing, malformed, expired, or invalid. content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingBearerToken: summary: Missing bearer token value: title: Unauthorized status: 401 detail: missing bearer token ForbiddenError: description: >- The bearer token is valid, but it does not grant access to the requested resource or action. content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficientAccess: summary: Insufficient access value: title: Forbidden status: 403 detail: access denied NotFoundError: description: The requested resource was not found or is not accessible to the caller. content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: summary: Resource not found value: title: Not Found status: 404 detail: resource not found TooManyRequestsError: description: > 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. headers: Retry-After: description: Seconds to wait before retrying, per the exceeded window. schema: type: integer example: 12 RateLimit: description: > Live per-window state as a structured-field list — one member per window (`minute`, `hour`, `day`) with remaining count `r` and seconds-until-reset `t`. schema: type: string example: '"minute";r=0;t=12, "hour";r=2800;t=1812, "day";r=49500;t=45012' RateLimit-Policy: description: > Static quota policy as a structured-field list — one member per window with quota `q` and window length `w` (seconds). schema: type: string example: '"minute";q=60;w=60, "hour";q=3000;w=3600, "day";q=50000;w=86400' content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: summary: Rate limit exceeded value: title: Too Many Requests status: 429 detail: rate limit exceeded for the minute window securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Runpod API Key description: > Runpod API key authentication. Generate an API key in the Runpod console and send it in the `Authorization` header as `Bearer `. Keys are scoped to the permissions granted when created; requests may return `403` when a valid key lacks access to the requested resource or action. ````