Skip to content

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

StatusBodyDescription
200Usage (application/json)OK
401Problem (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).
503Problem (application/problem+json)Database unavailable; retry after the Retry-After delay.
defaultProblem (application/problem+json)Any other error (405, 500, 504).

Response body

A 200 carries a Usage object.

FieldTypeRequiredDescription
as_ofdate-time (RFC 3339, UTC)yes
enforcementobjectyesEach feature: off, observe (counted and logged, never refused) or enforce.
keyobjectyes
key.bytesinteger | nullno
key.fingerprintstringnoFirst 12 hex digits of the key's SHA-256.
key.requestsinteger | nullno
limitsobject | nullyesNull while no limit is applied (metering off) and for a key without an organization.
limits.burstinteger | nullno
limits.exemptobject | nullnoNull, 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.concurrencybooleanno
limits.exempt.expires_atdate-time (RFC 3339, UTC) | nullnoWhen the exemption ends; null = no end set.
limits.exempt.ratebooleanno
limits.exempt.scopestringnokey: this key; org: every credential of the organization; config: the server's configuration. One of: key, org, config.
limits.monthly_bytesinteger | nullnoIncluded response bytes per month (measured before compression); null = unlimited.
limits.monthly_requestsinteger | nullno
limits.requests_per_secondinteger | nullnoNull while the caller is exempt from the rate limit.
monthstringyesThe month counted, YYYY-MM: the calendar month in New York time (America/New_York).
orgobjectyesThis month, all keys of the organization (a legacy key: that key). Null members while usage is not counted.
org.bytesinteger | nullnoBillable response bytes (5xx and 429 excluded).
org.bytes_remaininginteger | nullno
org.requestsinteger | nullno
org_idinteger | nullyesThe organization of the key; null for a legacy key not attributed to one.
planstring | nullyesThe organization's plan id; null when its entitlements are not known (default limits apply).
reset_atdate-time (RFC 3339, UTC)yesWhen the monthly allowance starts again: the start of the next month, midnight in New York (04:00 or 05:00 UTC).

Example request

Shell
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