Esta página aún no está traducida.

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.

LimitWhat countsEach planRefused byWhat you get
privateInstructionsInstructions 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 visibilitylimit_reached: "this plan keeps N private instructions; make one public, delete one, or upgrade"
seatsPeople in the organization who aren't guests. A Team plan paid by subscription has no cap: each person is billed as they join.

Plans Community 3 · Pro 1 · Team 10 · Enterprise unlimited

Adding a member, accepting an invitation, raising a guest's role, SCIM provisioninglimit_reached: "this plan has N seat(s) and all are taken; free one or upgrade"
agentsAgent credentials (API keys) that are not revoked.

Plans Pro 10 · Team 100 · Enterprise unlimited

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"
versionsPerMonthVersions 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"
appsApps registered for Sign in with instruction.md that are not revoked.

Plans Community 1 · Pro 5 · Team 25 · Enterprise unlimited

orgs_apps_createlimit_reached: "this plan registers N app(s)"
realtimeConsumersConsumers 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 renewedJSON-RPC error -32025, its data the limit_reached error with retryAfterSeconds and reads: "unlimited"
assistantCreditsThe 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 conversationHTTP 402, code allowance_exhausted: "the assistant's allowance is used up"
workspacesWorkspaces 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_createlimit_reached: "this plan keeps N workspace(s); several are on Team and above"
maxAgentsPerRuleThe most agents one deployment rule may be set to make (controls.maxAgents).

Plans Team 50 · Enterprise unlimited

Creating or changing a deployment rule with a higher controls.maxAgentslimit_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.

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.

A limit_reached result
{
  "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

WhatLimitWhat you get
An instruction's text: a draft, a pushed document, a proposal1,000,000 characterslimit_reached, "… holds at most 1,000,000 characters"
The draft's text inside an instructions_get answer (include: ["draft"])100,000 charactersPast 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 answer100,000 charactersPast 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 call200 operationslimit_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 parameters16 KB eachlimit_reached or validation
A permission request's tool input, from a runner (deployments_asks_create)4 KBvalidation, "tool.input is at most 4 KB"
A runner's report (deployments_report): its error; an activity line2,000 characters; 500 charactersCut to fit
A message to an agent; a note with an answer4,000 characters; 2,000 charactersCut to fit
An editor's presence state (instructions_presence_set awareness)4 KBvalidation
An OpenAPI document, uploaded or fetched (orgs_integrations_apis_add)5 MBvalidation, "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 MBvalidation, "the file is at most 5 MB"
Any other document an integration pull fetches2 MB, 15 secondsThe pull fails with the reason
SKILL.md files pulled from one GitHub repository200 filesThe first 200 are kept, with a note. Name a folder to narrow it.
A skill an agent fetches from GitHub (instruction agents apply)256 KBThe command fails: "… is larger than 256 KB"
An OAuth client metadata document (a URL client id)5,000 bytesThe 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-bytesThe element shows "document exceeds max-bytes (<bytes>)". Raise max-bytes.
A request body under /api/ (SCIM, the forms, the assistant)2 MiB at the edgeHTTP 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 characters
  • instructions_proposals_get: 150,000 characters
  • instructions_versions_read: 150,000 characters
  • instructions_diff: 150,000 characters
  • instructions_export: 150,000 characters

Count limits

These caps hold on every plan.

WhatLimitWhat you get
Bindings one caller has for one instruction50limit_reached: "remove a binding first"
Proposals one person has open on one instruction10limit_reached: "close one, or wait for its maintainers"
Deployment rules in an organization200limit_reached: "delete one first"
Integrations in an organization100limit_reached: "remove one first"
Domains in an organization20limit_reached
Key services in an organization (sealed workspaces)20limit_reached
Unlock methods of one sealed-workspace key20limit_reached
SCIM tokens that work at once5limit_reached: "revoke one first"
People and groups provisioned over SCIM50,000 people; 5,000 groupsSCIM 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.

BucketForCalls a minuteBurstTools
person-searchSearch by meaning (it asks the embedding model)3010instructions_search
person-liveThe editor's live tools, called while someone types900120instructions_draft_sync, instructions_presence_set
person-writesEvery tool that changes something12040138 tools
person-readsEvery tool that only reads, and every resource read60012072 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:

WhatLimit
An instruction's pages (https://instruction.md/<owner>/<name> and its addresses below it)300 requests a minute
The sign-in service's authorization endpoint300 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).

DefaultMaximumTools
50200instructions_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
20200instructions_list, templates_list, instructions_proposals_list, instructions_versions_list, instructions_schedules_list, orgs_integrations_search
25500instructions_bindings_list, instructions_consumers_list, orgs_members_list, instructions_audit_query
100500instructions_releases_list, deployments_list, deployments_messages_list
1050capabilities_search, instructions_search
50500instructions_access_list, instructions_links_list
25100instructions_activity_list
100300orgs_integrations_tools_list
1001000orgs_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 seeWhyWhat to do
limit_reached with details.limitThe organization is at a plan limitMake room (delete, make public, revoke), or upgrade with orgs_billing_checkout. See Plans, limits and billing.
limit_reached with details.featureThe plan doesn't include the featureUpgrade, or ask an admin of the organization.
limit_reached with details.reason: "past_due"A payment is overdueUpdate the payment method with orgs_billing_portal.
JSON-RPC -32025 on a stream or subscriptionAnother consumer holds the live updatesWait retryAfterSeconds, read instead of listening, or upgrade. See Live updates, events and webhooks.
HTTP 429A rate limitWait for Retry-After where it is sent, then retry with backoff.
Still stuckSend a request.

Last checked against the product:

Was this page helpful? Report a problem