# List prior invoices (/api/bill/get-bill-history)

`GET /api/bill/history`

Read-only list of the caller's prior finalized invoices (newest first), same per-item shape as /api/bill, paginated by count. 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 whose invoices to list. e.g. `acme` |
| `limit` | query | string \| integer | no | Invoices per page, newest first. 1–100; e.g. `6` |
| `after` | query | string | no | Invoice id from a prior page — returns the ones after it. e.g. `in_1ToVfTFSjWlUgKNB` |

## Responses

| Status | Description |
| --- | --- |
| `200` | Prior finalized invoices, newest first. Page with `after`. |
| `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 `bill:read`. |
| `404` | The org has no billing record — it has never started a subscription. An org that simply has no finalized invoices yet is a 200 with an empty list. |
| `422` | A query parameter failed schema validation — most often a `limit` outside 1-100. `details` names the offending field. |
| `500` | The request was valid; the control plane or a dependency it calls failed. |

### `200` body

- `invoices` — array<object>, required
  - array of object
    - `invoice_id` — string. e.g. `in_1ToVfTFSjWlUgKNB`
    - `period` — object, required
    - `status` — string, required. e.g. `open`
    - `period_source` — string, required. `stripe`, `install_cycle`, `calendar_month`, `explicit`
    - `runner_minutes` — number, required. e.g. `5820`
    - `amount_usd` — number, required. e.g. `46.56`
    - `credits_usd` — number, required. e.g. `8`
    - `amount_due_usd` — number, required. e.g. `38.56`
    - `free_credit_total_usd` — number. e.g. `8`
    - `free_credit_remaining_usd` — number. e.g. `7.95`
    - `line_items` — array<object>, required
    - `projected_month_end_usd` — number, required. e.g. `92.4`
- `has_more` — boolean, required

### Example

```json
{
  "invoices": [
    {
      "invoice_id": "in_1ToVfTFSjWlUgKNB",
      "period": {
        "from": "2026-06-12T00:00:00.000Z",
        "to": "2026-07-12T00:00:00.000Z"
      },
      "status": "paid",
      "period_source": "stripe",
      "runner_minutes": 5820,
      "amount_usd": 93.12,
      "credits_usd": 0,
      "amount_due_usd": 93.12,
      "line_items": [
        {
          "label": "starsling-ubuntu-24.04-8",
          "minutes": 5820,
          "usd": 93.12
        }
      ],
      "projected_month_end_usd": 93.12
    }
  ],
  "has_more": false
}
```