GET /v3/usage
The calling key's limits and this month's usage: requests and billable response bytes (measured before compression; 5xx and 429 not billable) of its organization and of the key itself, what is left of the monthly allowance, when it starts again, and which limits are enforced. Never refused for an exhausted allowance. Every authenticated answer of the API may carry RateLimit-Policy and RateLimit (draft-ietf-httpapi-ratelimit-headers) and X-Quota-* headers while those limits are enforced; over a limit the answer is 429 with code rate_limited (per-second rate, Retry-After) or quota_exceeded (monthly allowance), and 403 with code blocked for a suspended organization.
API key: required. See Authentication.
Group: Coverage, usage and service
Parameters
This route takes no parameters.
Responses
| Status | Body | Description |
|---|---|---|
200 | Usage (application/json) | OK |
401 | Problem (application/problem+json) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). |
503 | Problem (application/problem+json) | Database unavailable; retry after the Retry-After delay. |
default | Problem (application/problem+json) | Any other error (405, 500, 504). |
Response body
A 200 carries a Usage object.
| Field | Type | Required | Description |
|---|---|---|---|
as_of | date-time (RFC 3339, UTC) | yes | |
enforcement | object | yes | Each feature: off, observe (counted and logged, never refused) or enforce. |
key | object | yes | |
key.bytes | integer | null | no | |
key.fingerprint | string | no | First 12 hex digits of the key's SHA-256. |
key.requests | integer | null | no | |
limits | object | null | yes | Null while no limit is applied (metering off) and for a key without an organization. |
limits.burst | integer | null | no | |
limits.exempt | object | null | no | Null, or the caller's exemption from the rate limit (and, when concurrency is true, from the concurrency cap). The transfer allowance still applies. |
limits.exempt.concurrency | boolean | no | |
limits.exempt.expires_at | date-time (RFC 3339, UTC) | null | no | When the exemption ends; null = no end set. |
limits.exempt.rate | boolean | no | |
limits.exempt.scope | string | no | key: this key; org: every credential of the organization; config: the server's configuration. One of: key, org, config. |
limits.monthly_bytes | integer | null | no | Included response bytes per month (measured before compression); null = unlimited. |
limits.monthly_requests | integer | null | no | |
limits.requests_per_second | integer | null | no | Null while the caller is exempt from the rate limit. |
month | string | yes | The month counted, YYYY-MM: the calendar month in New York time (America/New_York). |
org | object | yes | This month, all keys of the organization (a legacy key: that key). Null members while usage is not counted. |
org.bytes | integer | null | no | Billable response bytes (5xx and 429 excluded). |
org.bytes_remaining | integer | null | no | |
org.requests | integer | null | no | |
org_id | integer | null | yes | The organization of the key; null for a legacy key not attributed to one. |
plan | string | null | yes | The organization's plan id; null when its entitlements are not known (default limits apply). |
reset_at | date-time (RFC 3339, UTC) | yes | When the monthly allowance starts again: the start of the next month, midnight in New York (04:00 or 05:00 UTC). |
Example request
curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \
'https://api.secblast.com/v3/usage'Open this route in the console
More in Coverage, usage and service
Previous: GET /v3/openapi.json
Markdown version: /docs/reference/get-usage.md