Skip to main content
Rate limits and quotas are enforced per plan. Your plan determines how many requests you can make in a period, which API versions you can access, and how far back you can query historical data.

​
How limits are enforced

Limits are checked when your request is authenticated. When you exceed a limit, the API returns an error and sets an X-Auth-Reason response header with the reason.

​
Quota exceeded

When you exceed your plan’s request quota, the API returns 402 Payment Required:

​
Rate limited

When you exceed your plan’s rate limit, the API returns 429 Too Many Requests:

​
Plan-dependent limits

Several behaviors depend on your plan’s entitlements:
  • Articles per page: the maximum number of articles returned per page.
  • Retention window: how far back published articles are available.
  • Historical trends: how far back topic and date-range queries can go.
  • Custom topics: access to custom topic identifiers.
  • API version: the maximum API version your plan can access. Requesting a newer version returns 403.

​
Best practices

  • Add retry logic with exponential backoff for 429 responses.
  • Cache responses where freshness allows.
  • Use the retrieve endpoint to re-fetch past results by ID instead of re-running expensive searches.
  • Contact support if you need a plan change.