Usage Limits

This page explains the limits you are subject to when using the API, including use of the Export Console.

Note that limits are dependent on the package you have purchased for the API. This page explains how limits are applied, but please check your contract for your account limits.

Historical access

Your package may limit you to how far in the past you can access data for export and analytics.

For example your package may include access to 6 months of historical data. If so you can export data and run analytics on data from up to 6 months back from the current date.

For packages that do not limit historical access the historical data you can export differs by content type:

  • News data is available from 2009 onwards
  • Social data is available for the last 15 months

Exports

Exports per month

If you have access to the export feature, your package may limit you to a number of exports you can run per month.

This limit is reset on the 1st day of each month.

You can see the number of exports you have run by calling the GET usage/me/metrics endpoint. See our guide on accessing usage statistics for more details.

Understanding exports
It is important to understand that when you create an export through the Export Console or using the API this can contain up to 5 saved searches or tags. Each of the searches or tags will consume one of your exports for the month. So for example, if you create a one-off export containing 3 saved searches, this will consume 3 of your exports allowance. If you create a recurring export which contains 2 tags this will consume 2 of your exports allowance each time it runs.

Documents per export

A single export can contain a maximum of 2,000,000 documents. When an export is created, we check the number of results the export will generate. If the export is forecast to return more than 2,000,000 documents the export will be automatically sampled down to approximately 2,000,000 documents. Sampling is random across the export time window.

Documents per month

If you have access to the export feature, your package will limit you to a number of documents you can export per month.

This limit is reset on the 1st day of each month.

You can see the number of documents you have exported by calling the GET usage/me/metrics endpoint. See our guide on accessing usage statistics for more details.

Maximum export window

If you have access to export content your package may limit the time window for which you can run an export.

For example if you are limited to 1 month that means the start date and the end date of an export can be a maximum of 1 month apart. For 1 month the API actually allows 31 days between start and end date, for example 2020/08/01 00:00:00 to 2020/09/01 00:00:00.

For packages that do not limit the export window, the maximum window is 2 years.

Analytics

Daily analytics calls

If you have access to analytics features your package will limit you to a number of analytics calls you can make per day.

You can see the number of analytics calls you have requested by calling the GET usage/me/requests endpoint. See our guide on accessing usage statistics for more details.

Additionally you can inspect headers returned by the API. These headers are returned for every analytics request:

Header Name Description
RateLimit-Day-Limit This is the number API credits you have per day as set by your API package. (For example 120 credits per day.)
RateLimit-Day-Remaining The remaining number of API calls before you are rate limited. If this falls to 0, you are rate limited. If you hit your API limit, all subsequent requests will fail with a suitable error message and HTTP response code of 403 or 429.
RateLimit-Day-Reset Unix timestamp when the next reset will occur.

Maximum analysis window

If you have access to analytics your package may limit the time window for which you can run an analysis query.

For example if you are limited to 1 month that means the start date and the end date of an analysis request can be a maximum of 1 month apart.

API Calls

Calls to analytics endpoints are limited to 5 calls / second and 100 calls / minute.

The following export endpoints are limited to 20 calls / minute:

  • POST /export/v1/exports/one-time
  • POST /export/v1/exports/recurring
  • POST /v3/exports/one-time
  • POST /v3/exports/recurring

Calls to all other endpoints are limited to 100 calls / minute.

You can see the number of API calls you have requested by calling the GET usage/me/requests endpoint. See our guide on accessing usage statistics for more details.