To use this endpoint you will need the following reference data:


Time range

The maximum range between the from and to dates in your query should not exceed 7 days.


Naming differences

For historical reasons, the queryable fields headline and summary differ in naming from their Article counterparts link and excerpt.


The following filtering options can be used in the filters body parameter.

country_codeStringTwo letter (lower case) ISO 3166 country code.
region_codeStringAvailable regions (lower case):
na North America
eu Europe
oc Oceania
sea South East Asia
sa South America
as Asia
me Middle East
af Africa
languageStringSupported languages are listed in Supported Languages.
categoriesNumberSupported categories are listed in Topics.
publisherStringTLD such as
domainStringExact domain where the article was published. e.g.
domainsStringThe possible permutations of publisher and subdomains. See this section of the data dictionary for an explanation of the difference between publisher, domain, and domains.
hrefStringSearch by the full url of the article eg. "href:\"\""
siteStructureHandy for articles that follows a particular path on a site, e.g: to look for all articles with url follows "", use filter with AND siteStructure:\\/tags\\/politics or AND siteStructure:"/tags/politics" will be sufficient.

Sort By

For all content types or the stories content type

Sorts one of the following in descending order:

  • default
  • fb_total_engagement
  • fb_tw_overperforming
  • fb_overperforming
  • tw_overperforming
  • predicted_interactions
  • twitter
  • linkedin
  • fb_tw_and_li
  • fb_tw_li_and_pi
  • nw_max_score
  • created_at

The default sort_by is nw_max_score when the selected time range is <= 25h, otherwise it will be fb_tw_overperforming.

For the youtube content type

When the content_type is set to youtube, the default sort order is by created_at. You can also sort in descending order by

  • yt_likes
  • yt_views
  • yt_comments
  • created_at.
Click Try It! to start a request and see the response here!