> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# BTQL rate limits on Starter and Pro plans

export const plans_0 = "Starter, Pro"

export const deployments_0 = "Any"

export const data_plane_version_0 = undefined

export const use_case_0 = "Use case - BTQL queries with frequent or resource-intensive query patterns"

<Note>
  **Applies to:**

  * Plan - {plans_0}
  * Deployment - {deployments_0}
  * {data_plane_version_0}
  * {use_case_0}
</Note>

## Summary

BTQL queries through the MCP server or API hit rate limits of approximately 20 requests per minute on Starter and Pro plans, causing HTTP 429 errors that block productivity. Rate limits are enforced because BTQL queries consume significant backend resources and costs that aren't accounted for in lower-tier plans. Contact sales to discuss increased rate limits for your organization's usage requirements.

## Resolution Steps

### If you're on a Starter or Pro plan

#### Step 1: Contact sales

Reach out to discuss higher rate limits based on 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.

```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
# Allow 500 queries per organization per minute
RATELIMIT_BTQL_DEFAULT=500

# Limit one project to 100 queries per minute
RATELIMIT_BTQL_PROJECT=<project_id>=100

# Return an HTTP 429 response when a limit is exceeded
RATELIMIT_BTQL_ENFORCE=true
```

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](/docs/admin/self-hosting/configure/networking#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](/docs/plans-and-limits#usage-limits) (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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.