Rate Limits

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

If you have any questions or require further clarification, feel free to engage with our community in the developer community.

GraphQL Complexity Calculation

Each field within the schema is assigned a numerical complexity, that 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

• Free Tier:
  • Burst Limit:
    • 100 requests per 10 seconds
    • 10,000 complexity per 10 seconds
  • Daily Cap:
    • 50,000 requests
    • 5,000,000 complexity
• Enterprise Tier:
  • Burst Limit:
    • 200 requests per 10 seconds
    • 20,000 complexity per 10 seconds
  • Daily Cap:
    • 500,000 requests
    • 50,000,000 complexity
• API Add-on (Across All Tiers):
  • Burst Limit:
    • 200 requests per 10 seconds
    • 20,000 complexity per 10 seconds
  • Daily Cap:
    • 500,000 requests
    • 50,000,000 complexity

While these default costs provide a baseline, Bettermode retains the right to adjust complexities for specific operations or fields and to modify the table above without prior notice. Consequently, executing a query 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 optimal 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.

Rate Limit Policies

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

The duration of the burst span is 10 seconds, with daily resets happening 24 hours after the first API request in each cycle.

RatePolicies vary based on the site's subscription plan and available add-ons, as detailed below.

Free Plan

• Burst Limit (per 10 seconds):
  • 20 requests
  • 2,000 complexity
• Daily Cap:
  • 2,000 requests
  • 50,000 complexity

Lite, Pro, and Business Plans

• Burst Limit (per 10 seconds):
  • 100 requests
  • 10,000 complexity
• Daily Cap:
  • 50,000 requests
  • 5,000,000 complexity

Enterprise Plan

• Burst Limit (per 10 seconds):
  • 100 requests
  • 10,000 complexity
• Daily Cap:
  • 250,000 requests
  • 25,000,000 complexity

API Add-on (Across all plans)

• Burst Limit (per 10 seconds):
  • 200 requests
  • 20,000 complexity
• Daily Cap:
  • 500,000 requests
  • 50,000,000 complexity

note

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

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 rate limit, subsequent requests will be denied with an HTTP 429 Too Many Requests status code. 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 on rate limit 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,...

Here’s a sample:

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

...which can be mapped to the following table:

Policy	Burst Request	Burst Complexity	Daily Request	Daily Complexity
Type	REQUEST	COMPLEXITY	REQUEST	COMPLEXITY
Duration	10	10	86400	86400
Limit	100	1000	50000	5000000
Remaining	30	870	32800	1340000
Resets at	2024-04-04, 19:54:00 (UTC)	2024-04-04, 19:54:00 (UTC)	2024-04-05, 19:53:50 (UTC)	2024-04-05, 19:53:50 (UTC)

These headers provide detailed information to calculate the appropriate time to resume processing events or actions for sites that reach their limits. It’s also worth noting that website owners can adjust their API usage capacity by purchasing the API add-on or changing their plan, potentially resetting their quotas. As such, developers encouraged to implement a dynamic probing mechanism to check the rate limit status of denied sites periodically, especially when encountering daily limit violations, rather than relying solely on the Retry-After header.