Skip to main content
Powabase’s only quantitative rate limit on the AI surface today applies to workflow execution endpoints. The rest of the API (agent runs, knowledge search, source CRUD, and so on) has no Kong-level or in-process limiter; abuse protection there comes from credit-based billing (you can’t run 10,000 agents per second because you’d exhaust your credits). This page covers what is rate-limited, what isn’t, and how to handle the 429 response when you hit the workflow limit. For credit-based pre-dispatch refusals, see Billing model.

​
What’s rate-limited

The limit is per caller, per project-service replica (so per pod, not cluster-wide). It’s a sliding-window in-memory counter: no Redis, no distributed coordination. Each project runs one API service replica today, so per-pod and per-project are the same thing. When you exceed the limit:
The HTTP status is 429.

​
One budget for the Service Role key

The limiter keys on the sub claim of the bearer token. Since 0.12.0, the workflow execution routes require the Service Role key (an end user’s JWT gets 403; see Which key for which route), so every execution call carries the same key and draws on one shared 20/min budget, however many of your backend services or end users it’s on behalf of.

​
What isn’t rate-limited

The rest of the AI surface:
  • Agent runs (POST /api/agents/{id}/run, /run/stream): no limit. Each run is metered by credits, not request rate.
  • Orchestration runs (POST /api/orchestrations/{id}/run/stream): no limit. Same credit-metered story.
  • Knowledge base search (POST /api/knowledge-bases/{id}/search): no limit.
  • Source operations (upload, reextract, cancel, delete): no limit.
  • All CRUD on agents, KBs, workflows, tools, etc.: no limit.
  • All /auth/v1/*, /rest/v1/*, /storage/v1/*, /realtime/v1/* BaaS endpoints: no Kong-level rate limit. GoTrue has its own per-endpoint rate limits documented in Auth model.

​
Why workflows specifically

Workflow /execute is rate-limited because a workflow can be triggered by an external system (a webhook from Stripe, GitHub, cron, etc.) that loses control over its retry behavior. Without a limit, a misconfigured upstream retry storm could exhaust an org’s credits in seconds. The 20/min cap is wide enough for normal usage and narrow enough to bound damage from a runaway loop. Agent runs aren’t limited the same way because they’re typically initiated from your own application code with rate-limiting already in place client-side. You’re not going to accidentally POST /api/agents/{id}/run/stream 10,000 times per second from a React app.

​
What to do client-side

When you get a 429:
  • Don’t retry immediately. The limiter’s sliding window means a retry within the current minute will hit the same 429.
  • Back off exponentially with jitter. Start at 3-5 seconds; double up to 30 seconds; add ±25% random jitter.
  • Surface the wait to the user. “Trying again in 20 seconds” is better UX than spinning indefinitely.
A reasonable retry sequence: 3s → 6s → 12s → 30s → 30s → 30s, with jitter. After three full 30-second waits, give up and surface a hard error: you’re either coding wrong or hitting a real abuse pattern.

​
What to do server-side (your own backend)

If your application triggers workflows on behalf of end users, the shared Service Role budget will bite you at scale. End-user JWTs can’t call /execute, so the fix is on your side: throttle and queue in your backend. Add a token-bucket limiter in front of your /execute calls: release 20 every 60 seconds, queue the overflow, and apply your own per-user fairness before the queue if you need it. Don’t rely on Powabase’s 429 to do throttling for you; that just trades steady throughput for retry overhead.

​
Future quantitative limits

A few things to be explicit about today’s posture so you can plan for changes:
  • There is no gateway-level rate limit on any endpoint today. The API gateway handles CORS and API-key checks only, and that includes inbound webhook triggers: nothing limits their rate at the gateway.
  • Per-IP limits are not enforced by the platform. If your concern is unauthenticated abuse against the Anon Key-fronted endpoints (PostgREST, Storage public URLs), gate them behind your own CDN or WAF.
  • The 20/min workflows limit may move as the platform tunes for usage patterns. The number isn’t a hard product commitment.

​
Next steps

Billing model

The credit system: the other gate on AI surface usage besides rate limits.

Workflows reference

The endpoints this limit applies to.

Auth model

GoTrue’s per-endpoint rate limits on the auth surface (separate from the AI surface limits documented here).

Webhooks reference

The webhook trigger surface: the most common abuse vector, and why workflows are limited.