Skip to main content
Applies to:
  • Plan - Starter, Pro, Enterprise
  • Deployment - Any
  • Use case - BTQL queries with frequent or resource-intensive query patterns

​
Summary

BTQL queries through the MCP server or API hit rate limits of 20 requests per minute, causing HTTP 429 errors that block productivity.

​
Resolution Steps

​
If you’re a SaaS or BYOC customer

​
Step 1: Contact support

Contact us to discuss options for your usage patterns and requirements.

​
Step 2: Optimize queries while waiting

Reduce query frequency by caching results, batching requests, or adding time delays between queries.

​
If you’re self-hosting (Hybrid deployment)

​
Step 1: Configure rate limit environment variables

Set RATELIMIT_BTQL_DEFAULT to control queries allowed per organization per window, which defaults to 60 seconds. To set a tighter limit on an individual project, add a <project_id>=<max_queries> entry to RATELIMIT_BTQL_PROJECT. Project limits require data plane v2.2.1 or later. Enforcement is off by default, so also set RATELIMIT_BTQL_ENFORCE to true to return an HTTP 429 response when a limit is exceeded.
A project limit is checked in addition to the organization limit, not instead of it. A query consumes one unit against the organization limit and one unit against each project it reads, so it must be under all of them to succeed. When an organization limit applies, a project limit can only tighten it, so setting one above the organization limit has no effect.

​
Step 2: Update deployment configuration

There is no dedicated Terraform variable or Helm value for these settings. Pass them as environment variables to the API services, using braintrust_api_extra_env_vars for AWS or api.extraEnvVars in values.yaml for GCP and Azure. See Set inbound request rate limits for the full set of variables and examples.

​
Additional Information

​
Rate limit behavior

Rate limits apply per organization, and additionally per project, and track queries over a fixed time window. Queries from the API, SDKs, and MCP server count toward these limits. Queries issued from the Braintrust UI are exempt.

​
Query timeout limits

Queries also have a 30-second timeout limit. Self-hosted customers can adjust this using BRAINSTORE_QUERY_TIMEOUT_SECONDS.

​
Retention window enforcement

Separate from rate limits, Starter and Pro plans enforce your plan’s data retention window (14-day retention on Starter, 30-day retention on Pro by default) on all SQL queries against logs and playground data. Experiments have up to 365-day retention on all plans. Data older than the window is silently filtered out rather than returned, so a query over older data returns empty results instead of an HTTP 429 error. Use a relative time interval to stay within the window.