# How to document API rate limits for AI agents

The limit pages that passed state every number with its scope, on one page.

- Published: 2026-09-24
- Kind: explainer
- Author: Sean Knight
- Tags: rate limits, plan quotas, documentation for AI agents

An AI agent that writes code against your API needs your rate limits before it can choose a retry interval or a batch size. It cannot ask support. It cannot sign into a dashboard. It reads your documentation and builds the rest of the code around whatever it finds there.

We measured how often the documentation supplies that number. From 2026-08-05 to 2026-09-22 we ran our AI Agent Readiness Test on 93 products. Three models, GPT 5.6 Sol, Claude Opus 5, and DeepSeek v4 Flash, each work alone with the same brief and no shared context, using only the product's public documentation pages. Each model votes PASS, PARTIAL, or FAIL on five first-hour developer jobs, and every vote carries a quote from a page and that page's URL. One of those jobs asks for the exact limits, meaning the rate limits and the plan quotas.

The products lost more points on this job than on any other. A PASS vote is worth 2 reading points, a PARTIAL vote 1, and a FAIL vote 0, so the limits job offered 558 points across the 93 products. The products lost 225 of them. 86 of the 93 lost at least one point on this job. The votes divide into 27 products at PASS, 55 at PARTIAL, and 7 at FAIL, and on 4 products the three models split three ways. Each report turns a product's votes into a score out of 80, shown as a percentage and a letter grade, and the [grades table](/grades/) gathers those grades for every product we tested.

One pattern separates the passes from everything else. A passing page states each limit with what it applies to and the value, on a page the agent can find. A failing page leaves out the scope, leaves out the value, or gives two values for the same limit.

## What the passing pages share

All three models voted PASS for 7 products. Three of them show the pattern.

[Linear](/reports/linear-docs-ai-agent-readiness/) puts every number on one page, organized by authentication type. An API key gets 2,500 requests per hour, an OAuth app gets 5,000, and an unauthenticated request gets 600. The same page sets complexity points per hour at 3,000,000 for API keys, 2,000,000 for OAuth apps, and 100,000 for unauthenticated requests, and it caps any single query at 10,000 points. No other page restates these numbers.

[Reducto](/reports/reducto-docs-ai-agent-readiness/) states 1,000 requests per second per API key on all endpoints on its Rate Limits page, with 200 requests per second on GET /job/{job_id}. Its Concurrency Throttle page holds one table with the United States and European Union baselines side by side for each plan.

[Unstructured](/reports/unstructured-docs-ai-agent-readiness/) states four limits in one callout: 10 files, 50 MB per file, one second between launches, and five concurrent jobs. The same callout appears word for word on five pages, and no page gives a different value.

Each of these pages pairs every number with a scope, such as an authentication type, an endpoint, or a plan. Where a number repeats, the copies agree.

## How the other pages fail

The failures take a few repeated shapes.

One shape is a number with no scope. [Mailgun](/reports/mailgun-docs-ai-agent-readiness/) has one rate-limit number, in the Metrics reference, and no page says what it applies to. No page lists the sending quota for each plan. An agent that finds that number cannot tell whether it governs one endpoint, one domain, or the whole account.

Another shape keeps the numbers outside the docs. The platform API page for [Mastra](/reports/mastra-docs-ai-agent-readiness/) says the rate limits are unpublished, and the only exact quotas appear on the marketing pricing page. The API rate limit page for [Sentry](/reports/sentry-docs-ai-agent-readiness/) names no requests-per-second number for any endpoint, and its quota pages send the reader to a pricing page outside the docs. An agent that reads only the documentation finds no number to use.

A third shape names categories without values. The docs for [CopilotKit](/reports/copilotkit-docs-ai-agent-readiness/) name five limit categories and give a value for none of them, then point to a dashboard page behind a login.

The last shape is two pages that disagree. The pre-recorded audio guide for [Deepgram](/reports/deepgram-docs-ai-agent-readiness/) says 100 concurrent pre-recorded requests, while its rate limits reference says 50 on every self-serve plan and region. Pages for [Airbyte](/reports/airbyte-docs-ai-agent-readiness/) disagree on Plus workspace limits and on sync intervals for higher plans. A disagreement caps the job at PARTIAL even when one of the two pages is complete, because the agent has no way to choose between them.

The damage follows from how a gap gets filled. The agent takes the first value it finds, or it fills the gap from general knowledge about APIs. The retry spacing, batch sizes, and concurrency in the code it writes follow that value. A person with the same gap would ask support, read the pricing page, or send a test request. The agent has none of those options.

## What the test does not measure

Our test checks whether the pages state the limits. It does not check whether the API enforces those values, so a passing page could promise more than the service delivers. The panel is also small, since three models give a narrow sample of how agents read documentation. Each report prints every vote with its quote and URL, so you can check our reading against the pages yourself.

## What to change

Put each limit on one documentation page. State what the limit applies to on that page, and give the value for each plan. Then have every other page link to that page instead of repeating the number. A repeated number can disagree with its source, and a disagreement caps the job at PARTIAL even when one page is complete. A link keeps one page as the source of every value.

The full set of [reports](/reports/) prints this finding for each product, with every vote, quote, and URL behind it.

Canonical URL: https://docsforagents.com/blog/how-to-document-api-rate-limits-for-ai-agents/