Usage Limits

This page explains the limits you are subject to when using the API, including use of the Export Console and Analytics 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.

Earned media historic 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 12 months of historical data. If so you can export data and run analytics on data from up to 12 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

Earned media documents per month

If you have access to the export or data streams feature, your package will limit you to a number of documents you can export from the platform per month. This limit is shared between your exports and data streams, so is the total number of documents you can take from the platform using exports or streaming features.

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

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

Earned media 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.

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.

API call limits

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

Earned media 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.

The day rate limit for a period begins when the first API request is sent after it has been reset to 0.

For example, a day rate limit period would start if the first API request is sent at 9:30am and finish 24 hours later when it is reset to 0 again. This is in contrast to the time periods for the usage statistics where the request counts for Last 7/30 days would consistently start at 12:00am UTC.

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 call limits

In addition to the daily analytics call limit of your package, all calls to earned media analytics endpoints are limited to 5 calls / second and 100 calls / minute.

Earned media streaming

Concurrent data streams

If you have access to the data streaming feature, your contract will state how many “Data Streams” you can run concurrently streaming data from the platform.

For example, if your contract says you can use 25 Data Streams, you can have up to 25 streams running from the API simultaneously.

You can see how many streams you have running by calling the GET /v3/hooks endpoint.

API call limits

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

  • POST /v3/hooks

General API call limits

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

Calls to endpoints, unless discussed above, 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.