Limits

MentionFlow's API has one request rate limit and a few fixed caps. Knowing them keeps your integration predictable.

Rate limit — 120 requests per minute per key

Read requests are metered per API key with a token bucket: 120 requests per minute, full burst allowed (all 120 may arrive at once; tokens then 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 regardless of how many messages the batch carries.

Every keyed response includes the standard headers:

A refused request returns 429 with Retry-After (seconds) and an honest JSON body — see Errors. Refusals never consume data or partially execute.

Two deliberate boundaries: unauthenticated requests are rejected 401 before metering (no key, no bucket), and crawler ingest (POST /api/v1/crawler-events) is not rate-limited — it receives machine traffic at page-view cadence, and dropping events would silently lose data.

Practical note: read responses are backed by a cache with a one-hour TTL, so polling faster than hourly returns the same window without extra computation. Poll on the order of the data cadence (daily or a few times a week) and the limit is unreachable.

Response caps

Each read resource returns at most:

The MCP equivalents match, with one exception: list_answers returns 50 (the 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 1–200, default 50). Passing either switches the response to a page plus a next_cursor field (null on the last page); pass next_cursor back as cursor to continue. Paged reads enumerate the full listing — past the default caps above (answers beyond 200, sources beyond 20, urls beyond 50) — in a stable per-resource order: by id (brands, prompts, competitors), by domain (sources), by url (urls), and newest-first by (date, id) (answers). Cursors are opaque, resource-specific tokens; a malformed or wrong-resource cursor is an honest 400, while a well-formed cursor value merely 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–200 is a 400, never silently clamped. Requests without cursor/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, but a batch may contain 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 request 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 / 413 shapes.