> ## Documentation Index
> Fetch the complete documentation index at: https://docs.checkthatfield.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quotas and limits

> Your monthly quota, what counts as a call, the per-minute limit, and the 15-second cap.

Each key has two limits: a **monthly quota** of calls, and a **rate limit** of 600 calls a minute. Each request is also stopped if its search takes too long.

## The monthly quota

We set your key's quota when we make it. It counts calls to every endpoint: `/v1/scores`, `/v1/fields/{field_id}` and `/v1/usage`.

> [!NOTE]
>
> Only answers count. A call that fails (a typo, an unknown postcode, a `404`, a `422`, a search that took too long) is given back. Calls refused for the key, the quota or the rate limit aren't counted either.

The month is the calendar month in UTC. Your count starts again at 00:00 UTC on the 1st of each month.

The quota holds exactly, even under load. Calls made at the same moment are counted one at a time, so they can't go past it.

### Seeing what's left

Answers from `/v1/scores`, `/v1/fields/{field_id}` and `/v1/usage` carry two headers:

| Header | Meaning |
| - | - |
| `X-Quota-Limit` | Calls allowed a month |
| `X-Quota-Remaining` | Calls left this month, after this one |

Or ask `/v1/usage`. It doesn't count as a call, and it still answers when the month's calls are used up:

```bash theme={null}
curl -H "Authorization: Bearer $CTF_KEY" "https://api.checkthatfield.com/v1/usage"
```

```json theme={null}
{
  "month": "2026-11",
  "calls": 1240,
  "quota": 10000,
  "remaining": 8760,
  "resets_at": "2026-12-01T00:00:00+00:00"
}
```

**month** `string`

The calendar month counted, `YYYY-MM`, in UTC.

**calls** `integer`

Calls answered this month.

**quota** `integer`

Calls allowed a month.

**remaining** `integer`

Calls left this month.

**resets\_at** `string`

When the count starts again, in UTC.

### When the quota runs out

Every call, `/v1/usage` included, gets `429 quota_exceeded` until the month ends. The `Retry-After` header gives the seconds until 00:00 UTC on the 1st. If you need more calls, email [hello@checkthatfield.com](mailto:hello@checkthatfield.com).

## The rate limit

Each key may make 600 calls a minute. The count is kept in fixed one-minute windows. Past it, calls get `429 rate_limited`, with a `Retry-After` header giving the seconds until the window ends.

> [!TIP]
>
> On a `429`, wait for `Retry-After` seconds before trying again. Calls made while limited still count towards the window, so retrying at once keeps you limited.

```python theme={null}
import time
import requests

def get(url, **kwargs):
    while True:
        r = requests.get(url, **kwargs)
        if r.status_code == 429 and r.json()["error"]["code"] == "rate_limited":
            time.sleep(int(r.headers.get("Retry-After", "60")))
            continue
        return r
```

Don't retry `quota_exceeded` this way: its `Retry-After` can be weeks.

## The 15-second cap

Each database query behind a request may take at most 15 seconds. A search that goes over is stopped and answered `503 too_slow`, and isn't counted against your quota.

It is most likely around the edge of a big town or city, with a wide radius. To avoid it:

* ask with a postcode or a point instead of a town's name
* use a smaller `radius_m`
* ask for fewer fields with `limit`

## Request bounds

| Parameter | Default | Bounds |
| - | - | - |
| `radius_m` | 500 | 50 to 1,000 metres |
| `limit` | 20 | 1 to 60 fields |
| `postcode` | | at most 20 characters |
| `q` | | at most 200 characters |
| `lat` | | 49 to 61 |
| `lng` | | −10 to 3 |

Values outside these get `422 bad_request`. `/v1/scores` returns at most 50 housing applications, newest first.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.