Brand News Monitor & GDELT Mention Alerts

Monitor global brand news and receive only genuinely new mentions

Track brands, companies, products, executives, competitors, or topics across global online news through the GDELT DOC 2.0 API.

This Actor is stateful. Each brand × language × source-country dimension remembers what it has already shown you, so scheduled runs do not keep billing the same article again.

The first successful observation creates a free baseline. Later runs emit NEW_MENTION only for article URLs that have not already been seen in that monitoring dimension.

An optional second deduplication layer catches syndicated republications that reuse the same normalized headline under a different URL.

No browser automation. No news-site login. No LLM or fuzzy matching in runtime.

Key features

• Stateful brand-news monitoring
• Genuinely new article mentions only
• Persistent deduplication by publisher URL
• Optional normalized-title deduplication
• Free first-run baseline
• Brand, company, product, executive, competitor, or topic queries
• Language filtering
• Source-country filtering
• Independent brand × language × country state
• Publisher URL
• Article title
• Publisher domain
• Article/source language
• Source country
• GDELT seen date
• Per-dimension article velocity
• Top publisher domains in the current window
• Top domains among delivered new mentions
• Free BRAND_SUMMARY on every successful dimension
• Free RUN_SUMMARY
• Up to 40 monitored dimensions per run
• Controlled GDELT request pacing
• Pay Per Event

Unofficial community Actor. Not affiliated with, sponsored by, or endorsed by the GDELT Project or by any publisher returned in the results. Data comes from the GDELT Project. GDELT's published Terms of Use permit commercial use and redistribution of its datasets, with GDELT attribution required when the data is redistributed.

---

What this Actor is for

A news scraper answers:

Which articles match this query right now?

A monitoring product should answer:

Which matching articles are new since I last checked?

This Actor maintains persistent state for every monitored dimension and is designed for:

• brand monitoring;
• PR and communications;
• media intelligence;
• competitor monitoring;
• executive monitoring;
• product-launch coverage;
• reputation research;
• crisis monitoring;
• market research;
• recurring media reports;
• Slack/news alert workflows;
• data warehouses and dashboards.

---

Important: first run is a free baseline

For each new:

brand × language × country

dimension, the first successful run learns the current article IDs.

It does not present those existing rows as new mentions.

Example:

First run
75 articles in the GDELT window
75 URLs learned
0 NEW_MENTION records

If later 6 unseen article URLs appear:

Next run
6 genuinely unseen mentions
6 NEW_MENTION records

This prevents normal lookback overlap from becoming repeated billing.

---

Persistent novelty state

The primary deduplication identity is derived from the publisher URL returned by GDELT.

The Actor computes a deterministic 16-character ID from:

SHA-256(article URL)

and persists it for the monitoring dimension.

A NEW_MENTION therefore means:

this article URL was not already present
in this brand × language × country state

---

Optional title deduplication

By default:

{
  "dedupeTitles": true
}

The Actor also normalizes titles by:

• lowercasing;
• removing accents;
• collapsing punctuation/whitespace.

Example:

Company X Launches New Product!

and:

company x launches new product

normalize to the same deterministic title key.

If that title was already seen, a different URL can be suppressed as a likely syndicated republication.

Important

This is exact normalized-title matching.

It is not:

• fuzzy matching;
• semantic similarity;
• clustering;
• AI classification.

Two genuinely different stories with the same normalized headline can therefore be treated as duplicates when title deduplication is enabled.

Disable it when URL-level novelty is more important than syndication suppression.

---

Who it's for

PR and communications teams

Monitor:

• company name;
• product names;
• executives;
• campaigns;
• major announcements.

Send new mentions to a media-review workflow instead of manually re-running searches.

Brand and reputation teams

Build recurring visibility into:

• mention velocity;
• publisher domains;
• languages;
• source countries;
• genuinely new article coverage.

Agencies

Use separate labels and queries for multiple clients, brands, campaigns, or executives.

Competitive intelligence teams

Track public coverage of competitors or sectors.

Automation and data teams

Connect results to:

• Slack;
• Microsoft Teams;
• email workflows;
• n8n;
• Make;
• webhooks;
• databases;
• BI tools;
• dashboards;
• AI analysis downstream.

The Actor itself does not read article bodies or generate AI summaries.

---

Data source — GDELT DOC 2.0

The Actor uses:

https://api.gdeltproject.org/api/v2/doc/doc

with:

mode=artlist
format=json
sort=datedesc

The query can also include GDELT filters for:

sourcelang
sourcecountry

The implementation deliberately spaces GDELT API requests by at least 5 seconds and retries controlled rate-limit or transient failures with bounded backoff.

---

GDELT usage terms

GDELT describes itself as an open platform for research and analysis.

Its published Terms of Use state that GDELT datasets may be used for academic, commercial, and governmental purposes without a dataset fee.

GDELT also permits redistribution/rehosting of its datasets, with attribution to the GDELT Project and a link to the project website required when redistributing the data.

Source:

https://www.gdeltproject.org/about.html

This Actor returns article metadata and publisher URLs from GDELT.

Users remain responsible for how they use publisher content and for any rights or terms that apply to the destination articles themselves.

---

Input

Recommended example

{
  "brands": [
    {
      "query": "\"Anthropic\"",
      "label": "Anthropic"
    },
    {
      "query": "\"OpenAI\"",
      "label": "OpenAI"
    }
  ],
  "languages": [
    "english"
  ],
  "countries": [],
  "timespanHours": 72,
  "maxRecordsPerQuery": 75,
  "dedupeTitles": true,
  "maxResults": 500,
  "maxRuntimeMs": 300000
}

Input fields

Field	Default	Description
brands	required	GDELT brand/topic queries. Bare strings or { query, label } objects.
languages	["english"]	GDELT sourcelang values. Empty list = all languages as one dimension.
countries	[]	GDELT sourcecountry codes. Empty list = all source countries.
timespanHours	72	GDELT lookback window. Range: 1–168 hours.
maxRecordsPerQuery	75	Maximum article rows read per dimension. Range: 10–250.
dedupeTitles	true	Optional second deduplication layer by normalized headline.
maxResults	500	Maximum billable NEW_MENTION records. Range: 1–5,000.
maxRuntimeMs	300000	Hard runtime cap in milliseconds.
debug	false	Additional diagnostic logging.

---

Brand query format

You can use a bare string:

{
  "brands": [
    "\"Anthropic\""
  ]
}

or provide a label:

{
  "brands": [
    {
      "query": "\"Anthropic\"",
      "label": "Anthropic"
    }
  ]
}

The query is passed into the GDELT DOC query expression.

For exact brand names, quoting the phrase is often useful:

"Anthropic"
"OpenAI"
"Acme Corporation"

The Actor does not rewrite the user's GDELT query into an AI-generated search expression.

---

Brand labels and persistent state

Persistent state is keyed partly by a normalized brand label.

Therefore two different queries must not use labels that normalize to the same slug.

Example of an invalid collision:

{
  "brands": [
    {
      "query": "\"Acme\"",
      "label": "Acme"
    },
    {
      "query": "\"Acme AI\"",
      "label": "ACME"
    }
  ]
}

Both labels normalize to:

acme

The revised validator rejects that collision instead of silently sharing or dropping state.

Exact duplicate entries with the same normalized label and same query are deduplicated.

---

Language dimensions

Example:

{
  "languages": [
    "english",
    "portuguese"
  ]
}

creates independent dimensions such as:

anthropic / english / all-countries
anthropic / portuguese / all-countries

Leave the array empty to monitor all languages as one dimension:

{
  "languages": []
}

Use the empty-list form for "all languages"; the literal string all is rejected.

---

Source-country dimensions

Example:

{
  "countries": [
    "US",
    "BR"
  ]
}

creates separate country dimensions.

Leave the list empty for all source countries:

{
  "countries": []
}

Use the empty-list form for all countries; the literal ALL is rejected.

---

Dimension cap

The number of monitored dimensions is:

brands × language dimensions × country dimensions

Maximum:

40

Examples:

10 brands × 1 language × all countries = 10 dimensions
5 brands × 2 languages × 3 countries = 30 dimensions
10 brands × 2 languages × 3 countries = 60 dimensions → invalid

The cap exists because GDELT requests are intentionally paced.

Split larger portfolios across separate Tasks.

---

Collection window and schedule overlap

The default:

{
  "timespanHours": 72
}

is intentionally larger than a daily schedule interval.

That creates overlap.

Overlap is useful because it reduces the chance that an article falls between two runs.

Persistent deduplication means the overlap should not create a second NEW_MENTION charge for an already-seen URL.

---

Article read cap

GDELT returns at most the configured:

maxRecordsPerQuery

for each dimension.

Current Actor range:

10–250

If more matching news articles exist in the lookback window than the requested result cap, older matching articles can be outside the returned slice.

For very high-volume brands:

• reduce timespanHours;
• schedule more frequently;
• raise maxRecordsPerQuery up to 250;
• narrow the query/language/country.

---

Output

The dataset can contain:

NEW_MENTION
BRAND_SUMMARY
RUN_SUMMARY

---

NEW_MENTION

This is the billable record.

It is emitted only when:

• the monitored dimension is past baseline;
• the article has a usable publisher URL;
• the URL identity was not already seen;
• optional title deduplication does not suppress it;
• result/runtime/billing caps allow delivery.

Example

{
  "recordType": "NEW_MENTION",
  "entityId": "listening:news:anthropic/72f9063c2bedf361",
  "source": "news",
  "brand": "anthropic",
  "brandLabel": "Anthropic",
  "query": "\"Anthropic\"",
  "url": "https://example.com/news/anthropic-announcement",
  "title": "Anthropic Announces New Product",
  "domain": "example.com",
  "language": "English",
  "sourcecountry": "United States",
  "seendate": "2026-08-26T13:15:00Z",
  "mentionId": "72f9063c2bedf361",
  "observedAt": "2026-08-26T17:00:00.000Z"
}

---

NEW_MENTION fields

Field	Description
recordType	NEW_MENTION.
entityId	Stable JM Forge mention identity.
source	news.
brand	Normalized brand slug.
brandLabel	User-facing brand label.
query	GDELT query used for this brand.
url	Publisher article URL returned by GDELT.
title	Article title.
domain	Publisher domain.
language	Language returned by GDELT.
sourcecountry	Source country returned by GDELT.
seendate	GDELT seen date normalized to ISO when possible.
mentionId	Deterministic URL-derived identity.
observedAt	Actor observation timestamp.

---

What this Actor does not extract

The current contract does not return:

full article body
author/byline
publisher audience/reach
social share count
sentiment
article summary
AI topic classification

It returns GDELT article metadata and a publisher URL.

Use a separate content-extraction or AI-analysis step downstream when needed.

---

BRAND_SUMMARY

Every successfully processed dimension receives a free summary.

It can include:

brand
brandLabel
language
country
baseline
articlesInWindow
newMentions
mentionsDelivered
seenBefore
skippedNoUrl
velocityPer24h
topDomains
topNewMentionDomains
observedAt

---

Article velocity

The free:

velocityPer24h

normalizes the number of articles returned by the configured GDELT window to a 24-hour rate.

Example:

72-hour window
90 articles returned
velocityPer24h = 30

Honest limitation

This is based on the article rows actually returned by GDELT inside maxRecordsPerQuery.

If the query is truncated by the per-dimension result cap, the calculated velocity is a lower-bound representation of the returned slice rather than a complete count of every matching article.

---

Publisher-domain intelligence

BRAND_SUMMARY.topDomains now represents the top publisher domains among all article rows returned in the current GDELT window.

BRAND_SUMMARY.topNewMentionDomains represents the top domains among NEW_MENTION records actually delivered in the current run.

This distinction makes a quiet run useful:

no new billable mention
but current source mix remains visible

---

RUN_SUMMARY

The free final summary can include:

billableRecords
freeRecords
baselineDimensions
httpRequests
http429
httpRetries
topDomainsOverall
capReason
qualityAlert
sourceUnavailable
warnings
units
cost
pricingLabel

topDomainsOverall refers to publisher domains among the billable new mentions delivered across the run.

---

Persistent state limits

Each monitored dimension keeps bounded state for up to:

5,000 URL identities
5,000 normalized title keys

The newest retained entries win as the state grows.

For ordinary brand monitoring this provides a long dedup horizon.

Very high-volume monitoring dimensions can eventually age old identities out of bounded state.

---

Request pacing and retries

GDELT APIs are rate limited.

The Actor enforces a minimum:

5 seconds

between GDELT requests.

Transient failures can use controlled retry delays with jitter.

The Actor tracks:

httpRequests
http429
httpRetries

and surfaces source/quality problems instead of fabricating articles.

---

Scheduling

This Actor is designed for scheduled monitoring.

A practical starting configuration:

daily schedule
72-hour lookback

The overlapping window reduces gaps while persistent state suppresses repeated URLs.

For fast-moving campaigns or crises, use a shorter schedule if the query volume can exceed your maxRecordsPerQuery window between runs.

---

Recommended scheduled workflow

1. Add the brand queries.
2. Run once to create free baseline state.
3. Save the input as an Apify Task.
4. Open Schedules.
5. Choose the cadence.
6. Send future NEW_MENTION records downstream.

Possible destinations:

• Slack;
• Microsoft Teams;
• email workflows;
• n8n;
• Make;
• Google Sheets;
• databases;
• PR dashboards;
• internal applications.

---

Example multi-market monitoring input

{
  "brands": [
    {
      "query": "\"Example Brand\"",
      "label": "Example Brand"
    }
  ],
  "languages": [
    "english",
    "portuguese"
  ],
  "countries": [
    "US",
    "BR"
  ],
  "timespanHours": 48,
  "maxRecordsPerQuery": 150,
  "dedupeTitles": true,
  "maxResults": 500
}

This creates four independent dimensions:

Example Brand / english / US
Example Brand / english / BR
Example Brand / portuguese / US
Example Brand / portuguese / BR

---

API

Run the Actor through the Apify API:

curl -s "https://api.apify.com/v2/acts/<YOUR_USERNAME>~brand-news-monitor/run-sync-get-dataset-items?token=<YOUR_APIFY_TOKEN>" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "brands":[
      {"query":"\"Anthropic\"","label":"Anthropic"}
    ],
    "languages":["english"],
    "countries":[],
    "timespanHours":72,
    "maxResults":500
  }'

Replace:

<YOUR_USERNAME>
<YOUR_APIFY_TOKEN>

with your Apify account values.

---

Integrations

Use with:

• Apify API;
• Tasks;
• Schedules;
• webhooks;
• n8n;
• Make;
• Slack;
• Microsoft Teams;
• Google Sheets;
• databases;
• BI tools;
• internal applications;
• AI agents downstream.

---

Pricing

This Actor uses Pay Per Event.

The code uses two custom billing events:

actor-start
new-mention

actor-start

Called once after valid input has been accepted.

Invalid input is rejected before the billing gate opens.

new-mention

Charged per delivered NEW_MENTION.

The Actor does not charge new-mention for:

• first-run baseline articles;
• URLs already seen in that monitoring dimension;
• normalized titles already seen when dedupeTitles=true;
• rows without a usable URL;
• BRAND_SUMMARY;
• RUN_SUMMARY.

The Pricing tab on the Actor page is always the authoritative source for current prices.

---

What is free

Free by design:

first baseline
repeated article URLs
normalized-title duplicates
BRAND_SUMMARY
RUN_SUMMARY

A quiet scheduled run can therefore produce useful summaries without a new-mention event.

The configured start event can still apply.

---

Cost control

Primary controls:

brands
languages
countries
timespanHours
maxRecordsPerQuery
maxResults
maxRuntimeMs

Focused monitoring

Use:

• fewer brands;
• one language;
• one source country;
• a narrower GDELT query;
• a shorter window.

Broader monitoring

Multiple languages and countries multiply the number of independent dimensions and GDELT requests.

The Actor enforces a hard 40-dimension limit.

---

Run health

Operational statistics are written to:

STATS

in the default Key-Value Store.

Depending on the run, STATS can include:

• HTTP requests;
• retries;
• rate-limit responses;
• dimensions completed;
• dimensions failed;
• baseline dimensions;
• billable records;
• free records;
• source availability;
• quality alerts;
• runtime;
• caps;
• cost metrics.

---

Honest limits

GDELT decides coverage

The Actor can only monitor articles that GDELT returns for the supplied query and filters.

No news index guarantees universal publisher coverage.

No article body

The Actor returns article metadata and the publisher URL, not the full publisher page.

Query quality matters

A common brand name can create unrelated mentions.

Use precise GDELT query syntax when necessary.

Exact normalized-title deduplication has tradeoffs

When enabled, two different publisher URLs with the same normalized title are treated as the same syndicated mention.

This can suppress a genuinely separate article that happens to use the identical headline.

URL deduplication uses the returned publisher URL

If the same underlying story is published under materially different URLs and does not share a normalized title, both can be treated as separate mentions.

The article read window is capped

maxRecordsPerQuery has a maximum of 250.

High-volume queries can therefore require shorter scheduling intervals or narrower filters.

GDELT APIs are rate limited

The Actor deliberately spaces requests and maintains a 40-dimension cap, but availability and quota behavior remain controlled by GDELT.

Brand × language × country state is independent

The same article can legitimately appear in multiple monitored dimensions and can be billable once in each independent dimension.

For example, monitoring an aggregate all-country dimension and a US-only dimension in separate Tasks creates different monitoring contracts.

No fuzzy syndication matching

The Actor does not use similarity models or embeddings to decide that two differently worded headlines are the same story.

No sentiment analysis

The Actor does not label coverage positive, negative, or neutral.

No AI in runtime

There is no LLM-generated summary, classification, or deduplication.

---

FAQ

Do I need a GDELT account?

No.

Do I need a GDELT API key?

No for the public DOC 2.0 endpoint used here.

Does it use a browser?

No.

Can I monitor multiple brands?

Yes.

The total brand × language × country dimension count must be 40 or less.

What happens on the first run?

The current returned article identities are learned as free baseline state.

No historical article is emitted as NEW_MENTION.

Why did I receive no billable mention?

Possible reasons:

• this was the first baseline;
• no unseen URL appeared;
• title deduplication suppressed a syndicated duplicate;
• the result/runtime/billing cap stopped further delivery.

Can I monitor Portuguese news?

Yes.

Use:

{
  "languages": [
    "portuguese"
  ]
}

Can I monitor Brazilian sources?

Yes.

Use:

{
  "countries": [
    "BR"
  ]
}

Can I monitor all languages?

Yes.

Use:

{
  "languages": []
}

Can I monitor all countries?

Yes.

Use:

{
  "countries": []
}

Can I use advanced GDELT query syntax?

The Actor passes the brand query to GDELT and adds its own language/country filters.

Use GDELT-supported query syntax carefully.

How is a mention ID created?

A deterministic SHA-256 hash of the article URL is truncated to 16 hexadecimal characters.

Does a repeated URL get charged again?

No while its identity remains in that dimension's persistent state.

Can syndicated copies be suppressed?

Yes.

Keep:

{
  "dedupeTitles": true
}

Is title deduplication fuzzy?

No.

It is deterministic normalized exact matching.

Are summaries charged?

No.

Can I schedule the Actor?

Yes.

What am I charged for?

The custom start event shown in Pricing plus genuinely new NEW_MENTION records delivered after baseline.

Can GDELT data be used commercially?

GDELT's published Terms of Use permit academic, commercial, and governmental use of its datasets without a dataset fee. Redistribution requires attribution to GDELT.

Is this affiliated with GDELT?

No.

This is an independent community Actor using the public GDELT DOC 2.0 API.

---

Support

For bugs, questions, or requested fields:

johnatan291303@gmail.com

You can also use the Issues tab on the Actor page.

---

Part of the JM Forge suite

Also from the same developer:

• ATS Hiring Signals Monitor — persistent hiring-signal monitoring.
• Steam Review Monitor & Player Feedback Alerts — genuinely new Steam review monitoring.
• NHTSA Recall, Complaint & Safety Spike Monitor — stateful US vehicle-safety intelligence.

JM Forge Actors remain independent tools.

Use this Actor for stateful global news mentions and media-monitoring workflows.