<!--
  immut documentation, machine-readable.

  Everything in one file:  https://www.immut.io/llms-full.txt
    What immut is, which integration path to choose, authentication and scopes, and the COMPLETE
    API reference: every endpoint with parameters, responses and a runnable curl. Fetch this first
    if you intend to call the API.

  Index of all pages:      https://www.immut.io/llms.txt
  OpenAPI contract:        https://www.immut.io/docs/openapi.json
  This page as HTML:       https://www.immut.io/docs/api/other/get-billing-usage

  Any page on this site is available as raw markdown by appending .md to its URL.
-->


# How much of the allowance this billing period has been used

`GET /billing/usage`

**Required scope:** `billing:read`

Use it before a large sweep so an agent can stop short of the limit rather than discovering it as a failed upload halfway through. Requires the billing:read scope, which is NOT granted to agent keys by default. This is read-only: nothing in the API changes a plan, buys seats or touches a payment method, and those stay in the app.

## Responses

| Status | Meaning |
|---|---|
| `200` | Success Returns: periodStart, periodEnd, and uploads {used, limit, remaining, quotaKind, byChannel}. byChannel is counted from the documents themselves over the same window, so it is real provenance rather than a running tally. A null periodStart means the plan has no billing window. |
| `400` | BadRequest |
| `401` | Unauthorized |
| `403` | Forbidden |
| `429` | RateLimited |

## Example

```bash
curl -X GET "https://backend.immut.io/api/v1/billing/usage" \
  -H "Authorization: Bearer $IMMUT_API_KEY"
```

## OpenAPI fragment

```json
{
  "/billing/usage": {
    "get": {
      "operationId": "getbillingusage",
      "summary": "How much of the allowance this billing period has been used. Use it before a large sweep so an agent can stop short of the limit rather than discovering it as a failed upload halfway through. Requires the billing:read scope, which is NOT granted to agent keys by default. This is read-only: nothing in the API changes a plan, buys seats or touches a payment method, and those stay in the app.",
      "description": "How much of the allowance this billing period has been used. Use it before a large sweep so an agent can stop short of the limit rather than discovering it as a failed upload halfway through. Requires the billing:read scope, which is NOT granted to agent keys by default. This is read-only: nothing in the API changes a plan, buys seats or touches a payment method, and those stay in the app.",
      "responses": {
        "200": {
          "description": "Success Returns: periodStart, periodEnd, and uploads {used, limit, remaining, quotaKind, byChannel}. byChannel is counted from the documents themselves over the same window, so it is real provenance rather than a running tally. A null periodStart means the plan has no billing window."
        },
        "400": {
          "$ref": "#/components/responses/BadRequest"
        },
        "401": {
          "$ref": "#/components/responses/Unauthorized"
        },
        "403": {
          "$ref": "#/components/responses/Forbidden"
        },
        "429": {
          "$ref": "#/components/responses/RateLimited"
        }
      },
      "x-required-scope": "billing:read"
    }
  }
}
```