> ## 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/jobs

> List and search jobs with filtering, sorting, and cursor-based pagination.

Returns a paginated list of jobs. Supports filtering by state, queue, worker, and search by task name.

## Authentication

Session cookie (dashboard).

## Query parameters

| Parameter      | Type      | Default     | Description                                                                                                          |
| -------------- | --------- | ----------- | -------------------------------------------------------------------------------------------------------------------- |
| `cursor`       | `string`  | —           | Pagination cursor from a previous response. Max 1000 chars.                                                          |
| `limit`        | `integer` | `50`        | Number of results per page (1–100).                                                                                  |
| `search`       | `string`  | —           | Search by task name (substring match). Max 500 chars.                                                                |
| `state`        | `string`  | —           | Filter by unified state: `unknown`, `queued`, `scheduled`, `active`, `completed`, `failed`, `retrying`, `cancelled`. |
| `queue`        | `string`  | —           | Filter by queue name.                                                                                                |
| `worker`       | `string`  | —           | Filter by worker ID.                                                                                                 |
| `connectionId` | `string`  | —           | Filter by connection UUID.                                                                                           |
| `framework`    | `string`  | —           | Filter by framework: `celery`, `bullmq`, `sidekiq`.                                                                  |
| `sortBy`       | `string`  | `createdAt` | Sort field: `createdAt`, `name`, `state`, `durationMs`, `queue`, `startedAt`, `worker`.                              |
| `sortOrder`    | `string`  | `desc`      | Sort direction: `asc` or `desc`.                                                                                     |

## Response

```json theme={null}
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "externalId": "abc123-def456-ghi789",
      "framework": "celery",
      "connectionId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "app.tasks.send_email",
      "queue": "default",
      "state": "completed",
      "stateChangedAt": "2026-02-27T10:30:00.000Z",
      "scheduledFor": null,
      "createdAt": "2026-02-27T10:29:55.000Z",
      "startedAt": "2026-02-27T10:29:56.000Z",
      "completedAt": "2026-02-27T10:30:00.000Z",
      "durationMs": 4000,
      "workerId": "celery@worker-1",
      "error": null
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ImExYjJjM2Q0... ",
    "limit": 50,
    "total": 1234
  }
}
```

### Job list item fields

| Field            | Type       | Description                                                 |
| ---------------- | ---------- | ----------------------------------------------------------- |
| `id`             | `string`   | Sluice-generated UUID.                                      |
| `externalId`     | `string`   | Framework-native ID (Celery task UUID).                     |
| `framework`      | `string`   | Always `celery` in V0.                                      |
| `connectionId`   | `string`   | Connection this job belongs to.                             |
| `name`           | `string`   | Task type name (e.g., `app.tasks.send_email`).              |
| `queue`          | `string?`  | Queue name, or `null` if unknown.                           |
| `state`          | `string`   | Current unified state.                                      |
| `stateChangedAt` | `string?`  | ISO 8601 timestamp of the last state change.                |
| `scheduledFor`   | `string?`  | ISO 8601 — when this job is scheduled to run (ETA tasks).   |
| `createdAt`      | `string`   | ISO 8601 — when the job was first seen.                     |
| `startedAt`      | `string?`  | ISO 8601 — when execution began.                            |
| `completedAt`    | `string?`  | ISO 8601 — when execution finished.                         |
| `durationMs`     | `integer?` | Execution time in milliseconds (`completedAt - startedAt`). |
| `workerId`       | `string?`  | Worker that processed this job.                             |
| `error`          | `string?`  | Error message, if the job failed.                           |

<Note>
  The list endpoint omits large fields (arguments, results, full stacktrace) for performance. Use [GET /api/jobs/:id](/api/jobs/get) for the complete job record.
</Note>

### Pagination

To get the next page, pass the `nextCursor` value as the `cursor` query parameter:

```
GET /api/jobs?cursor=eyJpZCI6ImExYjJjM2Q0...&limit=50
```

When `nextCursor` is `null`, there are no more results.

## Common queries

Copy-pasteable examples for incident response and debugging.

**All failed payment tasks in the last 24 hours:**

```bash theme={null}
curl -s "https://sluice.sh/api/jobs?state=failed&queue=payments&sortBy=createdAt&sortOrder=desc" \
  -H "Cookie: session=YOUR_SESSION_COOKIE"
```

**Currently stalled tasks (active for too long):**

```bash theme={null}
curl -s "https://sluice.sh/api/jobs?state=active&sortBy=startedAt&sortOrder=asc" \
  -H "Cookie: session=YOUR_SESSION_COOKIE"
```

**All retrying tasks on a specific worker:**

```bash theme={null}
curl -s "https://sluice.sh/api/jobs?state=retrying&worker=celery@worker-1&limit=100" \
  -H "Cookie: session=YOUR_SESSION_COOKIE"
```