News API - Social Engagement, Trending Stories, NewsWhip

Pull trending news articles, YouTube videos and Facebook posts with their real-time social engagement and predicted interactions into a dataset, a spreadsheet or a warehouse, one row per story. Uses your own NewsWhip API key, never changes anything, and charges only for rows that carry data.

What it collects

• Trending stories right now (Quick Start API, last 1 to 168 hours): top stories by region and topic (World, United States, Ireland and 200 more; Politics, Tech, Business, Sports and over 100 more topics), keyword search, every story from one publisher domain, and hyper-local stories for a city or local region.
• Social engagement per story: Facebook total engagement with likes, comments and shares, X (Twitter) influencer shares, LinkedIn and Pinterest counts, the change since the last check, the overperforming score against the publisher's normal performance, the current and maximum velocity score (nw_score), and the predicted interactions with the time the prediction is reached.
• Historical search from 2018 (Historical API): web articles and YouTube videos with Lucene filters on headline, summary, authors, country, region, language, topic, publisher, domain, URL and site path; full text search; related story grouping; sort by engagement, velocity, predicted interactions, overperformance or date. Ranges over 7 days are read in 7 day windows, newest first.
• URL lookup: engagement and metadata for specific article URLs, 5 per call.
• Facebook posts: posts from public pages with reactions (likes, loves, wows, hahas, sads, angrys), comments, shares, post type (native, live or embedded video, link, photo, status, branded content), page and the external link shared.
• Facebook influencers: the pages that drove the most engagement on matching content, with followers, likes and their top referred articles.
• Engagement statistics: count, min, max, average, sum and spread of Facebook, X, LinkedIn and Pinterest engagement, aggregated by publisher, domain, author, topic, language or country.
• Syndicated pickups (Syndication customers): where other publishers republished your content, with the match rate and the pickup's engagement.
• Read only, pay per result, bring your own key.

Input

Field	What it does
What to read	Top stories by region and topic (default, needs nothing else), keyword search, publisher stories, local stories, article and video search, URL lookup, Facebook posts, Facebook influencers, engagement statistics or syndicated pickups.
Region / Topic	Top stories by region. English names from the provider lists, such as World and Politics.
Time period (hours)	Region, publisher and local modes, 1 to 168.
Keywords	Keyword search; in historical modes, the single filter when no filters are set.
Publisher domain	Publisher mode, such as nytimes.com.
City or local region	Local mode, such as Seattle, WA or London.
Filters (Lucene)	Historical and syndication modes, such as country_code:us AND headline:tesla. Separate entries are joined with OR. Up to 20.
From / To	Historical modes, from 2018-01-01. Empty means the last 7 days.
Language	Two letter code such as en.
Content type	Web stories or YouTube videos (article search).
Sort by	Documented sort fields of the chosen route, always descending.
Group related stories, stories with video only, search full text, keyword fields	Article search options.
Facebook content type	Facebook posts: all, video kinds, link, photo, status, branded content.
Article URLs	URL lookup.
Aggregate statistics by / Sort statistics by	Engagement statistics, such as publisher and fb_total.sum.
Source article filters, source topics filter, match rate range	Syndicated pickups.
Maximum results	Row cap for the run (up to 50,000).
Requests per minute	Pacing, default 18.
API key	Your own NewsWhip API key, as a secret input.

Limits on the NewsWhip side

NewsWhip sells API access by subscription, separately from this actor's price:

• Rate limit: 100 requests per rolling 5 minutes and no more than 5 a second. The actor paces itself at 18 a minute by default and waits out any HTTP 429.
• Quick Start routes cover the last 168 hours and return up to 500 records a call; their answers are cached per key for about 3 minutes.
• Historical routes cover 2018 onwards, return up to 5,000 records a call, and work best with ranges of 7 days or less, so the actor splits longer ranges.
• Up to 20 filters per query and 150 terms per filter.
• Which routes your key can call depends on your plan: Historical routes need a Historical subscription, and syndicated pickups need the Syndication product. A route outside your plan is refused with HTTP 403 and the run ends cleanly.
• The provider retired its Instagram and trending entities routes, so Instagram posts are not available.

FAQ

What is a news API with social engagement data used for?

Finding the stories people are actually engaging with, while it is still early. Newsrooms watch top stories by region and topic to pick up what is spreading. Comms and PR teams search their brand and competitors and sort by predicted interactions to see which coverage will be big. Content and social teams pull the most shared stories in a niche to plan posts. Analysts export engagement statistics by publisher or author to benchmark outlets.

Which data source does this actor read?

The NewsWhip API at api.newswhip.com/v1, through the routes documented on the NewsWhip developer hub (developer.newswhip.com): the Quick Start routes /search, /publisher, /region and /local, the Historical routes /articles, /articlesByHrefs, /fbPosts, /fbInfluencers and /stats, and the Syndication route /syndicatedArticles. Docs and the live host were checked on 2026-10-03.

Do I need a NewsWhip API key?

Yes. This actor is bring-your-own-key and never ships one. NewsWhip issues an API key with an API subscription or trial. Paste it into the input, or set it once as the DATA_API_KEY environment secret. A missing, expired or refused key ends the run cleanly with a message saying which it was.

What are predicted interactions and the velocity score?

predictedInteractions is NewsWhip's forecast of the total Facebook engagement plus X influencer shares a story will reach, and predictedAt is when it expects to reach it. nwScore is the current social velocity (how fast engagement is growing) and maxNwScore the highest velocity so far. facebookOverperforming compares a story's Facebook performance with the publisher's usual average.

How do I get the top political stories in the United States today?

Choose top stories by region, set the region to United States, the topic to Politics and the time period to 24 hours. Rows come back ranked by the provider, each with engagement and predicted interactions.

How far back can I search, and how many results can one run return?

Historical modes reach back to 2018. One call returns up to 5,000 records, so for a long range the actor reads 7 day windows newest first until it has the maximum results you set (up to 50,000 a run). Quick Start modes cover the last 168 hours and return up to 500 records.

Can this actor change anything in my NewsWhip account?

No. The GET routes read, and the POST routes are the provider's documented search queries; the public API has no write routes. NewsWhip only accepts the key as a URL parameter; the actor never logs it and strips it from any error text.

How is it priced?

Pay per result: one price per story, video, Facebook post or syndicated pickup, and a lower price per influencer or statistics row. Searches and URLs that find nothing are free. Your NewsWhip subscription applies separately.

Example output

{
  "mode": "region",
  "modeLabel": "Top stories by region and topic",
  "recordType": "story",
  "found": true,
  "id": "97b2ca00-31f7-11e8-be5b-ef989ddb8d11",
  "name": "Example headline about a breaking story",
  "title": "Example headline about a breaking story",
  "url": "https://www.example-news.com/2026/10/02/example-story.html",
  "excerpt": "A short extract of the story.",
  "publisher": "example-news.com",
  "domain": "example-news.com",
  "country": "United States",
  "countryCode": "us",
  "language": "en",
  "authors": null,
  "publishedAt": "2026-10-02T07:42:52.000Z",
  "facebookEngagement": 438712,
  "facebookLikes": 391020,
  "facebookComments": 28110,
  "facebookShares": 19582,
  "facebookOverperforming": 27.79,
  "twitterShares": 31157,
  "twitterOverperforming": 20.06,
  "linkedinEngagement": 0,
  "pinterestPins": 22,
  "predictedInteractions": 1131719,
  "predictedAt": "2026-10-02T15:43:59.279Z",
  "nwScore": 532.89,
  "maxNwScore": 5263.77,
  "value": 438712,
  "relatedStoriesCount": 0,
  "fb_data": { "total_engagement_count": 438712, "likes": 391020, "comments": 28110, "shares": 19582, "total_count_delta": 121080, "delta_period": 292, "delta_period_unit": "m", "fb_overperforming": 27.79 },
  "image_link": "https://www.example-news.com/images/example.jpg",
  "has_video": false,
  "topics": [],
  "entities": [],
  "retrievedAt": "2026-10-03T09:14:52.118Z",
  "note": null
}

Values are illustrative; every field is one the provider documents. Facebook post rows add pageId, pageName, postType, reactions and externalLink; influencer rows add followersCount, likesCount, maxFbInteractions and social_referrals; statistics rows add aggregateBy, totalMatchedArticles and per network facebookStats, twitterStats, linkedinStats and pinterestStats; syndicated pickups add matchRate and syndicationStoryId.

Keyword map

news API, trending news API, social engagement API, news engagement data, viral content API, predicted engagement, story velocity, top stories by country, local news API, publisher analytics, Facebook posts API, Facebook page influencers, YouTube video engagement, content syndication tracking, media intelligence API, NewsWhip API, NewsWhip historical API.