API reference

Usage summary

Return usage periods and account billing counters. Review Diffio API behavior, response fields, setup details, and production workflows.

Read API usage period totals and account-level billing counters.

POST/v1/usage/summaryPermissions: usage:read

Endpoint

HTTP request

https://api.diffio.ai/v1/usage/summary

Use POST with a JSON body.

Permissions

usage:read

API keys must be active.

Authentication

Send the API key on every request using one of the supported headers.

Authorization: Bearer <apiKey>
X-Api-Key: <apiKey>
Xi-Api-Key: <apiKey>

Request

Send an empty object for the authenticated key, or apiKeyId when an admin key reads another key on the same account.

Body fields

Field	Type	Required	Description
`apiKeyId`	string	No	Optional API key id to read. Non-admin keys can only read their own usage.

cURL

curl -X POST "https://api.diffio.ai/v1/usage/summary" \  -H "Authorization: Bearer $DIFFIO_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "apiKeyId": "key_123"  }'

Response

Returns usage periods plus billing counters for the account.

Response fields

Field	Type	Required	Description
`usage`	object	Yes	Usage summary for the requested API key.
`usage.apiKeyId`	string	Yes	API key id whose usage was returned.
`usage.periods`	array	Yes	Usage periods sorted by periodStart descending.
`usage.periods[].periodId`	string	Yes	Usage period id.
`usage.periods[].reservedCents`	number	Yes	Reserved usage cents for the period.
`usage.periods[].finalizedCents`	number	Yes	Finalized usage cents for the period.
`usage.periods[].totalCents`	number	Yes	Total reserved and finalized cents for the period.
`usage.periods[].modelSeconds`	object	Yes	Usage seconds grouped by model key.
`usage.periods[].modelCents`	object	Yes	Usage cents grouped by model key.
`billing`	object	Yes	Account billing counters.
`billing.billingPolicy`	object	Yes	Account billing policy.
`billing.lifetimeListPriceCents`	number	Yes	Lifetime list price usage in cents.
`billing.lifetimeBillableCents`	number	Yes	Lifetime billable usage in cents.
`billing.unbilledCents`	number	Yes	Current unbilled cents on the account.

Successful response

{  "usage": {    "apiKeyId": "key_123",    "periods": [      {        "periodId": "period_2026_05",        "apiKeyId": "key_123",        "periodStart": "2026-05-01T00:00:00Z",        "periodEnd": "2026-06-01T00:00:00Z",        "reservedCents": 100,        "finalizedCents": 200,        "totalCents": 300,        "modelSeconds": {          "diffio-2": 120        },        "modelCents": {          "diffio-2": 300        }      }    ]  },  "billing": {    "billingPolicy": {      "type": "customerStripe"    },    "lifetimeListPriceCents": 300,    "lifetimeInternalAppliedCents": 0,    "lifetimeBillableCents": 300,    "unbilledCents": 300  }}

Return codes

200Success, treated as complete.: Usage summary returned.
204Success, treated as empty response.: CORS preflight when method is OPTIONS.
400Bad request, treated as client error.: Invalid JSON body.
401Unauthorized, treated as auth error.: Missing API key, or invalid API key.
403Forbidden, treated as permission error.: API key is not active, missing usage:read permission, or a non-admin key requested another apiKeyId.
405Client error, treated as fix required.: Method is not POST.
500Server error, treated as retryable.: API key missing userId, or failed to read usage summary.

Notes

When apiKeyId is omitted, the endpoint returns usage for the authenticated key.
Only admin keys can request usage for another key id.
Usage periods are read from api_key_usage/{apiKeyId}/periods in the API Firestore database.