API reference

Free usage

Read the shared monthly free allowance with GET /v1/usage at api.irondome.dev. Understand approximate counters and paid-context errors.

On this page

HTTP

GET /v1/usage

Request

Read the allowance for the free account context authorized by your key. Use the same API origin as email checks:

Terminal

curl 'https://api.irondome.dev/v1/usage' \
  --header "Authorization: Bearer $IRONDOME_API_KEY"

The response covers the organization that owns the key, including shared free-plan API and Supabase-hook usage. A paid context receives HTTP 403 free_usage_only; use the dashboard for paid usage.

Response

Example HTTP 200 response:

JSON

{
  "month": "2026-10",
  "limit": 500,
  "used": 37,
  "remaining": 463,
  "exhausted": false,
  "as_of": 1790935200,
  "approximate": true
}

Field	Meaning
`month`	Current UTC calendar month, `YYYY-MM`
`limit`	Monthly free allowance
`used`	Recorded checks for the month
`remaining`	Allowance remaining, with a minimum of zero
`exhausted`	Whether recorded usage has reached the allowance
`as_of`	Read time as Unix seconds
`approximate`	Usage may lag behind recent checks

Accounting

Usage is recorded asynchronously. Recent requests may not be visible yet, and concurrent requests can produce some quota overrun. used can exceed limit.

Do not fetch usage before every check. Read it when displaying an allowance or periodically when needed. Paid usage is available in the dashboard.