# Free usage

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

```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:

```sh
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](https://app.irondome.dev/usage).