API reference

Usage summary

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

Read restored audio seconds per month and model for an API key, plus the account billing state.

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 billable seconds for the current and previous calendar month, grouped by model, plus the account billing state. Charges, credits and invoices are in the developer dashboard billing pages.

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	Calendar months with usage, sorted by periodStart descending.
`usage.periods[].periodId`	string	Yes	Month id in YYYY-MM form.
`usage.periods[].seconds`	number	Yes	Billable seconds in the month (each generation bills whole seconds, at least 60).
`usage.periods[].modelSeconds`	object	Yes	Billable seconds grouped by model key.
`billing`	object	Yes	Account billing state.
`billing.billingPolicy`	object	Yes	Account billing policy.
`billing.billingMode`	string	Yes	free until a payment method is saved, then developer.
`billing.billingStatus`	string	Yes	active, or blocked when the starter credit is used up without a payment method or a payment failed.

Successful response

{  "usage": {    "apiKeyId": "key_123",    "periods": [      {        "periodId": "2026-10",        "apiKeyId": "key_123",        "periodStart": "2026-10-01T00:00:00Z",        "periodEnd": "2026-11-01T00:00:00Z",        "seconds": 180,        "modelSeconds": {          "diffio-4.5-flash": 120,          "diffio-4.5-pro": 60        }      }    ]  },  "billing": {    "billingPolicy": {      "type": "customerStripe"    },    "billingMode": "developer",    "billingStatus": "active"  }}

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 not linked to an account, 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.