# Rank the biggest CI consumers (/api/top/get-top)

`GET /api/top`

Aggregate CI leaderboard: rank StarSling-billed jobs by runner-minutes, cost, jobs, p95 duration, p99 duration, or queue wait, grouped by workflow/job/label/repo/branch, over a time window, with each row's trend vs. the prior equal-length window. Scoped to the caller's orgs.

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 leaderboard is always org-scoped. e.g. `acme` |
| `repo` | query | string | no | Narrow to one repository, as owner/name. Both segments are required. e.g. `acme/api` |
| `by` | query | string | no | Ranking axis — what each row is a total for. `workflow`, `job`, `label`, `repo`, `branch`; e.g. `workflow` |
| `metric` | query | string | no | Metric the leaderboard ranks on. `runner-minutes`, `cost`, `jobs`, `p95-duration`, `p99-duration`, `queue-wait`; e.g. `runner-minutes` |
| `order` | query | string | no | Sort direction — desc puts the biggest burner first. `asc`, `desc`; e.g. `desc` |
| `n` | query | string \| integer | no | How many rows to rank. Defaults to 20. 1–100; e.g. `20` |
| `window` | query | string | no | Relative lookback, e.g. 30d. Mutually exclusive with month and from/to. e.g. `30d` |
| `month` | query | string | no | A whole calendar month, YYYY-MM. e.g. `2026-06` |
| `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` |

## Responses

| Status | Description |
| --- | --- |
| `200` | The ranked leaderboard for the resolved window, with each row's trend against the window before it. |
| `400` | The window flags conflict or don't parse. Omit them all for the default window, or give exactly one of `window`, `month`, or `from`+`to`. |
| `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=`, or the API key lacks `usage:read`. |
| `422` | A query parameter failed schema validation — an unrecognised `by`, `metric`, or `order`, or an `n` outside 1-100. `details` names the offending field. |
| `500` | The request was valid; the control plane or a dependency it calls failed. |

### `200` body

- `by` — string, required. Ranking axis — what each row is a total for. `workflow`, `job`, `label`, `repo`, `branch`; e.g. `workflow`
- `metric` — string, required. Metric the leaderboard ranks on. `runner-minutes`, `cost`, `jobs`, `p95-duration`, `p99-duration`, `queue-wait`; e.g. `runner-minutes`
- `window` — object, required
  - `from` — string, required. e.g. `2026-06-22T00:00:00.000Z`
  - `to` — string, required. e.g. `2026-07-22T00:00:00.000Z`
- `rows` — array<object>, required
  - array of object
    - `key` — string, required. e.g. `Prebuild`
    - `repo` — string, required. e.g. `hpc-sandbox-benchmarks`
    - `runner_minutes` — number, required. e.g. `66043.9`
    - `cost_usd` — number, required. e.g. `528.35`
    - `runs` — number, required. e.g. `37`
    - `jobs` — number, required. e.g. `1460`
    - `p50_ms` — number, required. e.g. `92000`
    - `p95_ms` — number, required. e.g. `405000`
    - `p99_ms` — number, required. e.g. `1200000`
    - `queue_wait_ms` — number, required. e.g. `16000`
    - `trend_pct` — number | null, required. e.g. `55.2`

### Example

```json
{
  "by": "workflow",
  "metric": "runner-minutes",
  "window": {
    "from": "2026-06-22T00:00:00.000Z",
    "to": "2026-07-22T00:00:00.000Z"
  },
  "rows": [
    {
      "key": "Prebuild",
      "repo": "hpc-sandbox-benchmarks",
      "runner_minutes": 66043.9,
      "cost_usd": 528.35,
      "runs": 37,
      "jobs": 1460,
      "p50_ms": 92000,
      "p95_ms": 405000,
      "p99_ms": 1200000,
      "queue_wait_ms": 16000,
      "trend_pct": 55.2
    },
    {
      "key": "CI",
      "repo": "api",
      "runner_minutes": 1240.5,
      "cost_usd": 9.92,
      "runs": 318,
      "jobs": 3816,
      "p50_ms": 41000,
      "p95_ms": 118000,
      "p99_ms": 240000,
      "queue_wait_ms": 4000,
      "trend_pct": null
    }
  ]
}
```