Rate limiting
The API rate limits requests using a leaky bucket algorithm. Each request costs a number of units, and those units leak out of the bucket at a constant rate. This keeps traffic flowing at a steady rate while still allowing short bursts.
GraphQL API
Rate limiting for the GraphQL API is based on the cost of each request, rather than a fixed number of requests. The sections below cover best practices for keeping that cost down, and how to read your current rate limit status.
Best practices
- Use subscriptions instead of polling with queries to know when data changes.
- Query only the fields you need, and use
filterto narrow down list queries. - List queries return up to 100 records per page, but a larger page costs more than a smaller one. Fetching 100 records in one request costs more than fetching 10, so request fewer records rather than more. See pagination for details.
- If a request is rejected with a
429error, your bucket is full. Stop sending requests and only make new requests once the time given byresethas passed.
Rate limit
To protect the API from queries that are too complex or resource intensive, each request is assigned a cost based on the amount of requested data. Every response to a valid request, or a request that fails business validation, includes an extensions.cost object with the cost of the request and the state of your rate limit. It is omitted entirely when a request fails GraphQL schema validation.
cost· Integer- The cost, in units, of the current request.
limit· Integer- The maximum cost, in units, allowed in the current rate limit window.
used· Integer- How many units have already been consumed in this window.
remaining· Integer- How many units you still have available before hitting the limit.
reset· Integer- A UNIX timestamp, in seconds, indicating when the quota refreshes.
REST API
Rate limiting for the REST API applies to the tile service. Unlike the GraphQL API, rate limit status is returned through HTTP response headers, and each request has a fixed cost of 1 unit. These headers are returned on every request, including failed ones.
x-ratelimit-cost· Integer- The cost, in units, of the current request. Always
1for REST requests. x-ratelimit-limit· Integer- The maximum cost, in units, allowed in the current rate limit window.
x-ratelimit-used· Integer- How many units have already been consumed in this window.
x-ratelimit-remaining· Integer- How many units you still have available before hitting the limit.
x-ratelimit-reset· Integer- A UNIX timestamp, in seconds, indicating when the quota refreshes.
Current limits
Rate limits are applied per customer, on a one-minute window. There is no default limit in place yet. Limits are configured individually per customer until default limits are introduced in 2027.
Some queries and mutations also have individual limits that are lower than your overall limit. These are set on a per product basis, and sometimes on a per request basis, rather than globally.
Was this content helpful?