API Rate Limits

There is a 20-call-per-hour limit on Create a Question Run and Create a Cleanroom Flow Run calls.

Limits are managed per API user, organization, and IP address.

If the request limit is exceeded, responses will include a 429 Too Many Requests error.

Your code should include error handling for 429 errors so that subsequent requests are not made for the current hour that began with the first of the prior 20 calls.

Note: The Clean Room API uses the token bucket algorithm to manage requests and determine when to enforce the rate limit. An API user gets a set number of “tokens” for a given period, so it doesn't matter if the calls are made in a few seconds or at longer intervals across an hour. For more information, see "Token Bucket".

Token generation

Tokens expire after 12 hours. Reuse the access token in subsequent requests and request a new one only when the current one has expired. For more information, see Request an Access Token.

Polling object status

Do not poll for an object's status more than 20 times per hour. We recommend polling hourly.

Creating questions, question runs, and flow runs

Do not post to the API to create clean room question runs or clean room flow runs more than 20 times per hour.

More frequent calls may lead to unnecessary run failures or processing overhead.

We recommend creating distinct and meaningful run names to help distinguish between runs and make it easier to debug errors when they occur.