Errors
Every REST error under/v1 is an RFC 9457 problem, sent as application/problem+json. Its type links to the code on this page. Branch on its code; title and detail are for people. The instance is the request id. Include it when you contact support about an error.
A parameter-validation 422 lists each invalid parameter with its location, message and type:
Errors over MCP
MCP’s HTTP refusals use the same problem format. Tool results follow MCP’s rules:- A failure inside a tool call, such as a bad argument, a brand the key cannot read or an archived workspace, is a tool result with
isErrorset and the reason as text. - An unknown method or tool is a JSON-RPC error.
- A missing, revoked or expired key is an HTTP 401. An untrusted browser origin is an HTTP 403.
- A write from a read-only connection is an HTTP 403 with the
insufficient_scopechallenge before the tool runs. Compatible assistants ask you to approve more access and retry the call. A tool error inside HTTP 200 does not request more access. - A write whose member cannot run work in the workspace is an
isErrorresult withcode: "forbidden", since more access would not help. - A refusal’s result carries its facts beside
codeanddetail, such asresets_atwhen a free Snapshot opens again. - A tool call past its limit is an
isErrorresult whose text is JSON withcode: "rate_limited",detailand a positiveretry_afterin seconds. Initialization andtools/listdo not count toward the limit.
Rate limit
Each API key, assistant grant or service token may make 120 requests a minute. API keys share their limit across REST requests and MCP tool calls. Each service token shares its limit across service scan routes and managed-brand reads. The counter uses a sliding window, so crossing a minute boundary does not open a fresh quota. A REST request past the limit answers 429 withRetry-After set to the computed wait in seconds. The limit is per credential, so two keys do not share it.
The anonymous leaderboard HTTP reads have a separate per-IP bucket. A configured site key selects a larger bucket without changing which measurements are public. Their Retry-After is the number of seconds until its sliding estimate falls below the quota.
Responses to authenticated requests carry advisory headers:
q is the quota, w is the window in seconds, r is the requests remaining and t is the seconds until the sliding estimate falls below the quota. Concurrent requests can consume the remaining quota before your next call. A 429 body carries the same numbers in rate_limit:
Keeping reads consistent
Computed reads returnmeta.query, the normalized period, filters and paging parameters, and meta.data_as_of, the id and completion time of the newest scan included. data_as_of is null before a scan is available. The existing period descriptor stays alongside meta.
To keep a page’s requests on the same scans, take the first response’s meta.data_as_of.id and pass it as as_of on the other computed reads. For example:
404 not_found. Answers, changes, overview, questions and scans default to the latest scan, including daily updates. Other computed reads default to the latest weekly report. The pin selects scan facts; current settings, page inventory and action states remain live.
MCP tools accept the same as_of and cursor arguments on the applicable reads. Their structured content includes the same meta and next_cursor fields.
Paging
Lists acceptlimit from 1 to 100 and an opaque cursor, and return limit, total and next_cursor. Pass next_cursor unchanged as cursor with the same filters and limit, and stop when it is null. total counts the filtered population before paging. Existing offset parameters remain available; the cursor’s offset wins when both are supplied.
The default limit is 20, except for brands at 100, conversation messages at 50, and scores and leaderboard reads at 10. Brands, conversations, evidence, key pages, website scope and the Audit’s competitor comparison at GET /v1/scans/{scan_id}/audit/competitors use the same cursor pattern. Both conversation message reads return newest first and have no before or after parameter. Questions and answers keep has_more as a redundant equivalent of next_cursor != null.
Hall-of-fame cursors bind to the publication, and website-scope cursors bind to its current configuration. If either changes between pages, start again without a cursor after 400 invalid_cursor.
Scores page the Engines table with include=engines, or the engine pane’s competitors with include=engine. Competitors page the leaderboard with with_page=true. Both return next_cursor at the top of the response, null when the read has no page or the page is the last. Start with your filters and limit, then pass each next_cursor as cursor with the same filters and limit. Stop when next_cursor is null. When you supply a cursor, its offset takes precedence over offset. A cursor pins the scans selected by the first request, so a newer scan does not move answers between pages. Question cursors keep the first page’s question-set version and row order, including questions you archive while paging. Action, AI-visit and change cursors also exclude actions, pages and changes created after the first page’s population is read. Keep the cursor unchanged; changing its query or an explicit as_of answers 400 invalid_cursor.
Nested lists state a total for their population: source actions_total and prompts_total, cited-page prompts_total, page takes_total, perception and reputation question and page totals, audit finding_pages_total and checks_total, and map folder_pages_total. Use the existing limit and offset arguments for capped lists. Audit group checks are complete; checks_limit and checks_offset page a selected check’s failing pages. Page takes also retain takes.total, takes.limit and takes.offset. The cited-page read pages its citing questions with prompts_limit and prompts_offset, and accepts as_of for its scan facts.
Changes accept as_of and return query metadata.
Versioning covers what can change within v1.