API REFERENCE

API key usage

Read lifetime input, output, cached, and total token counts for your API key or, by key identifier, with a management key.

Read lifetime usage

Read lifetime recorded token usage for the API key used to authenticate the request.

curl https://api.netraruntime.com/v1/usage \
  -H "Authorization: Bearer $NETRA_API_KEY"

{
  "key_id": "0123456789ABCDEF",
  "period": "lifetime",
  "input_tokens": "12000",
  "output_tokens": "3000",
  "cached_tokens": "8000",
  "total_tokens": "15000",
  "as_of": "2026-11-04T10:00:00Z"
}

Read usage by key identifier

An organization management key can read recorded usage for any inference key in the same organization by its keyid. The inference key's secret is never sent, so reporting and reconciliation jobs can cover every key, including revoked and expired ones, without storing workload secrets.

curl https://api.netra.sh/v1/management/api-keys/4c8e0b91a2f7d635/usage \
  -H "Authorization: Bearer $NETRA_MANAGEMENT_KEY"

{
  "keyid": "4c8e0b91a2f7d635",
  "as_of": "2026-11-12T09:05:31.442Z",
  "budget_mode": "credit",
  "budget_period": "monthly",
  "token_budget_scope": "all",
  "reported_lifetime": {
    "input_tokens": "184320",
    "output_tokens": "51200",
    "cached_tokens": "0",
    "total_tokens": "235520",
    "as_of": "2026-11-12T09:05:31.442Z"
  },
  "lifetime": {
    "input_tokens": "184320",
    "output_tokens": "51200",
    "total_tokens": "235520"
  },
  "allowance": {
    "unit": "usd_nanos",
    "cap": "2000000000000",
    "used": "173500000",
    "reserved": "0",
    "remaining": "1999826500000",
    "status": "available",
    "reset_at": null
  }
}

The keyid is the 16-character identifier that the list and create calls return for each inference key; it is never the secret and it does not change when a secret is regenerated. lifetime holds durable settlement totals, while allowance counts the current budget period instead: the current UTC month for a monthly budget, or all recorded usage for a fixed one. The two therefore differ after a reset, which clears allowance consumption but not history. Amounts and counts are decimal strings, and a null cap or remaining value means unlimited.

Only the exact path is accepted; query parameters are rejected with 400. An unknown key, or a key in another organization, returns 404 rather than revealing that it exists. Invalid, expired, revoked, or no-longer-authorized management credentials return 401; a management key without Observe returns 403. Observe is always included in a management key, so reading usage never requires Create, Revoke, or any other write permission. See the Management API reference for the full lifecycle, and use GET /v1/usage below when the inference key reads only its own counts.

Response fields

Field	Meaning
`key_id`	The authenticated key's identifier, never its secret.
`period`	Always `lifetime`: all recorded usage for this key in its workspace.
`input_tokens`	Input tokens, including cached input.
`output_tokens`	Output tokens, including reasoning when reported.
`cached_tokens`	Cached input tokens already included in `input_tokens`. Historical records without cache counts contribute zero cached tokens.
`total_tokens`	Input plus output. Do not add cached tokens again.
`as_of`	UTC timestamp of the reporting snapshot, not a guarantee that all in-flight or queued usage has settled.

Counts are decimal strings to preserve exact integers. Use BigInt(value) in JavaScript or int(value) in Python. A key with no recorded usage returns "0" for every count. Counts reflect recorded metering, which can include estimated usage when upstream counts were unavailable.

Access, limits, and errors

This read does not run inference, consume credit, or count toward token budgets. It remains available when an inference budget is exhausted. It is limited to 30 reads per minute per key; poll no more frequently than once a minute. Recent requests can take time to appear after settlement. This is lifetime reporting, not the current month's budget counter.

On GET /v1/usage, no body, query parameters, key selector, or on-behalf-of headers are supported. Use a direct, active API key. A key can read only its own usage; it cannot list other keys or inspect another workspace. Revoked or expired keys cannot authenticate. Workspace owners and admins can still inspect revoked keys' recorded usage in API Keys in the dashboard, and can read it by keyid with a management key as described above.

Errors use the normal API error envelope: 401 for invalid, expired, revoked, or unauthorized credentials; 400 for unsupported query parameters or delegation; 405 for methods other than GET; 429 for the read limit; and 503 when authentication or reporting is unavailable. Treat unavailable data as an error, not zero usage. Responses use Cache-Control: no-store.