# News API - Social Engagement, Trending Stories, NewsWhip (`nabeelbaghoor/news-api-social-engagement-data`) Actor

Search news articles, YouTube videos and Facebook posts with real-time social engagement and predicted interactions from your own NewsWhip API key: trending stories by region, topic, city or publisher, history from 2018, top Facebook pages, engagement stats and syndication pickups. Read only.

- **URL**: https://apify.com/nabeelbaghoor/news-api-social-engagement-data.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community)
- **Categories:** News, Social media, Marketing
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 story or post returneds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 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

```json
{
  "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.

# Actor input Schema

## `mode` (type: `string`):

Top stories by region and topic needs nothing else, so it is the default. The first four modes are the Quick Start API (last 168 hours, up to 500 records a call). Article and video search, URL lookup, Facebook posts, Facebook influencers and engagement statistics are the Historical API (from 2018). Syndicated pickups needs a Syndication subscription.

## `region` (type: `string`):

Top stories by region. A region or country name in English from the provider Regions list, such as World, United States, Ireland or Germany.

## `category` (type: `string`):

Top stories by region. A topic name in English from the provider Topics list, such as All, Politics, Tech, Business, Sports or Entertainment.

## `timePeriodHours` (type: `integer`):

Region, publisher and local stories. Read stories published within the last 1 to 168 hours.

## `query` (type: `string`):

Keyword search: the keywords or phrase to find, such as electric cars. Historical modes: used as the single filter when no filters are set, searching headline, summary and authors.

## `publisher` (type: `string`):

Publisher stories. A domain or subdomain, such as nytimes.com or blog.newswhip.com.

## `city` (type: `string`):

Local stories. A local region from the provider list, such as Seattle, WA, New York, NY, London, Toronto or Hamburg-Schleswig-Holstein.

## `filters` (type: `array`):

Historical modes and syndicated pickups. Lucene filter strings on documented fields: headline, summary, authors, country_code, region_code, language, categories (topic IDs), publisher, domain, domains, href, siteStructure; for Facebook posts also page_id, page_name, external_link, fb_story. Separate entries are joined with OR, so put AND inside one entry. Up to 20 filters.

## `from` (type: `string`):

Historical modes. Start date as YYYY-MM-DD, an ISO date and time, or epoch milliseconds, from 2018-01-01. Leave both dates empty for the provider default of the last 7 days. Searches over more than 7 days are read in 7 day windows, newest first.

## `to` (type: `string`):

Historical modes. End date in the same formats. Defaults to now.

## `language` (type: `string`):

Historical modes. A two letter ISO 639-1 code, such as en, de, fr or es. Empty means any language.

## `articleContentType` (type: `string`):

Article and video search. Web stories or YouTube videos.

## `sortBy` (type: `string`):

Article, Facebook post and syndication searches, always descending. Default is velocity (nw_max_score) for ranges up to 25 hours, otherwise overperformance. Web stories: 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. YouTube: yt_likes, yt_views, yt_comments, created_at. Facebook posts: nw_max_score, fb_overperforming, fb_total_engagement, created_at and each reaction. Syndication adds match_rate and nw_score.

## `findRelated` (type: `boolean`):

Article search, web stories. Collapse stories with near-identical headlines into the relatedStories list of the best match.

## `videoOnly` (type: `boolean`):

Article search, web stories. Keep only stories with a detected video.

## `searchFullText` (type: `boolean`):

Article search. Match keywords against the full article text, not only headline, summary and authors.

## `defaultFields` (type: `array`):

Article search, Facebook posts and statistics. Up to 3 fields that plain keywords search. Articles default to headline, summary and authors; Facebook posts to page_name and external_link.

## `fbContentType` (type: `string`):

Facebook posts. All posts, or only videos, embedded, native or live video, links, photos, status updates or branded content.

## `hrefs` (type: `array`):

URL lookup. Full article URLs to fetch with their engagement; sent 5 per call. A URL the provider does not hold becomes an uncharged row.

## `statsAggregateBy` (type: `string`):

Engagement statistics. Group matching content by publisher, all domain permutations (domains), exact domain, language, authors, topic (categories) or country.

## `statsSortBy` (type: `string`):

Engagement statistics. A network (fb_total, twitter, pinterest, linkedin) and a statistic (count, min, max, avg, sum, sum_of_squares, variance, std_deviation).

## `syndicationFilters` (type: `array`):

Syndicated pickups. Lucene filters on your own source articles: headline, authors, summary, language, syndication_story_id.

## `syndicationTopicsFilter` (type: `string`):

Syndicated pickups. A Lucene filter on your syndication topics (\_type and \_value).

## `minMatchRate` (type: `integer`):

Syndicated pickups. Lowest text match percentage. The provider defaults to 10.

## `maxMatchRate` (type: `integer`):

Syndicated pickups. Highest text match percentage. The provider defaults to 100.

## `maxResults` (type: `integer`):

The most rows this run returns and charges for. One call returns up to 500 records on Quick Start routes and 5,000 on Historical routes; longer Historical ranges are read window by window.

## `requestsPerMinute` (type: `integer`):

Pacing. The provider allows 100 calls per rolling 5 minutes and 5 a second; raise this only if your contract allows more.

## `apiKey` (type: `string`):

Your own NewsWhip API key, issued with your API subscription. Stored as a secret. You can instead set the DATA_API_KEY environment secret.

## Actor input object example

```json
{
  "mode": "region",
  "region": "World",
  "category": "All",
  "timePeriodHours": 24,
  "articleContentType": "stories",
  "sortBy": "default",
  "findRelated": true,
  "videoOnly": false,
  "searchFullText": false,
  "fbContentType": "all",
  "statsAggregateBy": "publisher",
  "statsSortBy": "fb_total.sum",
  "maxResults": 100,
  "requestsPerMinute": 18
}
```

# Actor output Schema

## `records` (type: `string`):

One row per story, Facebook post, influencer or statistics group.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/news-api-social-engagement-data").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/news-api-social-engagement-data").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call nabeelbaghoor/news-api-social-engagement-data --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/news-api-social-engagement-data"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/DI8Gkq48ZoqXM3asv/builds/ybxpsnr5TBfvuwa6o/openapi.json