> For the complete documentation index, see [llms.txt](https://diffio.ai/llms.txt). This page is also available as HTML at https://diffio.ai/docs/api-reference/usage-summary/.

# Get usage

Reports what your account's generations used in a UTC time window (`start` to `end`, defaulting to the current calendar month so far), in total and broken down `by_model` at list price.

GET `https://api.diffio.ai/v2/usage`

- Key scope: `usage:read`
- Auth header: `Authorization: Bearer <apiKey>`
- Body: None

120 s billed Example response

`diffio-4.7-flash`

60 s

`diffio-4.7-pro`

60 s

**`by_model[].billable_seconds`: whole seconds, at least 60 per restore.**

## Request

Pass optional `start` and `end` query parameters and optional `Diffio-End-User` header.

### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `start` | string | No | Optional ISO 8601 period start (`YYYY-MM-DD` for `00:00:00Z` or full timestamp; defaults to the start of the current UTC month). |
| `end` | string | No | Optional ISO 8601 period end (`YYYY-MM-DD` or full timestamp; must be after `start` and within `366` days; defaults to now). |

### Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `Diffio-End-User` | string | No | Optional end-user identifier (up to 128 characters). Narrows the usage report to generations belonging to that end user. |

## Example request

**Python**

```python
import os
from diffio import DiffioClient

key = os.environ["DIFFIO_API_KEY"]
client = DiffioClient(api_key=key)

usage = client.usage.get()
```

**Node.js**

```javascript
import { DiffioClient } from "diffio"

const client = new DiffioClient({
  apiKey: process.env.DIFFIO_API_KEY,
})

const usage = await client.usage.get()
```

**cURL**

```bash
curl "https://api.diffio.ai/v2/usage" \
  -H "Authorization: Bearer $DIFFIO_API_KEY"
```

## Response

Returns aggregated `generations`, `billable_seconds`, `list_price_usd`, and `by_model` totals.

Success: `200`

### Response fields

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `object` | string | Always | Resource type, always `"usage"`. |
| `start` | string \| null | Always | Effective UTC start of the reporting window (ISO 8601), or `null`. |
| `end` | string \| null | Always | Effective UTC end of the reporting window (ISO 8601), or `null`. |
| `end_user` | string \| null | Always | `Diffio-End-User` filter applied to this report, or `null` when reporting across the whole account. |
| `generations` | integer | Always | Total generations created in `[start, end)` (includes failed generations, which contribute `0` billable seconds). |
| `billable_seconds` | integer | Always | Total whole seconds billed: completed restores count at least `60` seconds each; transcript edits count `30` seconds per restored window with no minimum. |
| `list_price_usd` | number | Always | Total usage at each generation's list price rounded to 4 decimal places (not an invoice total; excludes starter credits or discounts). |
| `by_model` | array | Always | Per-model usage rows sorted by `model` name. [Fields below](#fields-by-model) |

**`by_model[]` fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `by_model[].model` | string | Always | Serving model ID (for example `diffio-4.7-flash` or `diffio-4.7-pro`). |
| `by_model[].generations` | integer | Always | Generations created for this model in the period. |
| `by_model[].billable_seconds` | integer | Always | Whole seconds billed for this model in the period. |
| `by_model[].list_price_usd` | number | Always | List-price USD total for this model rounded to 4 decimal places. |

## Example response (200)

**Successful response**

```json
{
  "object": "usage",
  "start": "2026-11-01T00:00:00Z",
  "end": "2026-11-13T00:34:08.146003Z",
  "end_user": null,
  "generations": 2,
  "billable_seconds": 120,
  "list_price_usd": 0.25,
  "by_model": [
    {
      "model": "diffio-4.7-flash",
      "generations": 1,
      "billable_seconds": 60,
      "list_price_usd": 0.0833
    },
    {
      "model": "diffio-4.7-pro",
      "generations": 1,
      "billable_seconds": 60,
      "list_price_usd": 0.1667
    }
  ]
}
```

## Return codes

- `200` Returns aggregated usage totals and per-model breakdown.
- `400`
  - Malformed `start` or `end`
  - `end <= start`
  - Window exceeds 366 days
  - Period spans more than 20,000 generations
  - Oversized header
  Codes: [`invalid_parameter`](https://diffio.ai/docs/api-reference/errors/#invalid_parameter), [`usage_period_too_large`](https://diffio.ai/docs/api-reference/errors/#usage_period_too_large), [`invalid_header`](https://diffio.ai/docs/api-reference/errors/#invalid_header)
- `403` Key is inactive or lacks `usage:read`. [`permission_denied`](https://diffio.ai/docs/api-reference/errors/#permission_denied)
- **`401` `405` Same on every endpoint**

  - `401` Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).
  - `405` HTTP method not supported on this path; check the Allow header (code method_not_allowed).

### Example error response

Errors are JSON: an `error` object with `code`, `message` and `request_id`. An unrecognized key returns `401`:

**Error response**

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key.",
    "request_id": "dead773b60e148fd9e22d680a22fa701"
  }
}
```

## Notes

- Pass `Diffio-End-User` to meter usage per customer in a multi-tenant product.
- `start` and `end` filter by each generation's creation timestamp (`[start, end)`), up to 366 days and 20,000 generations per query.
- `list_price_usd` reflects list rates (`price_per_hour_usd * billable_seconds / 3600`); see [Billing](https://diffio.ai/docs/overview/administration/billing/) for credit balances and invoices.

## Related pages

- Previous: [Get a share](https://diffio.ai/docs/api-reference/get-share/): Fetch a published share's playback metadata and signed media URLs without an API key.
- Next: [Open the webhook portal](https://diffio.ai/docs/api-reference/open-webhook-portal/): Create a short-lived login link to the hosted webhook portal to manage endpoints and secrets.

- [Billing](https://diffio.ai/docs/overview/administration/billing/): Starter credit, metering and invoices.
- [API pricing](https://diffio.ai/api-pricing/): The current rate per hour for each model.
