> ## Documentation Index
> Fetch the complete documentation index at: https://docs.get-exo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

> Bucketed metering you can reconcile against your own billing.

## What this family does

`GET /v1/usage` returns metered units bucketed over a time window and grouped by subject, key or capability, so a developer reselling Exo to their own users can attribute cost per end user.

Buckets are aligned to `startTime`, and only non-empty buckets come back. A range with no usage is an empty list with a 200.

## Routes

| Method | Path                                          | Scope        | What it does            |
| ------ | --------------------------------------------- | ------------ | ----------------------- |
| `GET`  | [`/v1/usage`](/api-reference/usage/get-usage) | `usage:read` | Bucketed usage metering |

## The shape of a call

Read metered usage.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl "https://api.get-exo.com/v1/usage?startTime=2026-07-01T00:00:00Z&endTime=2026-08-01T00:00:00Z&groupBy=subject" \
    -H "X-Exo-API-Key: $EXO_KEY"
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import httpx

  response = httpx.get(
      "https://api.get-exo.com/v1/usage",
      headers={"X-Exo-API-Key": EXO_KEY},
      params={
          "startTime": "2026-07-01T00:00:00Z",
          "endTime": "2026-08-01T00:00:00Z",
          "groupBy": "subject",
      },
  )
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const params = new URLSearchParams({
    startTime: "2026-07-01T00:00:00Z",
    endTime: "2026-08-01T00:00:00Z",
    groupBy: "subject",
  });
  const response = await fetch(`https://api.get-exo.com/v1/usage?${params}`, {
    headers: { "X-Exo-API-Key": process.env.EXO_KEY! },
  });
  ```
</CodeGroup>

The response:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "buckets": [
    {
      "startTime": "2026-07-01T00:00:00Z",
      "endTime": "2026-07-02T00:00:00Z",
      "groups": [
        { "subject": "customer_6412", "capability": null, "units": { "readUnits": 412, "embedTokens": 1840 } }
      ]
    }
  ]
}
```

## Traps

**This is an organization-wide view.** It aggregates every subject, so it requires `usage:read`. An `admin` key also qualifies. A plain `read` key is refused.

**Grouping by subject uses your own subject keys.** Usage recorded for the key owner is grouped separately from usage recorded for a provisioned subject.

## Related

<Columns cols={2}>
  <Card title="API reference" icon="book-open" href="/api-reference/overview">
    Base URL, authentication, and the conventions every route shares.
  </Card>

  <Card title="Errors" icon="circle-alert" href="/platform/errors">
    The problem envelope and the full code catalogue.
  </Card>
</Columns>