Limits and usage windows
The Casafari API and MCP Platform limits how fast and how much an account can call, per plan. This page lists those limits. They are the limits that clause 7.4 of the Terms of Use refers to when it says they are published in the Documentation. They apply over REST and MCP alike, and they are separate from what each call costs in tokens.
Limits per plan
| Limit | Free | Agent | Agency | Custom |
|---|---|---|---|---|
| Tokens | 1,000 for 30 days, at most 500 per rolling 3 hours | 1,500 a month, at most 600 per rolling 3 hours | 5,000 a month, at most 2,000 per rolling 3 hours | As agreed |
| Requests a minute | 10 | 20 | 20 | As agreed |
| Requests in flight at once | 2 | 3 | 3 | As agreed |
| Distinct places a day | 10 | 50 | 50 | As agreed |
| Requests per rolling 3 hours | 50 | No limit | No limit | As agreed |
| Requests a day | 100 | No limit | No limit | As agreed |
| Requests per rolling 7 days | 300 | No limit | No limit | As agreed |
| Tokens a day (hard daily cap) | 1,000 | 50,000 | 50,000 | As agreed |
| Page size | 25 results | Each operation's own maximum | Each operation's own maximum | As agreed |
| Page depth | 100 results (4 pages) of one search | Each operation's own maximum | Each operation's own maximum | As agreed |
| Spending cap on credits | Not applicable | 25,000 tokens per subscription period | 25,000 tokens per subscription period | As agreed |
| Members, API keys, OAuth clients | 1, 2, 2 | 1, 3, 3 | 5, 10, 10 | As agreed |
Prices are on Pricing.
How to read it:
- A day runs from 00:00 UTC, and a minute is the current UTC minute. The rolling windows move continuously: usage leaves a window 3 hours or 7 days after it was made.
- Requests count whether or not they cost tokens: free calls such as place lookups (
locations_search), refunded calls and calls refused for payment all count. Two calls never count, so an agent can always see where it stands and finish a payment: the account status check (account_status,GET /v1/account) and the payment link's status (GET /v1/account/payment-links/{id}). Place lookups and the account status check cost 0 tokens. - A distinct place is a location a request names: a
location_id, and also a circle, a polygon or a street address in a request (Comparables takes an address or a circle). Naming a place already used that day does not count again. Free lookups count toward the 10 places too, so an agent that looks up many names uses the day's places before it makes a paid call. - On Free the limits apply together: the first one used up stops the next request.
- The 1,000 tokens of Free are for the first 30 days. After that, place lookups and the account status check stay free and other calls return a payment link. At most 500 of them can be used in any 3 hours.
- Agent and Agency count tokens, not requests: the tokens of the month, and at most a set number in any 3 hours. Usage beyond them is paid only from prepaid credits, and nothing is billed afterwards. Unused tokens do not carry over to the next month.
- A request over an operation's page size or depth maximum is refused with
400 page_depth_exceeded, and the response names the parameter and the maximum. - Custom limits are set in the contract.
Claro AI on Free
Claro AI has its own cap on Free: 4 searches in all, of any kind and in any order, counted for the whole organisation, with REST and MCP sharing one count.
- A search is
claro_search_premises(POST /v1/claro/search),claro_refine_search(POST /v1/claro/search/refine) orclaro_search_plots(POST /v1/claro/plots/search). Each page counts as one search: asking for the next page of a search with a cursor or an offset is a search again. - Only the results of those searches can be opened:
claro_get_premises,claro_get_plotandclaro_compare_premiseswork on ids returned by them, and a detail on any other id is refused. - The 5th search, or a detail of another id, is refused with
402 payment_requiredand the reasontrial_limit. It carries anupgrade_url, a payment link to top up that the owner or a billing member opens; buying tokens needs no subscription and lifts the cap. The Free plan includes 4 Claro AI searches and their results, and an agent should stop and say so instead of retrying. A search that Claro did not answer is not counted. - Claro operations that cost no tokens are not limited by this cap. Searches also cost tokens as on every plan, and the request limits above apply to Claro calls too. Paid plans have no search cap.
Accounts on credits without a subscription
An account that has bought prepaid credits and has no subscription can only spend what it bought, so it has no 3-hour or 7-day window and no spending cap. Its guards are 20 requests a minute, 3 requests in flight, 50 distinct places a day and at most 25,000 tokens a day. Until the account has passed business verification, or until 7 days after its first credit purchase, it keeps the Free plan's guards on requests a minute (10), requests in flight (2) and distinct places a day (10). Buying credits needs a verified card, and in the first 7 days after card verification a purchase is at most €4,000.
Account creation
- At most 3 accounts are opened per network a day, across the console, the sign-up API and OAuth sign-in. Over it the answer is
429 signup_limited. - At most 3 sign-ups through the sign-up API are started per email address a day (UTC).
- The email code that confirms an address is valid for 10 minutes and takes 5 attempts. At most 3 codes are sent per email address in 15 minutes and 20 per network in an hour.
See where you stand
Check usage with the account_status tool, which the Location Lookup, Area Insights and Comparables servers have, with GET https://platform.casafari.com/v1/account (your API key in the X-API-Key header or as Authorization: Bearer <api_key>), or in the console, which shows the current rolling 3 hours, today since 00:00 UTC and the rolling 7 days. Account calls cost 0 tokens.
What happens at a limit
| Status | Problem type | When | What to do |
|---|---|---|---|
429 | request_limit_reached | A request guard is used up: requests in flight, a minute, 3 hours, a day, 7 days or distinct places. The window member names which one (see below). | Wait for Retry-After seconds, then retry. |
429 | usage_limit_reached | A plan's 3-hour token window (session) is used up and no credits remain. Carries limit, reset_at, Retry-After and an upgrade_url to buy credits. | Wait until reset_at, or open upgrade_url to buy credits. |
429 | daily_limit_reached | The account's daily token cap is reached. It resets at 00:00 UTC. | Retry after the reset. |
402 | payment_required | The tokens are used up. Carries upgrade_url and a Link header with rel="payment". | Top up at upgrade_url (the owner or a billing member pays). Poll GET /v1/account/payment-links/{id} about every 5 seconds until it is completed, then retry. |
402 | payment_required with reason spending_cap_reached | On Agent and Agency, the credits spent this period reached the spending cap. | Wait for the next period, or raise the cap in the account's billing settings. |
400 | page_depth_exceeded | Page size or page depth is over the maximum. | Ask for fewer results, or stop paging. |
The window member of request_limit_reached
window names the request limit that was hit. It is not a token usage window: it tells which row of the table above refused the request, and a request limit counts requests, not tokens.
window | The limit that was hit | Free | Agent and Agency |
|---|---|---|---|
concurrency | Requests in flight at once (those still open and younger than 120 seconds) | 2 | 3 |
minute | Requests in the current UTC minute | 10 | 20 |
session | Requests in a rolling 3 hours | 50 | No limit |
day | Requests in the UTC day | 100 | No limit |
week | Requests in a rolling 7 days | 300 | No limit |
month | Requests in a rolling 30 days | No limit | No limit |
locations | Distinct places named in the UTC day | 10 | 50 |
Do not read it as the token usage window of the plans. That is refused with usage_limit_reached, which counts tokens and calls its 3-hour window session. A request_limit_reached with window session is the 3-hour request count, and one with week is the 7-day request count. month is set only for an account with limits of its own, such as a Custom contract. Wait for Retry-After seconds, which is the time until that limit frees up.
Errors are application/problem+json, and each type has a page at https://platform.casafari.com/errors/<code>. Over MCP the same refusals arrive as a payment error or a tool error with the same members. An agent cannot pay by itself: the owner or a billing member opens the payment link to top up.
The spending cap limits the credits a Agent and Agency subscription spends in one subscription period, automatic top-ups included. The default is 25,000 tokens (EUR 1,000). When it is reached, calls that would use credits are refused and no automatic top-up is made until the period ends or the cap is raised. Calls within the usage windows continue.
The platform has no SLA: Casafari aims to keep it available but does not guarantee uninterrupted or error-free operation, and publishes no uptime figure (see the Terms of Use). These limits protect the stability of the platform. Custom contracts set their own. The limits of the existing Casafari MCP server and REST API follow each customer's own contract and are not listed here. Claro AI, a platform product, is metered in platform tokens, with Claro's own limits per account behind them: see Limits and errors.
See also: Terms of Use (clauses 7 and 8), REST API and the FAQ.