---
title: "API keys · API v1"
description: "How much of the hourly budget the organization's keys have used."
---
# API keys

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: `read`, `full`

### Query parameters

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

### Example request

```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. |
| `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. |
| `verdict` | `object` | How close the organization is to its quota, already decided. |
| `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. |
| `points` | `object[]` (nullable) | Request history over the window, oldest first, one point per bucket. |
| `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. |
| `keys` | `object[]` (nullable) | Each key's share of the window's requests. |
| `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. |
| `api_base_url` | `string` | The base URL this deployment serves the API on. |

### 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: https://dmarcguard.io/docs/api/v1/#errors