# List workflow jobs (/api/jobs/list-jobs)

`GET /api/jobs`

Workflow-job listing (sling jobs list): jobs in one run (run_id), a repo, and/or a time window — at least one of the three is required — filtered by conclusion, keyset-paginated via an opaque cursor. One row per job attempt. Authenticated; scoped to the caller's orgs by membership.

Base URL: `https://runners.starsling.dev`

## Authentication

Requires a bearer token (`Authorization: Bearer`).

## Parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `org` | query | string | yes | GitHub organization login. Required — a job listing is always org-scoped. e.g. `acme` |
| `run_id` | query | string | no | Every job in one run. Alternative to scoping by repo and/or window. e.g. `28961231706` |
| `repo` | query | string | no | Bare repository name, without the org prefix. e.g. `api` |
| `conclusion` | query | array<string> | no | Terminal outcome. Repeatable: ?conclusion=failure&conclusion=timed_out. |
| `window` | query | string | no | Relative lookback, e.g. 30d. Mutually exclusive with from/to and month. e.g. `30d` |
| `from` | query | string | no | Start of the range, inclusive. Required with `to`. e.g. `2026-06-01` |
| `to` | query | string | no | End of the range, exclusive. Required with `from`. e.g. `2026-07-01` |
| `month` | query | string | no | A whole calendar month, YYYY-MM. e.g. `2026-06` |
| `limit` | query | string \| integer | no | Rows per page. Page with `cursor`. 1–100; e.g. `30` |
| `cursor` | query | string | no | Opaque keyset cursor from a prior page's `next_cursor`. |

## Responses

| Status | Description |
| --- | --- |
| `200` | One page of workflow jobs, newest first. Page with `next_cursor`. |
| `400` | No scope was given (`run_id`, `repo`, or a window), the window flags conflict, or the cursor is stale. |
| `401` | No credential, or a GitHub grant too old to read org membership — re-run `sling login`. |
| `403` | You are not a member of the org named in `?org=`. |
| `422` | A path or query parameter failed schema validation. `details` names each offending field. |
| `500` | The control plane failed, or the CI facts store is not configured for this deployment. |

### `200` body

- `jobs` — array<object>, required
  - array of object
    - `job_id` — string, required
    - `run_id` — string, required
    - `name` — string, required
    - `status` — string, required
    - `conclusion` — string
    - `label` — string
    - `runner_id` — string
    - `attempt` — string | integer, required
    - `duration_ms` — string | integer
    - `created_at` — string, required
- `has_more` — boolean, required
- `next_cursor` — string

### Example

```json
{
  "jobs": [
    {
      "job_id": "85933007091",
      "run_id": "28961231706",
      "name": "typecheck",
      "status": "completed",
      "conclusion": "failure",
      "label": "starsling-ubuntu-24.04-8",
      "runner_id": "611593",
      "attempt": 1,
      "duration_ms": 89000,
      "created_at": "2026-07-22T09:14:11.000Z"
    }
  ],
  "has_more": false
}
```