Limits
The Direct API's request-rate limits, the headers that report them, and its size and count limits.
Request rate
| Bucket | Limit | Counted per |
|---|---|---|
| Generation reads | 30 per minute per generation, 1,200 per minute in total | API key |
Free tool calls (lists, catalog, plan_media, and each media URL a call imports) | 1,000 per hour | API key |
Webhook management (/webhooks and its paths) | 60 per minute | API key |
/usage, /me | 60 per minute | API key |
Requests whose API key does not work (401) | 60 per 10 minutes; past it, requests from that address answer 429 (with Retry-After) until the window drains, except with a key that authenticated in the last 10 minutes | client IP address (an IPv6 address by its /64) |
| Paid tool calls | no request-rate limit |
- Paid calls are bounded by money, not by rate: your key's credit limits and your organization's balance.
- Under heavy load a generation waits in
queuedfor model capacity rather than being refused. Starting more work than a model can run at once makes later generations take longer, never fail. - A paid call whose outcome turned out free, such as
video_remove_audioon a silent video, counts against the free-call bucket.
Rate-limit responses
Every rate-limited endpoint returns these headers:
X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 1187
X-RateLimit-Reset: 1792919760A refused request answers 429 with Retry-After: <seconds> and this body:
{
"description": "This API key read generations more than 1200 times a minute. Poll less often, or pass ?wait= to be answered when a status changes.",
"code": "rate_limited",
"data": { "retry_after_seconds": 14 }
}Wait Retry-After seconds before you retry. A 429 never charges.
Size and count limits
| Limit | Value |
|---|---|
| Request body | 1 MB |
variations per image start | 1 to 4 |
| Ids per batch read | 10 |
wait | 45 s |
metadata | 20 keys; key up to 40 characters, value up to 500 |
Idempotency-Key | up to 200 characters, remembered 24 h |
| Active API keys per organization | 10 |
| Webhook endpoints per organization | 10 |
| Asset link lifetime | no expiry |
| Per-model inputs (prompt length, reference images, durations, file sizes) | as listed in Models and each tool's input_schema |
If you have any trouble or have any questions, feel free to reach out. We're happy to help. Write to us at support@morphic.com.