Past a size limit the request is refused with a 400 or 413. Past a count or
rate limit, it's a 409 or 429 with Retry-After. See Errors
for what to do about each. KiB = 1,024 bytes, MiB = 1,024 KiB.
Rate limits
Past a rate limit, the API answers 429 with code: "RATE_LIMITED",
Retry-After in seconds, and the limit it hit in limit:
{"name": "runs", "scope": "tenant", "max": 600, "windowSeconds": 60}. The
SDKs wait out Retry-After and retry. GET /v1/billing has your run limit
(runsPerMinute), and the console's Billing page shows it.
Limit (limit.name)
Per
Value
api_requests: requests to /v1/*
Client address
600 a minute
agent_creates: agent creates, upserts that change their agent, and forks
Account
600 a minute, against abuse only. Design around busy agents instead
A client address is the caller's IP address; an IPv6 address counts with the
rest of its /64.
api_requests refills continuously. The others count in fixed windows
aligned to the clock minute (UTC), so Retry-After is the time to the next
window.
A retried request (the same request id or Idempotency-Key) answered from
its record isn't a new run. An upsert whose configuration equals the agent's
(the same configHash) isn't an agent create, so deploying 50 unchanged
agents counts nothing. A fork counts.
Answers that count against agent_creates or runs carry
X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset
(seconds until the window resets), and so do their 429s.
Transcriptions and image requests each count as a run.
Agents
Limit
Value
An agent's key
1 to 80 characters of A-Z a-z 0-9 _ -
Lifetime (ttlSeconds)
60 seconds to 366 days, or null for until deleted. Default: until deleted with a key, 1 day without
Create body (POST /v1/agents, with initialMessages)
18 MiB
Imported history (initialMessages)
16 MB of JSON
systemPrompt, systemPromptAppend
32,000 characters each
modelHeaders
20 headers, 8 KB in all
spendLimit.usd
0 to 1,000,000
context
4 KB
Mounts
16 per agent
Agents busy at once
By usage tier, across the whole runtime. An agent is busy while it has a run open, running or queued; a busy agent queues more runs without another slot. A run past the limit gets 429 BUSY_AGENT_LIMIT
Tools in an agent's catalog
4,096 tools and 16 MiB of schemas; at most 64 offered directly to the model, the rest reached from js_exec
Usage tiers
An account's tier comes from what it has paid for credit in total, net of
refunds. Starting credit and other grants do not count. A payment moves the
account up as soon as it lands. See Pricing.
Tier
Paid in total
Agents busy at once
Free
nothing yet
20
Tier 1
$5
50
Tier 2
$50
100
Tier 3
$250
250
Tier 4
$1,000
1,000
GET /v1/billing has busyAgents: the limit, how many are busy now, the tier,
and the next one; the console's Billing page shows the same. At the limit, a
run gets 429 BUSY_AGENT_LIMIT with Retry-After, and the body's
busyAgents (amounts in micro-USD):
json
{ "error": "This account has 20 agents busy, the most its usage tier (Free) allows; retry when one finishes. $5 more of credit unlocks Tier 1: 50 busy agents (it applies once the account has paid $5 in total).", "code": "BUSY_AGENT_LIMIT", "busyAgents": { "busy": 20, "limit": 20, "source": "tier", "tier": "Free", "paid": 0, "next": { "tier": "Tier 1", "paid": 5000000, "limit": 50 } }}
Creating agents, reading them and sending them input don't count; only runs
do.
Runs and requests
Limit
Value
Request id (requestId, idempotencyKey)
1 to 80 characters of A-Z a-z 0-9 _ -
Settled requests kept per agent for idempotent retries
The most recent 256
Open requests per agent (running and queued)
32
Prompt body
6 MiB, with inline files
text
Not blank, unless the message attaches audio
metadata
16 keys of 1 to 64 characters, string values of at most 512 characters
Provider retries within a turn
3 attempts for overloads, rate limits, 5xx and dropped streams
Model responses in one run
1,000, compaction summaries included; runLimits.maxResponses lowers it for an agent or a definition. At it, the turn stops before its next model request (stopped: "turn_limit")
How long a run may take
2 hours from when it began; runLimits.maxSeconds lowers it. stopped: "turn_limit" too; send another message to continue. A turn waiting on people isn't running, and may wait for days. The SDKs have no default timeout
A quiet model stream
Nothing before the first token for 120 seconds (300 for a reasoning model at thinkingLevel high and up), or nothing for 45 seconds once it streams, ends the request as stalled, and it's retried. runLimits.firstTokenSeconds and runLimits.idleSeconds set an agent's own (1 to 3,600). Past every retry the run fails with model_stream_stalled
Resumes of one interrupted run
2; another interruption fails it with resume_limit
Idempotency-Key header
1 to 255 characters; its answer is kept for 24 hours
Stateless run body (POST /v1/runs)
7 MiB, with inline files (4 MiB of files in all)
A stateless run's wait
At most 60 seconds on create, 25 on GET /v1/runs/{id}
A stateless run's retention
A day after it ends by default (retentionSeconds: 60 to 604,800), then deleted. It counts against runs per minute and busy agents, not agent creates
Files
Limit
Value
Files attached to one message
20
Inline (base64) file bytes in one message
4 MiB in all
A file attached by URL ({url})
64 MiB, fetched within 60 seconds, at most 3 redirects, public addresses only
One file
256 MiB
Image the model sees natively
5 MiB and 8,000 pixels a side (larger ones are described in text); sent at most 1,568 pixels a side
PDF the model sees natively
16 MiB and 100 pages
Files in one model request
The newest 100 images, up to 20 MiB as sent; 24 MiB of PDFs. Older ones are described in text
Files a run lists in its outcome
100 written, 20 presented
Signed links
1 second to 24 hours, default 15 minutes
A volume
100,000 files, 100 snapshots and 10,000 pinned ones
Storage per account
1 GB on free credit, 100 GB once you've bought credit. A write past it gets 507 STORAGE_LIMIT
