Frequently Asked Questions

Frequently asked questions (FAQs) from API customers.

How can I get access to the earned media analytics features of the API?

Please speak to your account manager to check if you package has access to analytics features.

How can I get access to the owned social analytics features of the API?

Please speak to your account manager to check if you package has access to these features.

Do you have an SDK or Client Libraries?

Currently, we do not create our own, though we do provide an Open API specification which allows you to generate your own.

How do filters for my Explore searches work with the API?

If you set any filters in your Saved Search, such as limiting to a country or language, then we preserve those filters in your API requests.

Any additional parameters you supply, such as a country or language for an analytics request will be added will be additionally applied. This means that if your Saved Search has a country filter of “US” and your API request specifies “CA” as a country then you will receive 0 results. This is because we additionally filter your existing Saved Search to also limit country to “CA”. No documents can have a country of “US” and “CA” so no results are returned.

How much data can I export using the API?

Please take a look at the Usage Limits page.

What are your API rate limits?

Please take a look at the Usage Limits page.

How many exports can I run at one time?

You can create as many exports as you want. However only one export will be processed at a time. If you have scheduled multiple exports at the same time, all outstanding exports will remain in a PENDING state until the first export completes. Once the running export is complete, the next PENDING export will be processed.

How many searches can I use for an earned media export?

For an export request you can specify up to 5 searches or tags.

How long does it take to generate my earned media export?

Generating an export takes anywhere from a few minutes to 30 minutes. The more data involved and the bigger the time period, the longer it will take for an export to complete.

Please take this into consideration when configuring scheduled refresh in your BI tool or any other service consuming the exported data.

When will the data for my recurring earned media exports be refreshed?

Your export will be refreshed 30 minutes after the end of the time period that you have selected for your export. For example if you run a daily export starting at 00:00, then your export will begin to refresh at 00:30.

This 30 minute buffer makes sure that our system has been able to ingest all data for the time period that you have requested.

Does the export window include the “Start Date” and “End Date”?

The export time window begins at, and includes the Start Date, and continues up to, but not including the End Date.

For example: If you want to include all the documents published on December 25th, 2018. You would choose use a Start Date of 2018-12-25T00:00:00 and End Date of 2018-12-26T00:00:00.

What are the different status values for an export?

  • PENDING - Export is waiting to be processed, or is currently being processed.
  • ACTIVE - (recurring exports only) Export has data available and will be refreshed periodically.
  • FINISHED - (one-time export only) Export is complete and data is available.
  • EXPIRED - (one-time export only) Export is older than 60 days, data is no longer available.
  • INCOMPLETE - (one-time export only) Export in finished, but the data is incomplete, you’ll need to re-create the export to get the full set of results.
  • CANCELLED - Export was cancelled by user or administrator. This can happen if the search associated with the export was deleted, or of access to the API has been removed. Data will no longer be accessible for this export.

Do you delete exported data? And when?

For one-time exports, we automatically delete exported data 60 days after the export is executed.

For recurring exports, your exports will be updated on your defined time schedule always providing the newest exported data. If you do not access the data for a recurring export for over 60 days your recurring export will be cancelled.

What is the encoding of timestamps?

All dates are encoded using ISO 8601 format.

What is the encoding of strings?

All strings are encoded with UTF-8.

Why aren't all the keywords I expect in the matched keywords list?

The keywords for document_matched_keywords are collected from the highlights for the matched document. The highlights is a fragment of the document with a certain length. If the document matches a lot of keywords they might exceed the fragment length, and thus won’t be included in the list.