Rate Limits

In this section, you’ll discover the guidelines and usage policies for accessing Bettermode's public APIs. These provisions ensure fair usage and help us maintain the quality of the public API experience for all clients.

GraphQL Complexity Calculation

Each field within the schema is assigned a numerical complexity which is used to calculate the overall complexity of the query. By default, the complexity of a field is reflective of its return type, as is outlined in the table below:

Field type	Complexity
Scalar or Enum	0
Object	1
List of Scalar or Enum	1
List of Other Types	5 × Type complexity
Paginated Results	2 + Requested page size × Node complexity

While these defaults provide a baseline for complexity calculations, Bettermode reserves the right to adjust complexities for specific operations or fields and to modify the table above without prior notice Consequently, executing a query or a mutation remains the most accurate method to determine its complexity.

The query complexity is reported as an extension in the response:

{
  "data": {
    //...
  },
  "extensions": {
    "complexity": 35
  }
}

caution

Although not currently enforced, the maximum GraphQL complexity for a single query is ≤1,000. As Bettermode plans to implement this limit in the near future, we advise developers to consider this threshold when developing applications and integrations by targeting complexities below the aforementioned number and leave room for future complexity adjustments that may occur without notice.

Rate Limit Policies

Our API rate limit policies are designed to observe both burst and daily buckets, setting upper limits on the number of requests and GraphQL query complexity for each interval.

The burst span is defined as a 10-second window, with daily resets happening 24 hours after the first API request is received in each cycle.

note

When a request is dropped due to a burst-limit violation, it still counts towards the daily quota of the site.

Rate limit policies vary based on the subscription tier of the site and the available add-ons, as detailed below.

Tier	Burst Limit (per 10 seconds)	Daily Limit
Free Tier	20 requests 2,000 complexity	2,000 requests 50,000 complexity
Pro Tier	100 requests 10,000 complexity	50,000 requests 5,000,000 complexity
Enterprise Tier	200 requests 20,000 complexity	500,000 requests 50,000,000 complexity
API Add-on	200 requests 20,000 complexity	500,000 requests 50,000,000 complexity

info

The API Add-on is available to purchase for all paid customers, except for the Enterprise tier, as enterprise customers already benefit from the increased rate-limit quotas and have access to our Developers’ Portal by default.

Rate-limit policies for legacy subscriptions

• Lite, Pro, and Business Plans (Legacy)

  Burst Limit	Daily Limit
  100 requests 10,000 complexity	50,000 requests 5,000,000 complexity

• Advanced Plan (Legacy)

  Burst Limit	Daily Limit
  100 requests 10,000 complexity	250,000 requests 25,000,000 complexity

API Usage Guidelines

For Website Owners

To review your site’s daily API usage, go to Administration > Billing > Service usage on your site. There, you will see how different apps and integrations are utilizing your site’s daily API quotas.

For App Developers

Should a site exceed any of the quotas, subsequent requests will be denied with a HTTP 429 Too Many Requests status. The Retry-After header in the response specifies the wait time (in seconds), before client can attempt the next request.

If a site has exceeded its burst-limit, Retry-After value can range from 1 to 10. If the daily quota is reached, the value can go up to 86400 (24 hours). In cases where both burst and daily quotas are exceeded, the Retry-After value may change intermittently, as the burst limit resets every few seconds.

GraphQL API responses, including those for denied requests, feature following headers that provide real-time status of the applied policies:

X-Quota-Type: policy-1-type,policy-2-type,...
X-Quota-Duration: policy-1-duration,policy-2-duration,...
X-Quota-Limit: policy-1-limit,policy-2-limit,...
X-Quota-Remaining: policy-1-remaining,policy-2-remaining,...
X-Quota-Resets-At: policy-1-resets-at,policy-2-resets-at,...

Take the following header values as an example:

X-Quota-Type: REQUEST,COMPLEXITY,REQUEST,COMPLEXITY
X-Quota-Duration: 10,10,86400,86400
X-Quota-Limit: 100,1000,50000,5000000
X-Quota-Remaining: 30,870,32800,1340000
X-Quota-Resets-At: 2024-04-04T19:54:00.000Z,2024-04-04T19:54:00.000Z,2024-04-05T19:53:50.000Z,2024-04-05T19:53:50.000Z

They can be interpreted as:

Bucket	Type	Duration	Limit	Remaining	Resets at
Burst Request	REQUEST	10	100	30	2024-04-04, 19:54:00 (UTC)
Burst Complexity	COMPLEXITY	10	1,000	870	2024-04-04, 19:54:00 (UTC)
Daily Request	REQUEST	86,400	50,000	32,800	2024-04-05, 19:53:50 (UTC)
Daily Complexity	COMPLEXITY	86,400	5,000,000	1,340,000	2024-04-05, 19:53:50 (UTC)

These headers provide essential information for managing API requests when sites reach their limits. They help determine when to resume API operations after encountering limits. Bear in mind that the website owners can prematurely reset their API quotas by upgrading their subscriptions. As such, while the app developers are encouraged to honor the Retry-After header and avoid sending API calls during the back-off period, they should also account for these potential quota resets by probing the blocked sites every few minutes and resume the operation if conditions are met.