For AI agents: every API docs page in one plain-text file is at /docs/llms-full.txt, and the documentation index is at /llms.txt. This page is available as Markdown at https://diffio.ai/docs/api-reference/usage-summary.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

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:/
- Key scope:
usage:read - Auth header:
Authorization: Bearer <apiKey> - Body: None
120 s billed Example response
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 | Required: 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 | Required: 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 | Required: No | Optional end-user identifier (up to 128 characters). Narrows the usage report to generations belonging to that end user. |
Request
import os
from diffio import DiffioClient
key = os.environ["DIFFIO_API_KEY"]
client = DiffioClient(api_key=key)
usage = client.usage.get()Response
Returns aggregated generations, billable_seconds, list_price_usd, and by_model totals.
Success: 200OK.
Response fields
| Field | Type | Present | Description |
|---|---|---|---|
#object | string | Always | Resource type, always "usage".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 |
by_model[] 4 fields
| Field | Type | Present | Description |
|---|---|---|---|
#by_model[] | string | Always | Serving model ID (for example diffio-4.7-flash or diffio-4.7-pro). |
#by_model[] | integer | Always | Generations created for this model in the period. |
#by_model[] | integer | Always | Whole seconds billed for this model in the period. |
#by_model[] | number | Always | List-price USD total for this model rounded to 4 decimal places. |
Response 200OK.
{
"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
200OK.Returns aggregated usage totals and per-model breakdown.400Bad request.Malformed
startorend, or 4 more causes- Malformed
startorend end <= start- Window exceeds 366 days
- Period spans more than 20,000 generations
- Oversized header
invalid_parameterusage_period_too_largeinvalid_header- Malformed
403Forbidden: the key lacks permission.Key is inactive or lacksusage:read.permission_denied401Unauthorized: the API key is missing or invalid.405Client error.Same on every endpoint401Unauthorized: the API key is missing or invalid. Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).405Client error. 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 401Unauthorized: the API key is missing or invalid.:
{
"error": {
"code": "invalid_api_key",
"message": "Invalid API key.",
"request_id": "dead773b60e148fd9e22d680a22fa701"
}
}Notes
- Pass
Diffio-End-Userto meter usage per customer in a multi-tenant product. startandendfilter by each generation's creation timestamp ([start, end)), up to 366 days and 20,000 generations per query.list_price_usdreflects list rates (price_per_hour_usd * billable_seconds / 3600); see Billing for credit balances and invoices.