Metering

One token is charged per returned data row, minimum one token per request, so a 200 with an empty results array still costs one token. The isochrone is the exception: it charges 10 tokens per contour level (1–4 per call), regardless of format. A 304 Not Modified costs nothing.

Every metered response carries:

Header	Meaning
X-Tokens-Charged	Tokens charged for this request
X-Tokens-Remaining	Balance after this request
X-Request-Id	Correlation id (quote it in support requests)

When the balance reaches zero, requests return 429 with problem type tokens-exhausted. You can see your token balance and buy more tokens at account.close.city.

What things cost

Tokens are rows, so the cost of a call is the number of rows it returns. That gives you three levers: the modes, the destination types, and the blocks a query touches. A summary of a single block is a handful of rows; an areal query over a city is thousands. A few rules of thumb:

Call	Rows returned	Typical cost
A block or point summary	one per (category, mode)	tens of tokens
A POI search or a block’s POIs	one per matching POI	tens to a few hundred
A POI catchment (poi_catchment)	one per reachable block	hundreds
An areal block query (blocks_query)	one per (block, category, mode)	hundreds to thousands
Any isochrone	flat	10 per contour level

The isochrone is the cheap way to ask “how far can I get”: a whole 30-minute walkshed is 10 tokens as format=blocks, where the equivalent block query charges per block. See Efficient token use for the full playbook.

Rate limits

Each account may make up to 300 requests per minute. Over that, requests return 429 with problem type rate-limited and a Retry-After header; the SDKs surface it as RateLimitedError (Python) or a close_api_rate_limited condition (R). The paginators default to 100 rows per page and accept up to 1000, so reading with limit=1000 keeps you far under the limit. Very large bursts may also be shed at the gateway; back off and retry when you see a 429.

Getting tokens

New accounts receive a one-time signup grant of 5,000 tokens on email verification, and you can buy token packs (10,000 tokens for $10) as one-time purchases at any time.

Close+, the $10/month membership for the close.city map, also grants 10,000 API tokens each paid month, added to your balance while you are a member. Cancel anytime. Tokens you have already been granted stay on your account.

The SDKs surface X-Tokens-Charged / X-Tokens-Remaining on every reply, so you can watch the balance as you page.