Limits

The API has one rate limit and a few fixed caps. Know them and your integration stays predictable.

Rate limit — 120 requests per minute per key

Read requests are metered per API key with a token bucket. You get 120 requests per minute, and all 120 may arrive at once. Tokens refill continuously, at 2 per second. The REST read endpoints and the MCP endpoint share one bucket per key. An MCP POST costs one token, however many messages the batch carries.

Every keyed response includes the standard headers:

A refused request returns 429 with Retry-After in seconds and an honest JSON body, see Errors. A refusal never consumes data and never half-runs.

Two boundaries are deliberate. Requests with no key are rejected 401 before metering: no key, no bucket. Crawler ingest (POST /api/v1/crawler-events) is metered too, but on a separate bucket per key — the same 120 per minute, in its own namespace — so a busy shipper cannot eat that key's read and MCP budget, and read traffic cannot starve ingest.

A refused ingest request is the same 429 with Retry-After. Nothing on the MentionFlow side retries it, so a burst above the cap is simply not counted. Ship batches, up to the 10 MB body cap below, rather than one POST per page view, and honour Retry-After when you get one.

Read responses come from a cache with a one-hour TTL, so polling faster than hourly returns the same window and computes nothing new. Poll at the pace of the data, daily or a few times a week, and you will never reach the limit.

Response caps

Each read resource returns at most:

The MCP tools match, with one exception: list_answers returns 50, where REST /answers returns 200. The window is fixed at 7 days, so these caps bound the default result.

Pagination (additive)

The list resources (brands, prompts, competitors, sources, urls, answers) take optional cursor and limit query params. limit runs from 1 to 200, default 50. Pass either one and the response becomes a page plus next_cursor, which is null on the last page. Pass next_cursor back as cursor to continue.

Paged reads walk the full listing, past the caps above: answers beyond 200, sources beyond 20, urls beyond 50. The order is stable per resource: by id (brands, prompts, competitors), by domain (sources), by url (urls), newest first by (date, id) (answers).

Cursors are opaque, resource-specific tokens. A malformed cursor, or one from another resource, gets an honest 400. A well-formed cursor only repositions the walk. Every page still resolves brand scope through your own key, so a forged cursor can only land elsewhere in your own data. A limit outside 1 to 200 is a 400, never quietly clamped.

Requests without cursor or limit are byte-identical to the pre-pagination contract. shopping is not paginated. Its leaderboard cap is applied upstream and bounds the whole window.

MCP batch cap

The MCP endpoint accepts JSON-RPC batches of at most 10 messages. A larger batch is rejected with a -32600 error (HTTP 400). This bounds how much one request can fan out into concurrent database work.

Crawler ingest body cap

POST /api/v1/crawler-events accepts a body up to 10 MB. A larger body returns 413 with the message Body over 10 MB — ship smaller batches. Ship logs in chunks under that size. Rows are de-duplicated on insert, so overlapping chunks are safe. See Crawler ingest.

Related

• Conventions: the fixed window and caching.
• Resource reference: per-resource details.
• Errors: the 400 and 413 shapes.