API keys · API v1

How much of the hourly budget the organization's keys have used.

API usage

GET /api-keys/usage

The organization's current hourly window, a verdict on how close it is to the quota, a request history (hourly points for a window of two days or less, daily beyond) and the share attributed to each key. Poll this instead of parsing headers when you want the trend.

Permission integration:read
Key scope readfull

Query parameters

Name	Type	Description
`days`	`integer`	History window in days, 1 to 90. Default 30.

Example request

curl bash

curl "https://api.dmarcguard.io/api/v1/api-keys/usage" \
  -H "Authorization: Bearer dg_your_key"

Response

Field	Type	Notes
`days`	`integer`	Length of the charted window in days, as applied.
`bucket`	`string`	How wide each history point is: hour for a short window, day for a longer one.
`window`	`object`	The hour being metered right now.
`verdict`	`object`	How close the organization is to its quota, already decided.
`points`	`object[]` nullable	Request history over the window, oldest first, one point per bucket.
`keys`	`object[]` nullable	Each key's share of the window's requests.
`api_base_url`	`string`	The base URL this deployment serves the API on.

Field	Type	Notes
`window.used`	`integer`	Requests counted so far in the current hour.
`window.remaining`	`integer`	Requests left in the current hour, or -1 when the organization has no cap.
`window.limit`	`integer`	Requests allowed per hour, or 0 when the organization has no cap.
`window.reset_at`	`string` nullable	RFC 3339 UTC instant with whole seconds, e.g. 2026-09-15T16:03:43Z; null when absent.

Field	Type	Notes
`verdict.state`	`string`	no_traffic before the first request, capped when requests were refused anywhere in the charted window, near_cap when the hour is nearly spent, unlimited when the organization has no cap, ok otherwise.
`verdict.summary`	`string`	A ready-to-show sentence for the state.

Field	Type	Notes
`points[].ts`	`string` nullable	RFC 3339 UTC instant with whole seconds, e.g. 2026-09-15T16:03:43Z; null when absent.
`points[].allowed`	`integer`	Requests served in this bucket.
`points[].rejected`	`integer`	Requests refused in this bucket because a limit was already spent.

Field	Type	Notes
`keys[].id`	`string`	Identifier, Crockford Base32. Opaque; never parse it as a number.
`keys[].name`	`string`	The name the key was created with.
`keys[].prefix`	`string`	The key's leading characters, enough to recognise it without revealing it.
`keys[].allowed`	`integer`	Requests this key had served over the window.
`keys[].rejected`	`integer`	Requests this key had refused over the window.
`keys[].revoked`	`boolean`	True once the key was revoked; its past usage still shows here.
`keys[].last_used_at`	`string` nullable	RFC 3339 UTC instant with whole seconds, e.g. 2026-09-15T16:03:43Z; null when absent.

Errors

Status	When
`400`	days is outside 1 to 90.
`401`	Missing, malformed, revoked, expired or not-entitled API key.
`403`	The key's scope or its owner's role does not allow this operation.
`429`	Hourly quota or an abuse limit exceeded; the body's code says which. Honour Retry-After.
`500`	Unexpected server error; retry with backoff.
`503`	The organization's plan could not be resolved; retry shortly.

Plus the errors every request can return.