Endpoint reference

`GET /api/usage`

Q: Can the used number disagree with what the rate limiter enforces?

No — by construction. /api/usage reads the same counter the enforcement middleware increments on every 2xx response. There is no separate analytics pipeline that could drift; the number you see is the number the 429 fires on.

Q: Is there a no-code way to see my usage?

Yes — the dashboard at https://pdfops.dev/dashboard. Paste your key and it renders the same tier / used / remaining / reset numbers this endpoint returns.

Self-serve quota visibility for keyed callers: tier, limit, used, remaining, current period, and reset date for the key you pass. Prefer a browser? The dashboard renders the same numbers — paste your key, no code.

Request

Method: GET. URL: https://pdfops.dev/api/usage. No body.

Header	Required	Description
`X-API-Key`	Yes	Your API key (from `POST /api/signup` or a paid tier at /pricing).

Response

On success: 200 OK, Content-Type: application/json:

{
  "tier": "free",
  "limit": 250,
  "used": 41,
  "remaining": 209,
  "period": "2026-07",
  "resets_at": "2026-08-01T00:00:00.000Z"
}

Field	Type	Meaning
`tier`	string	`free`, `indie`, or `pro`.
`limit`	number	Your tier's monthly quota: 250 (free), 4,000 (indie), 25,000 (pro).
`used`	number	Successful (2xx) requests consumed this period. Reads the same counter the rate limiter increments — by construction, the number you see is the number the 429 fires on. There's no second bookkeeping to drift.
`remaining`	number	`max(0, limit − used)`.
`period`	string	Current UTC calendar month, e.g. `2026-07`.
`resets_at`	string	ISO timestamp of the 1st of next month, 00:00 UTC — when the counter resets.

Error codes

Error code	Status	Trigger
`missing_api_key`	401	No `X-API-Key` header. Unlike the PDF endpoints, `/api/usage` has no anonymous mode — there's no key to report on.
`invalid_api_key`	401	The key is unknown or revoked (e.g. rotated by a later signup). Get a fresh one at /pricing.

Calls to /api/usage don't consume quota — only 2xx responses from the PDF endpoints (/api/fill-form, /api/merge) do.

Example — curl

curl https://pdfops.dev/api/usage \
  -H "X-API-Key: pdfops_live_..."

FAQ

Does calling /api/usage consume my quota?

No. Quota is consumed only by successful (2xx) responses from the PDF endpoints. Poll /api/usage as often as you like.

Can the used number disagree with what the rate limiter enforces?

No — by construction. /api/usage reads the same counter the enforcement middleware increments on every 2xx response. There's no separate analytics pipeline that could drift; the number you see is the number the 429 fires on.

Why am I getting 401 invalid_api_key on a key that worked before?

The key was revoked — most commonly because someone re-signed up with the same email, which rotates the key (revokes the old, emails a new one). Check the inbox for a newer key email, or POST /api/signup again for a fresh key.

Is there a no-code way to see my usage?

Yes — the dashboard. Paste your key and it renders the same tier / used / remaining / reset numbers this endpoint returns.

← All docs · PDFops home