API errors and limits

Errors

Errors return a status code and a JSON body with a machine-readable code:

{ "error": { "code": "brand_required", "message": "This account has several brands: pass brand_id. See GET /brands." } }

Status	Code	What to do
400	invalid_parameter	A parameter has the wrong type, is out of range, or is missing. The message says which.
400	brand_required	The account has several brands. Pass brand_id.
401	invalid_api_key	The key is missing, mistyped or revoked.
403	feature_not_in_plan	The data is part of the Pro and Growth plans.
403	plan_inactive	The account’s plan isn’t active.
404	brand_not_found	The brand_id isn’t on this account.
404	market_not_found	The market isn’t a live market of this brand. See GET /markets.
404	not_found	The topic, task or other item doesn’t exist.
409	integration_not_connected	The endpoint needs an integration, such as Search Console, that isn’t connected.
429	quota_exceeded	The monthly read budget is used up.
429	rate_limited	More than 60 requests a minute. Wait for Retry-After seconds.
502	upstream_error	A service GetIntel depends on failed. Retry later.

Monthly read budget

Each data request counts as one read. The budget is shared with the MCP server: reads from your API scripts and from your coding agents come out of the same monthly number.

Plan	Reads a month
Monitor	10,000
Pro	50,000
Growth	200,000

GET /usage shows what’s used and left, and when it resets (the first of the month). /usage and /brands don’t count against the budget.

Rate limit

Up to 60 requests a minute per key. Over that, the API answers 429 rate_limited with a Retry-After header.

Freshness

The API reads the same data as the app, so it’s as fresh as the app. AI answers update after the daily scan (9am IST), brand perception and the technical scan update weekly, and AI traffic every few minutes to every hour. See Data freshness. There’s no need to poll more often than once an hour.