Rate and size limits
This page is for developers who call instruction.md's MCP server, run its CLI, or embed its pages. It lists every limit the service enforces: what each plan allows, how large a text or upload may be, how fast you may call, and how lists are paged. Each limit names the error you get when you reach it.
Plan limits
Each organization has one plan, and its limits count everything in the organization. The figures come from billing/plans.json, the same file the server enforces. Unlimited means the plan sets no cap.
| Limit | What counts | Each plan | Refused by | What you get |
|---|---|---|---|---|
privateInstructions | Instructions an organization holds that are not public (Only you and Your organization both count). Deleted ones don't. | Plans Community 3 · Pro 100 · Team 1,000 · Enterprise unlimited | instructions_create, instructions_duplicate, instructions_fork, instructions_transfer, instructions_visibility_set, and a first release that sets a visibility | limit_reached: "this plan keeps N private instructions; make one public, delete one, or upgrade" |
seats | People in the organization who aren't guests. A Team plan paid by subscription has no cap: each person is billed as they join. | Adding a member, accepting an invitation, raising a guest's role, SCIM provisioning | limit_reached: "this plan has N seat(s) and all are taken; free one or upgrade" | |
agents | Agent credentials (API keys) that are not revoked. | orgs_agents_create (instruction agents create) | limit_reached: "agents need the Pro plan or above" where the plan has none, else "this plan keeps N agent(s); revoke one or upgrade" | |
versionsPerMonth | Versions released by the organization in the current calendar month, every instruction together. | Plans Community 200 · Pro 1,000 · Team 10,000 · Enterprise unlimited | instructions_publish (instruction publish, instruction push --publish) | limit_reached: "this plan makes N versions a month" |
apps | Apps registered for Sign in with instruction.md that are not revoked. | orgs_apps_create | limit_reached: "this plan registers N app(s)" | |
realtimeConsumers | Consumers that hold live updates for the organization's instructions at once: an events stream, a poll lease, a webhook subscription or a resource subscription. A consumer is one person or agent, through one OAuth client and one MCP client. Reads are never counted. | Plans Community 1 · Pro unlimited · Team unlimited · Enterprise unlimited | The gateway's admission, when the live delivery opens and each time it is renewed | JSON-RPC error -32025, its data the limit_reached error with retryAfterSeconds and reads: "unlimited" |
assistantCredits | The editor's assistant, in credits (a thousandth of a US dollar of model cost). Community's is each person's, once; a paid plan's is the organization's, each month, pooled per seat on Team. | Plans Community 1,000 · Pro 1,500 · Team 2,500 · Enterprise unlimited | POST /api/assistant/turn and a spoken conversation | HTTP 402, code allowance_exhausted: "the assistant's allowance is used up" |
workspaces | Workspaces of the organization, its default one included. Sealed workspaces don't count here. An organization that holds more after a downgrade keeps them. | Plans Community 1 · Pro 1 · Team unlimited · Enterprise unlimited | orgs_workspaces_create | limit_reached: "this plan keeps N workspace(s); several are on Team and above" |
maxAgentsPerRule | The most agents one deployment rule may be set to make (controls.maxAgents). | Creating or changing a deployment rule with a higher controls.maxAgents | limit_reached: "this plan lets a rule run at most N agents" |
A plan that has 0 of a limit is left out of its row: on that plan the feature is not offered, and the call is refused with the feature's own message, such as "agents need the Pro plan or above".
Limits never cut what you already have. An organization that holds more than its plan allows after a downgrade keeps it all, and only adding more is refused. Plans never limit reading an instruction: pulling an instruction, over MCP or its page, works on every plan. Reads still count toward the rate limits.
Plan features
A feature is either on or off for a plan. When a plan lacks it, the call is refused with limit_reached and details: {"feature": "<key>", "upgrade": "orgs_billing_checkout"}. The refusals of sso, ema, appsSensitive and appsPolicy also name the plan that has the feature in details.plan.
- Signing keys (
signing):Plans On every plan
- Sealed workspaces (
sealedWorkspaces):Plans On Team and Enterprise
- Agent credentials (
agents): - Deployments, one instruction run as an agent (
deployments): - Deployment rules, every instruction of a scope (
deploymentRules):Plans On Team and Enterprise
- Integrations (
integrations): - Allowing and blocking an MCP server's tools (
toolPolicy): - Restricting instructions to the organization's integrations (
integrationsOnly):Plans On Team and Enterprise
- People directories (
peopleDirectories): - SCIM provisioning (
scim):Plans On Team and Enterprise
- Apps that follow every instruction of a workspace (
appsSensitive):Plans On Team and Enterprise
- Choosing the apps your people use (
appsPolicy):Plans On Team and Enterprise
- Single sign-on through the organization's own identity provider (
sso):Plans On Enterprise
- AI clients connected through that identity provider without a sign-in, enterprise-managed authorization (
ema):Plans On Enterprise
. It is not switched on in production yet: see Changes and status.
The whole list, with prices, is on Plans.
What a refusal looks like
A tool refused at a plan limit answers a result with isError: true. Its structuredContent is the error: the limit, the plan's figure (max), what the organization holds (used), the organization and its plan, and the tool that upgrades it. The admins and billing people of the organization may call orgs_billing_checkout.
{
"error": {
"code": "limit_reached",
"message": "this plan keeps 3 private instructions; make one public, delete one, or upgrade",
"details": {
"limit": "privateInstructions",
"max": 3,
"used": 3,
"orgId": "org_01J…",
"plan": "community",
"upgrade": "orgs_billing_checkout"
}
}
} An organization whose payment is overdue takes no new people and no new private instructions until it is paid. That refusal is also limit_reached, with details.reason: "past_due" and details.manage: "orgs_billing_portal". Every error code is on Errors.
Size limits
| What | Limit | What you get |
|---|---|---|
| An instruction's text: a draft, a pushed document, a proposal | 1,000,000 characters | limit_reached, "… holds at most 1,000,000 characters" |
The draft's text inside an instructions_get answer (include: ["draft"]) | 100,000 characters | Past it, draft.text is left out and the answer links instruction://<id>/draft instead. Read that resource for the whole text. |
The diff inside an instructions_proposals_get answer | 100,000 characters | Past it, diff.unified is left out: the answer keeps the stats, and unifiedOmitted says where to read the texts. |
Edits in one instructions_draft_edit call | 200 operations | limit_reached on ops. Send the whole text with instructions_draft_replace instead. |
| A sealed object (an envelope) | About 2 MB (3,000,000 characters) | limit_reached, "a sealed object holds at most about 2 MB" |
| One sealed item of a sealed deployment's conversation (a line, a question, an answer, a message) | 64 KB (65,536 characters) | validation, "a sealed item is at most 64 KB" |
| Your preferences; a workspace's settings; a deployment's parameters | 16 KB each | limit_reached or validation |
A permission request's tool input, from a runner (deployments_asks_create) | 4 KB | validation, "tool.input is at most 4 KB" |
A runner's report (deployments_report): its error; an activity line | 2,000 characters; 500 characters | Cut to fit |
| A message to an agent; a note with an answer | 4,000 characters; 2,000 characters | Cut to fit |
An editor's presence state (instructions_presence_set awareness) | 4 KB | validation |
An OpenAPI document, uploaded or fetched (orgs_integrations_apis_add) | 5 MB | validation, "the document is at most 5 MB"; for a fetched one, the pull fails with "The document is larger than 5 MB" |
A people directory's CSV or JSON file (orgs_people_directories_add) | 5 MB | validation, "the file is at most 5 MB" |
| Any other document an integration pull fetches | 2 MB, 15 seconds | The pull fails with the reason |
| SKILL.md files pulled from one GitHub repository | 200 files | The first 200 are kept, with a note. Name a folder to narrow it. |
A skill an agent fetches from GitHub (instruction agents apply) | 256 KB | The command fails: "… is larger than 256 KB" |
| An OAuth client metadata document (a URL client id) | 5,000 bytes | The sign-in, or orgs_apps_create with cimdUrl, is refused |
What the renderer loads from src or ref (max-bytes) | 1 MiB by default, or the element's max-bytes | The element shows "document exceeds max-bytes (<bytes>)". Raise max-bytes. |
A request body under /api/ (SCIM, the forms, the assistant) | 2 MiB at the edge | HTTP 413 |
Long answers in Claude Code
Claude Code moves a tool's answer longer than 50,000 characters out of the conversation into a file. These tools ask it to keep a longer answer in the conversation, up to the figure shown:
instructions_get: 150,000 charactersinstructions_proposals_get: 150,000 charactersinstructions_versions_read: 150,000 charactersinstructions_diff: 150,000 charactersinstructions_export: 150,000 characters
Count limits
These caps hold on every plan.
| What | Limit | What you get |
|---|---|---|
| Bindings one caller has for one instruction | 50 | limit_reached: "remove a binding first" |
| Proposals one person has open on one instruction | 10 | limit_reached: "close one, or wait for its maintainers" |
| Deployment rules in an organization | 200 | limit_reached: "delete one first" |
| Integrations in an organization | 100 | limit_reached: "remove one first" |
| Domains in an organization | 20 | limit_reached |
| Key services in an organization (sealed workspaces) | 20 | limit_reached |
| Unlock methods of one sealed-workspace key | 20 | limit_reached |
| SCIM tokens that work at once | 5 | limit_reached: "revoke one first" |
| People and groups provisioned over SCIM | 50,000 people; 5,000 groups | SCIM error 400, scimType: tooMany |
Rate limits
Calls to the MCP server
The gateway counts each person's calls in token buckets, by the token's subject, across all its replicas. A bucket holds its burst and refills at its rate. A call past an empty bucket is refused with HTTP 429: wait, then call again. An agent credential is its own subject, so each agent has its own buckets.
| Bucket | For | Calls a minute | Burst | Tools |
|---|---|---|---|---|
person-search | Search by meaning (it asks the embedding model) | 30 | 10 | instructions_search |
person-live | The editor's live tools, called while someone types | 900 | 120 | instructions_draft_sync, instructions_presence_set |
person-writes | Every tool that changes something | 120 | 40 | 138 tools |
person-reads | Every tool that only reads, and every resource read | 600 | 120 | 72 tools |
Which tools only read and which change something is on Tool reference. A person may also have at most 4 calls to the 72 tools that run in the service's own process (the language checks, diffs, signing, the draft's merge) in flight at once. A further call waits its turn for up to 20 seconds. The gateway gives up on any request after 60 seconds.
Live updates
Plans Community 1 · Pro unlimited · Team unlimited · Enterprise unlimited
On a plan with a realtimeConsumers limit, that many consumers may hold live updates for the organization's instructions at once. The gateway asks when a stream, poll lease, webhook subscription or resource subscription opens, and every 60 seconds while it lives. A place is freed when its consumer lets go, or 120 seconds after its last renewal. Another consumer is refused with JSON-RPC error -32025. Its data is the limit_reached error, with retryAfterSeconds and reads: "unlimited". How to handle it is on Live updates, events and webhooks.
Pages and sign-in
These are counted per client address at the edge, and refused with HTTP 429 past them:
| What | Limit |
|---|---|
An instruction's pages (https://instruction.md/<owner>/<name> and its addresses below it) | 300 requests a minute |
| The sign-in service's authorization endpoint | 300 requests a minute |
The same, when client_id is a URL (it makes the sign-in service fetch the client's metadata document) | 30 requests a minute |
/api/support/ (the support and contact forms) | 30 requests a minute |
/api/assistant/ (the editor's assistant) | 300 requests a minute |
Support and contact forms
Behind the edge's limit, each request to the forms is counted again. A refused request gets HTTP 429 with code rate_limited, details.retryAfter in seconds and a Retry-After header.
- In each server process: 5 requests from one address, then one a minute; 20 from one network, then one every 15 seconds. An IPv6 address counts by its /64, and a network by its /48.
- Stored requests: 5 an hour from one address and 20 a day from one network; 3 an hour and 10 a day from one email address. The email caps don't apply to a signed-out "I can't sign in" request, so nobody can lock someone else out of help.
- All requests together: 500 a day for general requests, and 1,000 a day each for sign-in requests and signed-in senders.
- One request: a body of at most 16 KiB; a name and an organization of 120 characters; an email address of 254; a message of 10 to 5,000 characters. A body over 16 KiB gets HTTP 413.
The assistant
The editor's assistant allows 20 steps a minute for each person and 120 a minute for everyone together, and one answer at a time for each person. Past these it answers HTTP 429 rate_limited with Retry-After. Free allowances used from one network are capped each day. When the service's daily budget is spent, it answers HTTP 503 "the assistant is resting for today". When your allowance (assistantCredits, above) is used up, it answers HTTP 402 allowance_exhausted.
Paging
A tool that lists takes limit and answers a page with nextCursor. Send that back as cursor for the next page. A limit below 1 or above the maximum doesn't fit the tool's input schema, and the gateway refuses the call with Input validation failed for tool '…' (see Errors).
| Default | Maximum | Tools |
|---|---|---|
| 50 | 200 | instructions_refs_list, instructions_access_requests_list, deployments_rules_list, deployments_asks_list, orgs_list, orgs_invitations_list, orgs_workspaces_list, orgs_keys_list, orgs_agents_list, me_apps_activity, support_requests_list |
| 20 | 200 | instructions_list, templates_list, instructions_proposals_list, instructions_versions_list, instructions_schedules_list, orgs_integrations_search |
| 25 | 500 | instructions_bindings_list, instructions_consumers_list, orgs_members_list, instructions_audit_query |
| 100 | 500 | instructions_releases_list, deployments_list, deployments_messages_list |
| 10 | 50 | capabilities_search, instructions_search |
| 50 | 500 | instructions_access_list, instructions_links_list |
| 25 | 100 | instructions_activity_list |
| 100 | 300 | orgs_integrations_tools_list |
| 100 | 1000 | orgs_people_search |
The tables on this page are generated when the docs are built: plan limits from billing/plans.json, buckets from the gateway's configuration (deploy/mcpg/prod.yaml), and paging from the tool registry (packages/registry/registry.json).
If you hit a limit
| What you see | Why | What to do |
|---|---|---|
limit_reached with details.limit | The organization is at a plan limit | Make room (delete, make public, revoke), or upgrade with orgs_billing_checkout. See Plans, limits and billing. |
limit_reached with details.feature | The plan doesn't include the feature | Upgrade, or ask an admin of the organization. |
limit_reached with details.reason: "past_due" | A payment is overdue | Update the payment method with orgs_billing_portal. |
| JSON-RPC -32025 on a stream or subscription | Another consumer holds the live updates | Wait retryAfterSeconds, read instead of listening, or upgrade. See Live updates, events and webhooks. |
| HTTP 429 | A rate limit | Wait for Retry-After where it is sent, then retry with backoff. |
| Still stuck | Send a request. |