# Emerging Trend Monitor (`primeselectai/emerging-topic-trend-monitor`) Actor

Find rising topics for TikTok and social content planning with GDELT news data. Get deduplicated topic clusters, momentum scores, entities, tone, source URLs, and change records for repeat monitoring.

- **URL**: https://apify.com/primeselectai/emerging-topic-trend-monitor.md
- **Developed by:** [Simon Jessen](https://apify.com/primeselectai) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 25.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 results

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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Emerging Topic Trend Monitor

Emerging Topic Trend Monitor helps you turn public news momentum into better short-form content decisions. Run a query, receive ranked deduplicated topic clusters and source records, then use the included momentum and change fields to decide what deserves research or production. Configuration comes after the buyer sees the output shape.

### Outcome

Find fast-growing topics, narratives, entities, and sentiment shifts from global news coverage so teams can validate and prioritize content opportunities before investing in TikTok production.

### Use cases

- Use the Actor when you need find fast-growing topics, narratives, entities, and sentiment shifts from global news coverage so teams can validate and prioritize content opportunities before investing in TikTok production.
- Build workflows around a repeat-use trend intelligence layer rather than a TikTok scraper: normalize GDELT article metadata into topic clusters, deduplicate coverage, calculate momentum and tone changes across time windows, rank entities and locations, and emit delta records suitable for content planning and alerts.
- Designed for TikTok agencies, creator teams, social media strategists, trend researchers, brand marketers, and content-planning platforms.
- Schedule repeat runs: Daily or weekly monitoring of saved queries, with new-cluster detection, momentum changes, source diversification, and historical comparison.
- Feed normalized dataset records into APIs, spreadsheets, databases, automations, or AI/agent workflows.

### Quick start

1. Open the Actor input form.
2. Set the filters or query relevant to your workflow.
3. Start with a small `maxResults` value.
4. Run the Actor and inspect the default dataset before scheduling larger or recurring jobs.

Example input:

```json
{
  "query": "renewable energy",
  "maxResults": 10,
  "timespan": "7d",
  "mode": "artlist"
}
```

### Inputs

- **query** (string, required) — A keyword, phrase, Boolean expression, or GDELT-supported search query representing the topic to monitor.
- **timespan** (string, optional) — GDELT timespan such as 1d, 7d, 30d, or 90d. Defaults to 7d.
- **maxResults** (integer, optional) — Maximum number of article records to retrieve before normalization and deduplication. Defaults to 100.
- **language** (string, optional) — Optional language filter such as English, Spanish, French, or All.
- **country** (string, optional) — Optional country or region filter for source coverage.
- **previousRunAt** (string, optional) — Optional ISO timestamp used by downstream processing to identify newly observed or materially changed records.
- **mode** (string, optional) — GDELT DOC API response mode. Artlist returns article metadata records.

### Output example

The example below is taken from the latest validated local live-source sample when available; otherwise it is derived from the bundled dataset schema.

```json
{
  "id": "https://www.dostor.org/5684843",
  "query": "",
  "title": "وزير الكهرباء يبحث مع « مصدر » الإماراتية تسريع مشروعات الطاقة المتجددة في مصر",
  "url": "https://www.dostor.org/5684843",
  "domain": "dostor.org",
  "sourceCountry": "Egypt",
  "language": "Arabic",
  "publishedAt": "20260829T134500Z",
  "tone": null,
  "themes": [],
  "entities": [],
  "clusterKey": "https://www.dostor.org/5684843",
  "clusterSize": 1,
  "momentumScore": null,
  "changeType": "new",
  "attribution": "Data source: GDELT Project (https://gdeltproject.org/)."
}
```

### Pricing

Store pricing is configured in Apify. The intended primary paid unit is **completed trend-monitoring job**. Start with a small result limit while validating your workflow, then scale only when the output and economics fit your use case. The README never hard-codes a price that could drift from the live Store configuration.

### Source and limitations

- Source: GDELT 2.0 DOC API.
- Licence/terms: GDELT Project Terms of Use; no separate SPDX license stated.
- Reuse condition: GDELT states that its datasets may be used for unlimited and unrestricted academic, commercial, or governmental use and may be redistributed, rehosted, republished, or mirrored, provided that use or redistribution cites the GDELT Project and links to its website. This Actor should return structured metadata, short snippets where available, source URLs, and derived trend signals; it must not imply endorsement or republish full third-party article text, images, logos, or publisher content. No standalone resale or competing-data-product prohibition was found in the GDELT Project Terms of Use. GDELT Cloud terms are different and prohibit redistribution, so this Actor must use the GDELT Project API directly rather than GDELT Cloud.
- Automation condition: Use HTTP GET requests, bounded pagination, caching, deduplication, exponential backoff, and conservative concurrency. The GDELT Project documents the API and open data but does not provide a clearly stated universal request-rate guarantee in the reviewed sources; treat rate limits as UNKNOWN and implement configurable throttling.
- This is a compliant substitute for TikTok public-content collection, not TikTok-native data; it measures public news and media momentum rather than TikTok views, likes, comments, or creator metrics.
- Third-party article headlines, snippets, images, logos, and trademarks may carry publisher-specific rights. Limit outputs to metadata, short permitted fields, source URLs, and derived signals; do not republish full article content.
- GDELT coverage is biased toward indexed online news and may overrepresent English-language, highly covered, or politically salient topics.
- GDELT documentation does not establish a universal guaranteed API rate limit; conservative throttling and monitoring are required.
- The Actor must use the GDELT Project endpoint directly. GDELT Cloud is not an acceptable upstream because its current policy prohibits third-party redistribution without a separate written license.

This Actor does not bypass authentication, rate limits, robots/API policies, licensing conditions, or upstream access controls. Missing upstream values are not invented.

### FAQ

**Does this use the approved source contract?**\
Yes. Runtime requests are restricted to the source contract validated by Market Hunter before build.

**Can I schedule repeat runs?**\
Yes, when the source permits automated access. Use conservative schedules and result limits that respect upstream conditions.

**Why can some fields be empty or null?**\
The upstream source may omit fields for particular records. The Actor preserves missing values rather than fabricating data.

### Troubleshooting

- If a narrow query returns no rows, loosen filters and retry with a small result limit.
- If the upstream source returns a rate-limit or temporary server error, retry later instead of increasing request pressure.
- If authentication or source identity is required, verify the protected credential/identity configured for the Actor.
- If the upstream response schema changes, report the failed run so the deterministic mapping can be updated.

### Related Actors

- brand-mention-trend-monitor
- news-entity-cooccurrence-monitor
- geopolitical-event-monitor
- social-content-keyword-brief-generator

> Store publication remains an explicit manual action. This product is not affiliated with or endorsed by the upstream source unless the Store listing explicitly states otherwise.

# Actor input Schema

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

A keyword, phrase, Boolean expression, or GDELT-supported search query representing the topic to monitor.

## `timespan` (type: `string`):

GDELT timespan such as 1d, 7d, 30d, or 90d. Defaults to 7d.

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

Maximum number of article records to retrieve before normalization and deduplication. Defaults to 100.

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

Optional language filter such as English, Spanish, French, or All.

## `country` (type: `string`):

Optional country or region filter for source coverage.

## `previousRunAt` (type: `string`):

Optional ISO timestamp used by downstream processing to identify newly observed or materially changed records.

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

GDELT DOC API response mode. Artlist returns article metadata records.

## Actor input object example

```json
{
  "query": "renewable energy",
  "timespan": "7d",
  "maxResults": 10,
  "mode": "artlist"
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `runMeta` (type: `string`):

No description

# 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 = {
    "query": "renewable energy",
    "timespan": "7d",
    "maxResults": 10,
    "mode": "artlist"
};

// Run the Actor and wait for it to finish
const run = await client.actor("primeselectai/emerging-topic-trend-monitor").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 = {
    "query": "renewable energy",
    "timespan": "7d",
    "maxResults": 10,
    "mode": "artlist",
}

# Run the Actor and wait for it to finish
run = client.actor("primeselectai/emerging-topic-trend-monitor").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 '{
  "query": "renewable energy",
  "timespan": "7d",
  "maxResults": 10,
  "mode": "artlist"
}' |
apify call primeselectai/emerging-topic-trend-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,primeselectai/emerging-topic-trend-monitor"
        }
    }
}

```

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/imN5QOUWhGNJX14oj/builds/dt9vCNbzW3NtmM7OH/openapi.json