Limits
Rate limits, concurrency, upload and import sizes, page sizes, waits, link lifetimes and webhook delivery.
Read as MarkdownEvery number RiffAds enforces on the API, MCP and the CLI. All are fixed unless a row says so.
Rate limits
REST has a per key limit plus the per action buckets, MCP only the per action buckets. Over either: rate_limited with retry_after_seconds.
Per key
- 120 requests per API key, across every endpoint.
- The count resets only after 60 seconds with no request, so it is not a per minute window.
Per action
Fixed 60 second windows, counted per API key on REST and per person on MCP.
| Bucket | Per minute | Spent by |
|---|---|---|
agent_read | 120 | Every read: lists, single reads, the wait, the library and download links, templates, run reads, the webhook list, MCP resources |
agent_estimate | 60 | POST /estimates, estimate_generation, riffads estimate |
agent_submit | 20 | POST /generations, submit_generation, riffads generate, riffads analyze |
agent_upload | 30 | Reserving and finalizing an upload |
agent_import | 10 | POST /uploads/from-url, import_media_from_url, riffads upload --url |
webhook_manage | 20 | Creating and deleting webhook endpoints |
workflow_run | 20 | Both workflow invoke routes and run_workflow |
- One wait call costs one
agent_read, however long it blocks. get_assetcosts one. MCPresources/listcosts up to two,resources/readone.- No
X-RateLimit-*headers.Retry-Aftercomes only on a 429 that hasretry_after_seconds. quota_exceededis also 429 but not retryable: Errors.
Per IP
Counted per address, before any key or token check.
| Rule | Limit | Window |
|---|---|---|
| MCP dynamic client registration | 10 | 10 minutes |
| Every other path on the MCP server | 120 | 60 seconds |
GET /health/ready | 60 | 60 seconds |
- This 429 is OAuth shaped with
Retry-After, not the error envelope: its body. GET /healthand keyed/api/v1routes have no per-IP brake.
Concurrency
| Rule | Value |
|---|---|
| Agent jobs running, REST and CLI | 1 per API key |
| Agent jobs running, MCP | 1 per person |
| A stuck job frees the slot after | 600 seconds |
| Renders at once, per workspace | Set by plan |
A busy slot answers submission_in_flight: One job at a time. The render cap answers rate_limited with no retry_after_seconds.
Variants
| Rule | Value |
|---|---|
| Variants per submit | max 4 |
| Real ceiling | the smaller of the capability's max and 4 |
| Over the ceiling | refused, never clamped |
What comes back for each model type: Variants.
Uploads
| Kind | Accepted types | Max size |
|---|---|---|
| Image | image/jpeg, image/png, image/webp, image/gif | 20 MB |
| Video | video/mp4, video/webm, video/quicktime | 100 MB |
| Audio | audio/mpeg, audio/mp3, audio/wav, audio/x-wav, audio/webm, audio/ogg | 25 MB |
| Rule | Value |
|---|---|
| Pixels per image | max 40,000,000 |
| Longest image side | max 16,384 px |
filename | 1 to 255 characters |
| Signed PUT link | 300 seconds, one use, exact byte count |
| Unfinished reservations per workspace | max 50 |
| Abandoned reservation clears after | 15 minutes |
| Reservations per workspace | 30 a minute |
Other file types are refused before any bytes move. A capability can set stricter file rules, and its refusal names the number.
Import from a link
POST /uploads/from-url, import_media_from_url or riffads upload --url. Free in credits.
| Rule | Value |
|---|---|
| What it takes | A direct link to one media file. A web page, a post or an ad library page is refused |
| Download size | max 50 MB, then the per-kind limit above |
| Redirects followed | max 5 |
| Download time | 25 seconds |
| Addresses | Public only, including every redirect |
url | 1 to 2,048 characters |
filename | 1 to 255 characters |
For a file over 50 MB, use the upload flow. Imported images are content checked, video and audio are not (content_checked: false).
Page sizes
| List | MCP | Default | Max |
|---|---|---|---|
GET /capabilities | list_capabilities | 25 | 50 |
GET /presets | list_presets | 25 | 50 |
GET /actors | list_actors | 25 | 50 |
GET /voices | list_voices | 25 | 50 |
GET /generations | list_generations | 25 | 50 |
GET /assets | search_library | 25 | 50 |
GET /workflow-runs, GET /workflows/{id}/runs | list_workflow_runs | 25 | 50 |
Lists that do not page:
| List | Size |
|---|---|
GET /webhooks | every endpoint, at most 10 per workspace |
GET /workflows/templates, list_templates | every template |
Templates inside one GET /presets row | at most 20. GET /presets/{id}/templates (MCP: list_presets with capability_id) returns all |
MCP resources/list | at most 50 entries, brand kits first, then actors. No cursor |
- Only
next_cursor: nullis the end. A short or empty page is not. - Send
next_cursorback ascursorwith the same filters. A broken cursor restarts from the top. limitabove the max is clamped, not refused. No list row carries a link.
Waits and timeouts
| Thing | Value |
|---|---|
| One wait call blocks at most | 20 seconds |
| Wait route wall clock | 60 seconds |
| MCP route wall clock | 60 seconds |
| Image inspection on finalize | 5 seconds |
| Import download | 25 seconds |
GET /health/ready database check | 3 seconds, then 503 |
These are not render times, and there is no timeout parameter. A wait that runs out answers 200 with still_running: true: Wait for the result.
CLI
| Thing | Value |
|---|---|
| Request timeout | 30 seconds |
| Wait call timeout | 90 seconds |
riffads generate, riffads status --wait give up after | 30 minutes (--timeout <seconds>) |
riffads workflows invoke --wait, riffads workflows run --wait give up after | 60 minutes (--timeout <seconds>) |
| Retryable refusals in a row before it stops | 5 |
Giving up is not cancelling: the job keeps running. Commands.
Link lifetimes
| Link | Lifetime |
|---|---|
A file's url (REST, MCP, CLI, webhooks) | Never expires. Deleting the file turns it off |
| Signed upload PUT link | 300 seconds |
- One link per file, the same on every surface and every read. There is no second, short link.
- Anyone with a file's
urlcan open it: Download links. - Preset
preview_urllinks are public and permanent. They are not your files.
Blocks
| Window | Value |
|---|---|
| Failures that pause a request | 3 |
| Pause lasts | about 1 hour |
| Content refusals that block a request | 2 |
| Block lasts | 30 days |
Only moderation_blocked, provider_unavailable and internal_error count. Errors.
Webhooks
| Rule | Value |
|---|---|
| Endpoints per workspace | max 10 |
Endpoint url | public https, up to 2,048 characters |
description | up to 200 characters |
| Answer a delivery with a 2XX within | 10 seconds |
| Attempts per delivery | 5: at once, then 5 minutes, 30 minutes, 2 hours and 12 hours after the one before (about 14.5 hours in all) |
Reject a webhook-timestamp older than | 300 seconds |
Endpoint marked failing after | 3 deliveries in a row that used every attempt |
Endpoint disabled after | 20 such deliveries in a row |
Redirects are not followed, and one 2XX resets the count: Webhooks.
Request bodies
- Every write body is strict: unknown keys are refused, including inside
config(somaxCreditsis a 400). - An estimate is checked exactly like a submit.
- Workflow invoke takes max 60 input entries.
- Validation refusals list max 5 issues, then
Plus N more. - No published body size limit. Send files through uploads.
Spend caps
Four limits cap agent spend, and a refusal names the one that bound it in limit.bound_by: Spend limits.