> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sluice.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /api/workers

> List workers with status, active job counts, and heartbeat information.

Returns a paginated list of workers with their current status and performance metrics.

## Authentication

Session cookie (dashboard).

## Query parameters

| Parameter      | Type      | Default    | Description                                                                 |
| -------------- | --------- | ---------- | --------------------------------------------------------------------------- |
| `page`         | `integer` | `1`        | Page number (1-indexed).                                                    |
| `limit`        | `integer` | `50`       | Results per page (1–100).                                                   |
| `connectionId` | `string`  | —          | Filter by connection UUID.                                                  |
| `framework`    | `string`  | —          | Filter by framework: `celery`, `bullmq`, `sidekiq`.                         |
| `state`        | `string`  | —          | Filter by worker state: `online`, `busy`, `idle`, `offline`.                |
| `sortBy`       | `string`  | `hostname` | Sort field: `hostname`, `state`, `activeJobs`, `lastHeartbeat`, `taskRate`. |
| `sortOrder`    | `string`  | `asc`      | Sort direction: `asc` or `desc`.                                            |

## Response

```json theme={null}
{
  "data": [
    {
      "id": "d4e5f6a7-b8c9-0123-def0-123456789abc",
      "externalId": "celery@worker-1",
      "framework": "celery",
      "connectionId": "550e8400-e29b-41d4-a716-446655440000",
      "hostname": "celery@worker-1",
      "pid": 12345,
      "state": "online",
      "lastHeartbeat": "2026-02-27T10:30:00.000Z",
      "concurrency": 8,
      "activeJobs": 3,
      "queues": ["default", "payments"],
      "metadata": {
        "software": "celery 5.6.2 (dawn-chorus)",
        "pool": "prefork"
      },
      "taskRate": 4.2,
      "processedTotal": 15230,
      "extensions": {},
      "createdAt": "2026-02-20T08:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 4,
    "totalPages": 1
  }
}
```

### Worker fields

| Field            | Type       | Description                                                                                          |
| ---------------- | ---------- | ---------------------------------------------------------------------------------------------------- |
| `id`             | `string`   | Sluice-generated UUID.                                                                               |
| `externalId`     | `string`   | Framework-native worker ID (Celery hostname, e.g., `celery@worker-1`).                               |
| `framework`      | `string`   | Always `celery` in V0.                                                                               |
| `connectionId`   | `string`   | Connection this worker belongs to.                                                                   |
| `hostname`       | `string`   | Worker hostname.                                                                                     |
| `pid`            | `integer?` | Worker process ID.                                                                                   |
| `state`          | `string`   | Worker state: `online`, `busy`, `idle`, `offline`.                                                   |
| `lastHeartbeat`  | `string?`  | ISO 8601 — time of last heartbeat. Workers that miss heartbeats for >6 seconds are marked `offline`. |
| `concurrency`    | `integer?` | Maximum concurrent jobs this worker can process.                                                     |
| `activeJobs`     | `integer`  | Number of jobs currently being processed.                                                            |
| `queues`         | `string[]` | Queues this worker consumes from.                                                                    |
| `metadata`       | `object`   | Framework-specific metadata — software version, pool type, etc.                                      |
| `taskRate`       | `number?`  | Jobs processed per minute over a rolling 1-hour window.                                              |
| `processedTotal` | `integer?` | Cumulative jobs processed since the worker came online.                                              |
| `extensions`     | `object`   | Framework-specific data.                                                                             |
| `createdAt`      | `string`   | ISO 8601 — when this worker was first seen.                                                          |