Limits

Rate limits, concurrency, upload and import sizes, page sizes, waits, link lifetimes and webhook delivery.

Read as Markdown

Every 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.

BucketPer minuteSpent by
agent_read120Every read: lists, single reads, the wait, the library and download links, templates, run reads, the webhook list, MCP resources
agent_estimate60POST /estimates, estimate_generation, riffads estimate
agent_submit20POST /generations, submit_generation, riffads generate, riffads analyze
agent_upload30Reserving and finalizing an upload
agent_import10POST /uploads/from-url, import_media_from_url, riffads upload --url
webhook_manage20Creating and deleting webhook endpoints
workflow_run20Both workflow invoke routes and run_workflow
  • One wait call costs one agent_read, however long it blocks.
  • get_asset costs one. MCP resources/list costs up to two, resources/read one.
  • No X-RateLimit-* headers. Retry-After comes only on a 429 that has retry_after_seconds.
  • quota_exceeded is also 429 but not retryable: Errors.

Per IP

Counted per address, before any key or token check.

RuleLimitWindow
MCP dynamic client registration1010 minutes
Every other path on the MCP server12060 seconds
GET /health/ready6060 seconds
  • This 429 is OAuth shaped with Retry-After, not the error envelope: its body.
  • GET /health and keyed /api/v1 routes have no per-IP brake.

Concurrency

RuleValue
Agent jobs running, REST and CLI1 per API key
Agent jobs running, MCP1 per person
A stuck job frees the slot after600 seconds
Renders at once, per workspaceSet 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

RuleValue
Variants per submitmax 4
Real ceilingthe smaller of the capability's max and 4
Over the ceilingrefused, never clamped

What comes back for each model type: Variants.

Uploads

KindAccepted typesMax size
Imageimage/jpeg, image/png, image/webp, image/gif20 MB
Videovideo/mp4, video/webm, video/quicktime100 MB
Audioaudio/mpeg, audio/mp3, audio/wav, audio/x-wav, audio/webm, audio/ogg25 MB
RuleValue
Pixels per imagemax 40,000,000
Longest image sidemax 16,384 px
filename1 to 255 characters
Signed PUT link300 seconds, one use, exact byte count
Unfinished reservations per workspacemax 50
Abandoned reservation clears after15 minutes
Reservations per workspace30 a minute

Other file types are refused before any bytes move. A capability can set stricter file rules, and its refusal names the number.

POST /uploads/from-url, import_media_from_url or riffads upload --url. Free in credits.

RuleValue
What it takesA direct link to one media file. A web page, a post or an ad library page is refused
Download sizemax 50 MB, then the per-kind limit above
Redirects followedmax 5
Download time25 seconds
AddressesPublic only, including every redirect
url1 to 2,048 characters
filename1 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

ListMCPDefaultMax
GET /capabilitieslist_capabilities2550
GET /presetslist_presets2550
GET /actorslist_actors2550
GET /voiceslist_voices2550
GET /generationslist_generations2550
GET /assetssearch_library2550
GET /workflow-runs, GET /workflows/{id}/runslist_workflow_runs2550

Lists that do not page:

ListSize
GET /webhooksevery endpoint, at most 10 per workspace
GET /workflows/templates, list_templatesevery template
Templates inside one GET /presets rowat most 20. GET /presets/{id}/templates (MCP: list_presets with capability_id) returns all
MCP resources/listat most 50 entries, brand kits first, then actors. No cursor
  • Only next_cursor: null is the end. A short or empty page is not.
  • Send next_cursor back as cursor with the same filters. A broken cursor restarts from the top.
  • limit above the max is clamped, not refused. No list row carries a link.

Waits and timeouts

ThingValue
One wait call blocks at most20 seconds
Wait route wall clock60 seconds
MCP route wall clock60 seconds
Image inspection on finalize5 seconds
Import download25 seconds
GET /health/ready database check3 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

ThingValue
Request timeout30 seconds
Wait call timeout90 seconds
riffads generate, riffads status --wait give up after30 minutes (--timeout <seconds>)
riffads workflows invoke --wait, riffads workflows run --wait give up after60 minutes (--timeout <seconds>)
Retryable refusals in a row before it stops5

Giving up is not cancelling: the job keeps running. Commands.

LinkLifetime
A file's url (REST, MCP, CLI, webhooks)Never expires. Deleting the file turns it off
Signed upload PUT link300 seconds
  • One link per file, the same on every surface and every read. There is no second, short link.
  • Anyone with a file's url can open it: Download links.
  • Preset preview_url links are public and permanent. They are not your files.

Blocks

WindowValue
Failures that pause a request3
Pause lastsabout 1 hour
Content refusals that block a request2
Block lasts30 days

Only moderation_blocked, provider_unavailable and internal_error count. Errors.

Webhooks

RuleValue
Endpoints per workspacemax 10
Endpoint urlpublic https, up to 2,048 characters
descriptionup to 200 characters
Answer a delivery with a 2XX within10 seconds
Attempts per delivery5: 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 than300 seconds
Endpoint marked failing after3 deliveries in a row that used every attempt
Endpoint disabled after20 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 (so maxCredits is 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.

On this page