Conventions and errors
JSON, ids, dates, paging, limits, versions, and every error the API returns.
Conventions
- JSON in and out, UTF-8. Send
Content-Type: application/jsonwith a body. - Ids are integers. A catalogue filter also has a
key, a stable string such asmergers_acquisitions. - Instants are ISO 8601 in UTC (
2026-09-18T12:04:00Z). Dates areYYYY-MM-DD. - Absent values are
null, never missing. - Lists are newest first and paged.
limitis 1 to 100, 50 by default. A page carriesnext_cursor; pass it back ascursorfor the next page. It isnullon the last page.
{ "data": [ … ], "next_cursor": "eyJpZCI6NDgxMn0" }- Rate limit: 60 requests a minute per key (or per assistant signed in, see the
MCP server), the API and the MCP server counted together. Past that,
429with aRetry-Afterheader in seconds. - Limits: each account is on a plan (Trial, Pro, Scale, or an Enterprise plan of its own),
which counts radars, companies a radar watches and custom sources a radar ticks per calendar
month, in UTC: anything a saved radar used this month counts until the 1st, even once
removed, and a company or custom source only in the account, on no radar, does not count.
Pro counts 10 radars, 40 companies and 10 custom sources a month; Scale 40, 160 and 40. A
request that would go past them fails with
403 account_limit, saying what is over, by how many, and when places free up (below); editing, renaming or moving something between radars never does. An account holds at most 1,000 companies and 500 custom sources, a newsletter 2,000 recipients, and a radar 50 companies and filters, 10 AI filters (NOTlines left out) and 30 custom sources. Own words, languages other than English, and tender, price and rate radars are Scale's: on Pro they fail with403 plan_feature. An account adds at most 50 filters in its own words a day (UTC). - Versions: the path carries the version. A change that breaks a client comes as
/api/v2;/api/v1gains fields, never loses or renames one. - OpenAPI: the full description, generated from the code, is at
https://app.trymarketradar.com/api/v1/openapi.json. The API reference is built from it.
Errors
Every error has the same shape:
{ "error": { "code": "invalid_request", "message": "Enter the company's website, such as bnpparibas.com.", "field": "website" } }A request past the month's count says what is over, by how many, and when places free up:
{ "error": { "code": "account_limit", "message": "2 companies over: the plan counts 40 companies a month, and 40 are used since 1 October. Places free up on 1 November.", "field": null, "over": [{ "what": "companies", "limit": 40, "used": 40, "by": 2 }], "frees_at": "2026-11-01T00:00:00Z" } }| Status | code | When |
|---|---|---|
| 400 | bad_json | The body is not JSON |
| 401 | unauthorized | No key, an unknown key, or a revoked key |
| 403 | read_only_key | A read key asked to write |
| 403 | account_limit | The request would take the month past what the plan counts (over and frees_at say what and until when), the account already holds 1,000 companies or 500 custom sources, or the newsletter 2,000 recipients |
| 403 | plan_feature | The plan does not include it: own words (field is query), languages other than English (languages), or a tender, price or rate radar (type) |
| 404 | not_found | No such object in the key's account. Another account's ids read as not found |
| 409 | conflict | The company's website is already one of the account's companies (field is website), the custom source's address is already the account's (field is address), a newsletter already has the name (field is name), or an issue or recipient is past what the call asks (field is status) |
| 422 | invalid_request | The request fails a rule; field names the field. A company, company group or filter in a body that is not the account's fails here, on query; a custom source, on custom_source_ids; a website group, on source_group_ids |
| 429 | rate_limited | More than 60 requests in a minute, or a 51st filter in your own words in a UTC day. Retry-After says when to try again |
| 500 | server_error | Ours. Retrying later is safe for a read |