Skip to content

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://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

FieldTypeRequiredDescription
#startstringRequired: NoOptional ISO 8601 period start (YYYY-MM-DD for 00:00:00Z or full timestamp; defaults to the start of the current UTC month).
#endstringRequired: NoOptional ISO 8601 period end (YYYY-MM-DD or full timestamp; must be after start and within 366 days; defaults to now).

Headers

FieldTypeRequiredDescription
#Diffio-End-UserstringRequired: NoOptional 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

FieldTypePresentDescription
#objectstringAlwaysResource type, always "usage".usage
#startstring | nullAlwaysEffective UTC start of the reporting window (ISO 8601), or null.
#endstring | nullAlwaysEffective UTC end of the reporting window (ISO 8601), or null.
#end_userstring | nullAlwaysDiffio-End-User filter applied to this report, or null when reporting across the whole account.
#generationsintegerAlwaysTotal generations created in [start, end) (includes failed generations, which contribute 0 billable seconds).
#billable_secondsintegerAlwaysTotal whole seconds billed: completed restores count at least 60 seconds each; transcript edits count 30 seconds per restored window with no minimum.
#list_price_usdnumberAlwaysTotal usage at each generation's list price rounded to 4 decimal places (not an invoice total; excludes starter credits or discounts).
#by_modelarrayAlwaysPer-model usage rows sorted by model name.Fields below
by_model[] 4 fields
FieldTypePresentDescription
#by_model[].modelstringAlwaysServing model ID (for example diffio-4.7-flash or diffio-4.7-pro).
#by_model[].generationsintegerAlwaysGenerations created for this model in the period.
#by_model[].billable_secondsintegerAlwaysWhole seconds billed for this model in the period.
#by_model[].list_price_usdnumberAlwaysList-price USD total for this model rounded to 4 decimal places.

Response 200OK.

Successful response
{
  "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 start or end, or 4 more causes
    • Malformed start or end
    • end <= start
    • Window exceeds 366 days
    • Period spans more than 20,000 generations
    • Oversized header
    invalid_parameterusage_period_too_largeinvalid_header
  • 403Forbidden: the key lacks permission.Key is inactive or lacks usage:read. permission_denied
  • 401Unauthorized: the API key is missing or invalid.405Client error.Same on every endpoint
    • 401Unauthorized: 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 response
{
  "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 for credit balances and invoices.

Report an issue with this page