# Billing snapshot for a period (/api/bill/get-bill)

`GET /api/bill`

Read-only budget check. With no month, it returns the current open billing period: runner minutes, cost, credits, amount due, per-label line items, and a projected month-end total. Pass month=YYYY-MM to check a past period — a closed month returns its finalized Stripe invoice, or an in-house estimate when no invoice covers it. Scoped to the caller's orgs. Plan/payment changes stay in the dashboard.

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 the bill belongs to. e.g. `acme` |
| `month` | query | string | no | A finalized month, YYYY-MM. Omit for the current open period. e.g. `2026-06` |

## Responses

| Status | Description |
| --- | --- |
| `200` | The billing period's spend, credits, and line items. Open unless a month was named. |
| `400` | `month` isn't a YYYY-MM calendar month. |
| `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. Distinct from a month with no usage, which is a 200 with zeroes. |
| `422` | A path or query parameter failed schema validation. `details` names each offending field. |
| `500` | The request was valid; the control plane or a dependency it calls failed. |

### `200` body

- `invoice_id` — string. e.g. `in_1ToVfTFSjWlUgKNB`
- `period` — object, required
  - `from` — string, required. e.g. `2026-07-01T00:00:00.000Z`
  - `to` — string, required. e.g. `2026-08-01T00:00:00.000Z`
- `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
  - array of object
    - `label` — string, required. e.g. `starsling-ubuntu-24.04-8`
    - `minutes` — number, required. e.g. `1240.5`
    - `usd` — number, required. e.g. `19.85`
- `projected_month_end_usd` — number, required. e.g. `92.4`

### Example

```json
{
  "period": {
    "from": "2026-07-12T00:00:00.000Z",
    "to": "2026-08-12T00:00:00.000Z"
  },
  "status": "open",
  "period_source": "install_cycle",
  "runner_minutes": 2910,
  "amount_usd": 46.56,
  "credits_usd": 8,
  "amount_due_usd": 38.56,
  "free_credit_total_usd": 8,
  "free_credit_remaining_usd": 0,
  "line_items": [
    {
      "label": "starsling-ubuntu-24.04-8",
      "minutes": 2910,
      "usd": 46.56
    }
  ],
  "projected_month_end_usd": 92.4
}
```