News Monitor: Only New Articles From Saved Watches

What does News Mentions Watch do?

News Mentions Watch is a news monitor with saved watches. You list the companies, people, keywords, topics and news sites to follow, run it on a schedule, and each run returns only the news articles it has not delivered to you before. A watch can be:

• keyword: words or phrases, matched as whole words in the article title.
• organization: a company, agency or other body, matched in the organizations found in the article.
• person: a name, matched in the people found in the article.
• theme: a GDELT theme code, such as ECON_BANKRUPTCY for bankruptcies.
• source: a news site, such as bbc.co.uk, to follow everything it publishes.

The articles come from the GDELT Project, which reads news sites around the world and publishes a file of what it saw every 15 minutes. One English file holds about 1,600 to 2,100 articles from about 300 to 440 news sites. Each row is one article: its link, title, news site, when GDELT saw it, the language, the watches it matched, the organizations, people, themes and countries GDELT found in it, its tone, its sharing image, and the GDELT record ID. The first run of a watch delivers its newest articles as a baseline, and later runs only what is new. Each watch also gets one free summary row per run with what it matched, the files read, a spike flag when the news on it is unusually busy, and on its first run a coverage report of the news sites that carried it.

Data from the GDELT Project (https://www.gdeltproject.org/). Every row carries that citation. GDELT holds no article text, so neither does this Actor. The Actor is not affiliated with or endorsed by the GDELT Project.

Why use News Mentions Watch?

Following the news on a company, a person or a topic means running the same searches again and working out which results you have already read. A search returns everything it finds each time. This Actor keeps your watches in one input, remembers what it delivered, and on a schedule sends only the articles that are new to you.

What you get:

• Five kinds of watch in one input. Up to 50 watches a run, mixing keywords, organizations, people, GDELT themes and news sites, each with an optional label and words to leave out (excludeTerms).
• Only what is new. Each watch remembers the newest GDELT file it has read and the articles it delivered. A later run reads only the files published since, and an article reaches you once, even when GDELT lists it again.
• One row and one charge per article. An article that three of your watches match is one row that lists all three. The same link seen twice, or the same title from the same site on the same day, counts once.
• See the news sites before you pay for many articles. A watch's first run reports, in its free summary row, how many news sites carried what it matched, every one of them, and the 10 with the most articles.
• A spike flag. Each watch keeps its last 14 runs, and its summary row says when a run matched at least 3 times its usual number.
• News in other languages when you want it. GDELT's translingual files cover news in other languages, with the language code on each row.
• No key needed. The GDELT files are public.

Each claim above has a test behind it:

What you get	How it works	The test that backs it
Five kinds of watch	Keywords match whole words in the title, organizations and persons match whole words inside the names GDELT found, themes match exactly, sources match the site and its subdomains. excludeTerms drop a match whose title holds one of them.	"keyword: whole words in the title, any of the phrases", "organization: inside GDELT's organizations list, and the title only with matchTitle", "person: inside GDELT's persons list, whole names", "theme: exact codes only", "source: the domain and its subdomains", "excludeTerms drop a match whose title holds one of them, for every watch type". The three prefill watches were checked by hand against the raw GDELT lines of 8 files on 14 Oct 2026: the same counts (177, 121 and 33 articles) and the same 10 newest each.
Only what is new	A watch's floor is the newest file it has read. A later run reads the files after it, never more than 72 hours back, and skips every article the memory holds.	"the next run reads only the newer file, delivers only its articles and charges only those", "a later run reads only the stamps after the floor", "the floor only moves forward", "adding a watch to a named memory delivers that watch's baseline only", and the live test "live: a first run and a second run against data.gdeltproject.org, at most 8 files".
One row and one charge per article	Links are compared without www, fragment, tracking parameters or a trailing slash. A second key joins the news site, the day and the folded title.	"one article matched by two watches is one row listing both, so it is charged once", "the same URL in two files, or the same title from one source on one day, is one article", "URLs are compared without www, fragment, tracking parameters or a trailing slash".
Late and missing files	GDELT's server publishes a file some minutes after the time in its name. A file under 3 hours old that is not there yet, or that comes damaged, stops the reading, and the next run starts there. An older one is skipped and counted.	"lag rule: a 404 on a file under 3 hours old means not published yet, so reading stops", "gap rule: a 404 on a file 3 hours old or more is a gap, skipped and counted", "gap and damage on old files: a missing file and a corrupt one are skipped and counted, the rest is read", "lag rule on a damaged recent file: reading stops there, and the next run reads it".
A coverage report on the first run	Counted over every match of the look-back, not only the articles delivered.	"coverage report: distinct sources that matched, all of them A to Z, and the top 10 by count", "first run of the prefill: the newest 10 a watch, one charge per row, free summaries with the coverage report".
A spike flag	The watch's matches per file over its last 14 runs, times the files of this run, against what it matched now.	"spike: at least 10 matches and at least 3 times the average for the same number of files", "spike: a watch whose history is quiet flags a busy run in its summary row", "the history keeps the last 14 runs".
News in other languages	The translingual files, read when includeTranslingual is on. The language comes from GDELT's translation column.	"translingual files: rows in other languages, with the T record ids, and reading waits for the later translingual file", "language: eng in the English files, the srclc code in translingual ones".
Filters for every watch	News sites to keep or leave out, countries mentioned, and a tone range, applied before any watch.	"filters: include and exclude sources, tone range, countries by code or name", "shared filters cut every watch: sources, tone and countries".
A memory with a known size	Each watch remembers the newest 20,000 articles it delivered or held back.	"the memory keeps the newest 20,000 keys of a watch, delivered before held on a tie", "store names: the same watches in any order give one name; a task has its own".
Gentle on GDELT's server	At most 2 downloads at a time, a User-Agent that names the Actor, retries with growing waits after a server error.	"at most 2 downloads at a time", "a 5xx is retried three times with growing waits, then fails as a server error", "a 429 waits for Retry-After, or 60 seconds; three in a row stop the client".
Charged only for what you get	One charge per row with status ok. Every other row is free, and the run stops before it would charge past your maximum cost per run. A run that restarts reads its own rows first.	"C1 the maximum cost per run stops delivery cleanly, and the next run delivers the rest, charging nothing twice", "B2 a crash after a row is written but before the memory is saved delivers and charges nothing twice", "P3 a memory write still on its way when the run ends leaves no article out, and the next run delivers and charges nothing".

Plus what the Apify platform adds around it:

• API access. Start runs and read results with the Apify API or the JavaScript and Python clients.
• Scheduling. Run the watches every hour, or every morning at 7:00, and get only what appeared since the last run.
• Integrations. Send rows to Make, Zapier, Google Sheets, Slack or any webhook.
• Monitoring. Run history, logs and alerts for failed runs.

Typical uses are a feed of news on your brand or company for a PR or communications team, a daily list of news on the companies in a portfolio, an alert on a chief executive or a regulator, a risk feed on bankruptcies, recalls or data breaches, and a news feed for an AI agent that should read only what is new.

What data can News Mentions Watch extract?

Each article becomes one row in the dataset. Each watch also gets one free summary row per run. The most useful fields:

Field	Type	What it holds
status	string	ok (an article, charged), summary (the free row of one watch), invalid or skipped.
url, title, sourceDomain	string	The article's link, its page title as GDELT recorded it (HTML entities decoded), and the news site as GDELT names it, a domain without www.
seenAt, publishedAt	string	The 15-minute stamp of the GDELT file that held the article, which is when GDELT saw it, and the publication time GDELT read from the page when it found one (about half of the articles). ISO 8601, UTC.
language	string	eng for English files; for translingual files the ISO 639-2 code of the original language, such as spa, deu or zho.
changeType	string	baseline on a watch's first run, new after that.
matchedWatches, matchedWatchIds, matchedTerms	array	The labels and IDs of every watch of the run that matched the article, and the phrases, names, codes or domains that matched.
organizations, persons	array	The organizations and people GDELT found in the article, as GDELT spells them, at most 25 each.
themes	array	The GDELT theme codes mentioned most in the article, at most 10.
locationCountries, locationCountryNames	array	The countries of the places GDELT found, as FIPS 10-4 codes the way GDELT writes them (UK, GM for Germany) and as names. GDELT gives a few codes no name (RB, YI, OC for oceans), and then the name is the code.
tone, positiveScore, negativeScore, polarity, wordCount	number	GDELT's tone of the article, from -100 to +100 (most news sits between -10 and +10), its shares of positive and negative words, how charged the text is, and the number of words GDELT read.
imageUrl	string	The sharing image the page names, when it has one.
gdeltRecordId, gdeltFile	string	The record ID in the GDELT file (translingual records carry a T) and the file's name.
attribution	string	The citation GDELT asks for, on every row.
watchId, watchType, watchLabel, watchValue	string	Summary and notice rows: the watch, its type, your label and its terms. The same watch keeps the same ID from run to run.
articlesMatched, articlesDelivered, alreadyDelivered, heldBack	integer	Summary rows: what the watch matched in this run's files, what it delivered, what the memory had delivered before, and what maxPerWatch held back.
filesRead, filesMissing, filesFailed	integer	Summary rows: the GDELT files read for the watch, and the files 3 hours old or more that were missing or damaged and were skipped.
averageBefore, spike	number, boolean	Summary rows: the matches expected from the watch's last 14 runs for this run's files, and whether this run matched at least 10 and at least 3 times that.
sourcesMatched, sourceDomains, topSources	integer, array, array	Summary rows, first run only (the coverage report): how many news sites carried the matches, all of them A to Z (at most 1,000), and the 10 with the most articles.
stateStore, checkedAt	string	The memory's store name, and when the row was written.
message, errorCode	string	Summary and notice rows: what happened in plain words, and a short code when there is something to report.

The Articles view shows the watches, title, news site, time seen, language, tone and link. The Names and themes view shows the organizations, people, themes and countries of each article. The Watch summaries view shows each watch's counts, spike flag and coverage report.

A row that has something to report carries one of these codes in errorCode, so you can count rows by reason without reading the sentence. The sentence in message can be reworded in a later version. The code stays.

errorCode	Meaning
invalid-watch	A watch that could not be read, such as an unknown type or a keyword watch without a phrase. The row says what to change.
duplicate-watch	The same watch is already in your list, so it was checked once.
max-per-watch	A later run found more new articles than maxPerWatch. The newest were delivered and the older ones left out for good.
charge-limit	The run reached your maximum cost per run. The next run delivers what was left.
run-time-limit	The run reached its time limit. The next run starts where it stopped.
aborted	The run was stopped.
corrupt-file	A GDELT file came damaged and failed its check. Under 3 hours old it stops the reading and the next run tries it again; older, it is skipped and counted in filesFailed.
server-error, http-error	GDELT's server answered with an error status, after retries. The same rule as for a damaged file.
repeated-server-errors	Three files in a row failed with server errors, so the run stopped reading.
rate-limited	GDELT's server answered "too many requests" (HTTP 429) three times in a row.
network-error, timeout	The server could not be reached, or a file did not arrive within 180 seconds. Reading stops there whatever the file's age, so a run without a network never skips a file.
too-large, unexpected-redirect	A file over 64 MB, or a redirect to another site.

How to watch the news by keyword, organization, person, theme or source

1. Open the Actor in Apify Console and select the Input tab.
2. The form is prefilled with an organization watch (Federal Reserve) and two keyword watches (inflation, and OpenAI or Nvidia), 2 hours back at 10 articles each, so you can press Start to see a result straight away. On Apify on 15 Oct 2026 this input read 8 files and delivered 27 articles in 11 seconds at the default 512 MB.
3. Edit Watches (watches). Each watch is one object with a type:
   • { "type": "keyword", "phrases": ["battery recall", "product recall"] }, with "match": "all" to need every phrase.
   • { "type": "organization", "names": ["Federal Reserve"] }, with "matchTitle": true to also match the name in the title.
   • { "type": "person", "names": ["Christine Lagarde"] }
   • { "type": "theme", "themes": ["ECON_BANKRUPTCY"] }
   • { "type": "source", "domains": ["bbc.co.uk"] }
   • Any watch can take a label and excludeTerms, words or phrases that drop an article when its title holds them.
4. Set First run looks back (hours) (lookbackHours) and Most articles per watch per run (maxPerWatch). A watch's first run reads that many hours of files and delivers its newest articles up to that number. Later runs read only the files published since.
5. Optional: set the Filters for every watch: other languages (includeTranslingual), news sites to keep (includeSources) or leave out (excludeSources), countries mentioned (countries) and a tone range (minTone, maxTone).
6. Save the input as a task, or set Watch memory name (stateStoreName), such as my-news-watch. Either way a watch you add later brings only its own baseline.
7. Press Start. Open the Output tab for the table, and export it as JSON, CSV or Excel. Then create a schedule with the same input, for example every hour, or every weekday at 7:00.

To run it from code, send the same input to the Actor through the API:

{
    "watches": [
        { "type": "keyword", "phrases": ["battery recall", "product recall"], "label": "Recalls" },
        { "type": "organization", "names": ["European Central Bank"], "matchTitle": true, "label": "ECB" },
        { "type": "person", "names": ["Christine Lagarde"], "label": "Lagarde" },
        { "type": "theme", "themes": ["ECON_BANKRUPTCY"], "label": "Bankruptcies" },
        { "type": "source", "domains": ["bbc.co.uk"], "excludeTerms": ["football"], "label": "BBC" }
    ],
    "lookbackHours": 24,
    "maxPerWatch": 50,
    "stateStoreName": "my-news-watch"
}

How to send new articles to Slack or Google Sheets (Make, Zapier, no code)

After the first run, a scheduled watch holds only the articles that are new since the last run, so you can pass every run's results straight on.

Slack, built in. On the Actor's Integrations tab, add Slack, connect your workspace, pick a channel and choose the event "Run succeeded". Each finished run posts a message with a link to its results.

Google Sheets with Make.com.

1. In Make, create a scenario and add the Apify module that watches for finished Actor runs, set to this Actor.
2. Add the Apify module that gets dataset items, and map the run's default dataset ID.
3. Add Google Sheets "Add a Row" and map the fields you want, for example matchedWatches, title, sourceDomain, seenAt, tone and url.
4. Add a filter so only rows with status ok reach the sheet, or only rows of one watch, or only summary rows where spike is true for an alert.

Google Sheets or Slack with Zapier. Use the Apify trigger for a finished Actor run, then the Apify step that fetches dataset items, then a Google Sheets "Create Spreadsheet Row" or a Slack "Send Channel Message" action. A Zapier filter step works the same way as the Make filter.

Your own code. Add a webhook on the Integrations tab for the event "Run succeeded", and read the dataset from the URL in the payload.

Set the schedule first (see the steps above), so that each run, and each message or row, covers what is new since the run before.

How much does it cost to watch the news?

You pay per article delivered, and the Apify platform usage for the run is included. An article costs $0.0030 on the Free and Bronze plans, so 1,000 articles cost $3.

Event	When it is charged	Price
article	One article row delivered with status ok: each article of a watch's first-run baseline, and each new article after that, once however many watches matched it	$0.0030 (Free, Bronze), $0.0026 (Silver), $0.0021 (Gold)
Actor start	Once per run, scaled by memory (Apify standard event)	$0.00005 per GB of memory

Summary rows and rows with the status invalid or skipped cost nothing. You can cap a run with the Maximum cost per run setting, and the Actor stops cleanly at that limit.

How much does one article cost?

One article costs $0.0030 on the Free and Bronze plans, $0.0026 on Silver and $0.0021 on Gold. A run adds a start fee of about $0.000025 at the default memory of 512 MB. As a guide: 10 watches at the default of 50 articles each start with a baseline of up to 500 articles, $1.50 at most (a measured first run of 10 such watches over 24 hours delivered 207, $0.62). With about 30 new articles a day after that, a month of hourly runs costs about $2.70 for the articles and about $0.02 in start fees.

How do I keep a run within budget?

Set Maximum cost per run when you start it or in the schedule. The run stops before it would charge past that amount, and the watches it did not finish get free rows with the code charge-limit. Those articles stay out of the memory, so the next run delivers them. A lower maxPerWatch and a shorter lookbackHours keep the first-run baseline small.

What does a run cost when nothing is new?

Only the start fee, about $0.000025 at 512 MB. Each watch writes its free summary row, and nothing is charged.

How often should I run it?

As often as you want the news. You pay per article, not per file read, so an hourly schedule costs the same per article as a daily one, plus the start fee of each run. GDELT publishes a file every 15 minutes, so a run more often than every 15 minutes finds nothing new.

Input

Open the Input tab to see every setting with a short description. Only watches is required. The form has three parts:

• The watches: watches, lookbackHours and maxPerWatch.
• Filters for every watch: includeTranslingual, includeSources, excludeSources, countries, minTone and maxTone.
• Watch memory: stateStoreName.

watches takes up to 50 watches. The fields of a watch:

Field	For	What it holds
type	every watch	keyword, organization, person, theme or source.
label	every watch	Optional. A name copied into each of the watch's rows.
phrases, match	keyword	Up to 25 words or phrases, matched as whole words in the title, any case, and any (the default) or all of them.
names, matchTitle	organization, person	Up to 25 names, matched as whole words inside the names GDELT found. For an organization watch, matchTitle also matches the names in the title.
themes	theme	Up to 25 GDELT theme codes, matched exactly.
domains	source	Up to 25 news sites, such as bbc.co.uk. Subdomains match too.
excludeTerms	every watch	Optional. Words or phrases that drop an article from this watch when its title holds one of them.

lookbackHours is 24 by default, from 1 to 72. A watch's first run reads that many hours of files (24 hours is 96 files). Later runs read only the files published since the watch's last run, never more than 72 hours back.

maxPerWatch is 50 by default and at most 1,000. A watch's first run delivers its newest articles up to this number. When a later run finds more new articles than maxPerWatch, the newest are delivered, the older ones are left out for good, and the watch's summary row says how many.

includeTranslingual is off by default. On, the run also reads GDELT's translingual files: news in other languages, machine-translated by GDELT. Names and themes come from the translation, titles stay in the original language, so a keyword watch matches those titles as written. The translingual files are larger, and GDELT publishes them about 15 minutes after the English ones.

includeSources and excludeSources keep or leave out news sites, subdomains included. countries keeps only articles that mention a place in one of the countries, given as FIPS 10-4 codes the way GDELT writes them (US, UK, GM for Germany, CH for China, JA for Japan) or as country names. minTone and maxTone keep only articles inside a tone range, such as maxTone -2 for clearly negative news.

stateStoreName names the key-value store that remembers what each watch delivered. With a name, an added watch delivers only its own baseline, and a removed watch is no longer read. Left empty, a run of a saved task keeps one memory for that task, which works the same way. A run outside a task and without a name keeps a memory named after its watches, so adding or changing a watch there starts a new memory, and the next run delivers (and charges) every watch's baseline again.

Output

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel. A run also writes a SUMMARY record to its key-value store with the counts of watches checked, articles delivered as a baseline and as new, matches delivered before or held back by maxPerWatch, invalid and duplicate watches and spikes, the charged rows, the reason the run stopped early if it did, the memory's name and size, the GDELT files asked for, read, missing and failed with the outcome of each, where reading stopped and why, the requests, retries and bytes, and one record per watch. A run that could read no GDELT file at all, or whose watches are all invalid, ends with the status Failed and the reason in its message, so a schedule shows it.

An article that two prefill watches matched, the first-run summary of an organization watch, and a later run's summary with nothing new look like this:

[
    {
        "status": "ok",
        "errorCode": null,
        "message": null,
        "url": "https://www.nhpr.org/2026-10-14/inflation-sizzled-in-september-and-social-security-benefits-will-get-a-boost",
        "title": "Inflation sizzled in September — and Social Security benefits will get a boost",
        "sourceDomain": "nhpr.org",
        "seenAt": "2026-10-14T19:30:00Z",
        "publishedAt": null,
        "language": "eng",
        "changeType": "baseline",
        "matchedWatches": ["Federal Reserve", "Inflation"],
        "matchedWatchIds": ["51adb6523eea98756f40", "1e441add73b7df7c079f"],
        "matchedTerms": ["Federal Reserve", "inflation"],
        "organizations": ["Boston College", "Federal Reserve", "Cleveland Federal Reserve Bank", "National Committee To Preserve Social Security", "Labor Department On", "Security Administration"],
        "persons": ["Beth Hammack"],
        "themes": ["TAX_ECON_PRICE", "ECON_INFLATION", "WB_1104_MACROECONOMIC_VULNERABILITY_AND_DEBT", "WB_442_INFLATION", "CRISISLEX_C07_SAFETY", "EPU_CATS_ENTITLEMENT_PROGRAMS", "ARMEDCONFLICT", "EPU_CATS_NATIONAL_SECURITY", "WB_137_WATER", "LEADER"],
        "locationCountries": ["US", "IR", "RS", "JO", "UP"],
        "locationCountryNames": ["United States", "Iran", "Russia", "Jordan", "Ukraine"],
        "tone": -1.1532,
        "positiveScore": 1.318,
        "negativeScore": 2.4712,
        "polarity": 3.7891,
        "wordCount": 557,
        "imageUrl": "http://npr-brightspot.s3.amazonaws.com/56/61/c0ae826a434f85125c7d6ab98c31/gettyimages-2298003777.jpg",
        "gdeltRecordId": "20261014193000-784",
        "gdeltFile": "20261014193000.gkg.csv.zip",
        "attribution": "Data from the GDELT Project (https://www.gdeltproject.org/), Global Knowledge Graph 2.1. Not affiliated with or endorsed by the GDELT Project.",
        "stateStore": "my-news-watch",
        "checkedAt": "2026-10-14T19:41:14.122Z"
    },
    {
        "status": "summary",
        "errorCode": null,
        "message": "First run: 8 files read (2026-10-14 17:45 UTC to 19:30 UTC). 124 articles matched from 109 sources, 10 delivered. Top sources: adn.com (2), advocate-news.com (2), batonrougepost.com (2). The topSources field holds the top 10 and sourceDomains every source that matched. 114 older articles were held back by maxPerWatch (10) and will not be delivered later. Free row.",
        "changeType": "baseline",
        "watchId": "cad7c57c11eb643fa4e4",
        "watchType": "organization",
        "watchLabel": "EU",
        "watchValue": "European Union",
        "articlesMatched": 124,
        "articlesDelivered": 10,
        "alreadyDelivered": 0,
        "heldBack": 114,
        "filesRead": 8,
        "filesMissing": 0,
        "filesFailed": 0,
        "averageBefore": null,
        "spike": false,
        "sourcesMatched": 109,
        "sourceDomains": ["4029tv.com", "abcnews.com", "adn.com"],
        "topSources": [{ "domain": "adn.com", "articles": 2 }, { "domain": "advocate-news.com", "articles": 2 }, { "domain": "batonrougepost.com", "articles": 2 }]
    },
    {
        "status": "summary",
        "message": "Run: 0 files read. 0 articles matched, 0 delivered. Free row.",
        "changeType": "new",
        "watchType": "organization",
        "watchLabel": "Federal Reserve",
        "articlesMatched": 0,
        "articlesDelivered": 0,
        "filesRead": 0,
        "spike": false
    }
]

The rows come from local runs on 14 Oct 2026 against the real GDELT files, with the store name of the example input. The article row lists one of its four persons here, and the summary rows are shortened. Every row carries every field, with null where a value does not apply, so exports keep the same columns.

Tips for faster runs and lower costs

• Save the input as a task, or set stateStoreName, before you add or remove watches. Outside a task and without a name, any change to the list starts a new memory, and the next run delivers and charges every watch's baseline again.
• Keep the first-run baseline small with maxPerWatch and lookbackHours. A baseline of 10 newest articles per watch tells you whether a watch is tuned right, and the coverage report in its summary row shows which news sites carry it, for a fifth of the cost of 50.
• Prefer a keyword watch when you want articles about a name. An organization watch finds every article that mentions the organization anywhere: on 14 Oct 2026 GDELT listed Nvidia in about 10 articles per 15-minute file, and only about a third of them had Nvidia in the title. That is why the prefill watches OpenAI and Nvidia with a keyword watch.
• Use excludeTerms for the meanings you do not want, such as football on a watch for a city's name.
• Leave includeTranslingual off unless you need news in other languages. With it, a 24-hour first run read 192 files and 2.6 times the data, and took about 2.5 times as long.
• A first run of 10 watches with lookbackHours 24 reads 96 files, about 670 MB, and takes about 2 to 3 minutes at the default 512 MB (a 3-watch first run read its 96 files in 139 seconds on Apify on 15 Oct 2026). An hourly run of the same watches reads 4 files in about 12 seconds. More memory brings more CPU on Apify: at 1,024 MB a long first run takes about half as long.
• The default 512 MB fits up to 50 broad watches with maxPerWatch 1,000 (peak 317 MB measured). 256 MB is enough for 10 ordinary watches (peak 178 MB), not for broad ones.
• A run timeout of 30 minutes leaves room for a 72-hour first run of 10 watches. A run that reaches its limit stops cleanly with free rows, and the next run starts where it stopped.

FAQ, disclaimers and support

Where does the data come from, and may I use it?

From the GDELT Project's Global Knowledge Graph 2.1 files, which GDELT publishes every 15 minutes at data.gdeltproject.org. GDELT's terms (https://www.gdeltproject.org/about.html) allow any use, commercial use included, with a citation and a link back to the project. Every row carries that citation in attribution, and keep it when you pass the rows on. The articles belong to their publishers. A row holds GDELT's record of an article (link, title, names, themes, places, tone), never its text. How you may use what you collect depends on your purpose and your country, so check that for your use case. This is general information, not legal advice.

Is this an official GDELT tool?

No. The Actor is an independent tool, not affiliated with, made, endorsed or checked by the GDELT Project. The data comes as GDELT publishes it. GDELT finds the names, themes, places and tone by machine, and they can be wrong. Open the article (the url column) before you act on a row.

What counts as new, and where can it be wrong?

Each watch keeps a floor: the newest GDELT file it has read. A later run reads only the files after the floor, never more than 72 hours back, and delivers an article only when no watch of the memory has delivered it before. An article is the same when its link is the same (without www, fragment, tracking parameters and a trailing slash), or when the same news site shows the same title on the same day (titles of 3 words or 20 characters and more). Inside a run, the first file that holds an article wins. After a first run cut at maxPerWatch, the floor still moves to the newest file read, so the articles held back are never delivered later. Where the result can be wrong:

• The same story at many sites. An agency story that 8 papers print is 8 articles, one per site, because the title key works per site. On 14 Oct 2026, 75 titles in one file appeared at more than one site.
• A title edited after publishing. A site that changes a title and the link makes the article new again.
• The cut at maxPerWatch. When a later run finds more than maxPerWatch new articles, the older ones are left out for good, and the summary row says how many.
• A schedule paused for more than 72 hours. The next run reads the last 72 hours, and the summary row says how many older files it did not read.
• One article, several watches. One row lists every watch of the run that matched it. A watch whose first run comes later does not deliver an article the memory delivered before, and counts it in alreadyDelivered.

How does a watch decide what matches, and where can it be wrong?

Titles are decoded from HTML entities, normalised and compared in lower case. A keyword phrase must appear as whole words, and a space in a phrase also matches a dash. Scripts written without spaces, such as Chinese, Japanese and Thai, count as word edges, so a Latin name inside a Chinese title is found. An organization or person name must appear as whole words inside one of the names GDELT found in the article. Theme codes match exactly. A source watch matches the site and its subdomains. excludeTerms are tested against the title. Where the result can be wrong:

• Keywords see only the title. GDELT publishes no article text, so an article that names your word only in its body is not found by a keyword watch. An organization or person watch looks at the whole article's names.
• Names found by machine. GDELT's lists of organizations and persons come from software, and a big name appears in many articles that are not about it. On 14 Oct 2026 the lists also held a city and a product as persons.
• Themes found by machine. GDELT assigns its theme codes by software, so a theme watch has the same limits.
• Sites GDELT does not read. A source watch finds nothing for a site GDELT does not crawl. The coverage report of a first run shows which sites GDELT carried for your watch.
• Other languages. In translingual files the names and themes come from GDELT's machine translation, while the title stays in the original language. A keyword watch in English does not match a Spanish title.
• Broken characters. A title with broken characters, such as "£2m" for "£2m", comes that way from the site.
• Country codes. GDELT uses FIPS 10-4 codes: GM is Germany, UK the United Kingdom. A country name in countries is turned into its code.

How fresh is the news, and what happens when a GDELT file is late or missing?

GDELT names a file every 15 minutes. On 14 Oct 2026 its server published each English file 10 to 60 minutes after the time in its name, and the translingual files about 15 minutes after the English ones. So an article reaches you some 25 to 75 minutes after GDELT saw it, plus the time to your next run. A file under 3 hours old that the server does not have yet, that comes damaged or that keeps failing, stops the reading at that file, and the next run starts there. A file 3 hours old or more that is still missing or damaged is skipped for good and counted in the summary row (filesMissing, filesFailed). Where the result can be wrong:

• A file later than 3 hours. It is skipped, and its articles are missed.
• A short first look-back. With lookbackHours 1, a first run may find only 1 or 2 published files.
• The time on a row. seenAt is when GDELT saw the article, not when it was published. publishedAt is the publication time when GDELT found one on the page, about half the time.

What is a spike, and where can it be wrong?

Each watch keeps its last 14 runs. Its summary row gives averageBefore, the matches per file of those runs times the files of this run, and sets spike to true when this run matched at least 10 articles and at least 3 times averageBefore. Where the result can be wrong:

• The first runs. A first run has no history, so it never flags a spike, and the first few runs after it have a short one.
• Quiet watches. A watch that matches fewer than 10 articles in a run never flags one.
• GDELT's own volume. A file with fewer articles than usual, for example after a pause on GDELT's side, lowers the counts of every watch.

Is personal data involved?

News names people, and GDELT publishes the names it finds as part of its public record. The Actor outputs those names in persons as GDELT gives them and nothing more: no profiles, no contact details, no article text. Under the GDPR and similar laws you are the controller of what you collect, so keep and use it for a lawful reason.

If a row is about you and you want it out of this Actor's output, open an issue on the Issues tab with the article link or your name as it appears. A link removed this way is never delivered again. A name removed this way is left out of the persons field of every later row, and a person watch no longer matches it. GDELT's files and the article itself stay as they are; only GDELT and the publisher can change those.

How does the Actor remember what it delivered, and how do I start over?

After each run it keeps, per watch, its floor, its last 14 runs for the spike flag, and the keys of the articles it delivered or held back (the newest 20,000), in a named key-value store listed in each row as stateStore. The keys are short hashes of links and titles; no article and no name is stored there. To start over, delete that store under Storage in Console, or set a new stateStoreName. A watch whose reading stopped early keeps its floor, so the next run catches up.

What happens when GDELT's server fails or limits the requests?

The Actor downloads at most 2 files at a time, with a User-Agent that names it. A server error is retried three times with growing waits. A "too many requests" answer (HTTP 429) is waited out for as long as its Retry-After header says, or 60 seconds, and three in a row stop the reading. Three files in a row with server errors stop the reading too. A network error or a file that does not arrive within 180 seconds stops the reading at that file whatever its age, so a run without a network never skips a file. Each stop is one free skipped row with its code, and the next run starts at that file.

What happens when a run reaches its time limit?

The Actor reads the time limit of the run from the platform and starts no new file and no new row in the last 30 seconds. What it did not finish gets free rows with the code run-time-limit, and the next run starts where this one stopped.

What if something looks wrong?

Open the Issues tab on the Actor page and describe your input and what you expected. A run link helps. Issues are answered within two days.

Other Actors by the same developer

• Public Tenders Feed: new public tenders from EU TED, UK Find a Tender, SAM.gov and CanadaBuys, filtered by codes, keywords, country and value, with only notices not delivered before.
• New Scholarly Papers Watch: new journal articles, preprints and other works for the keywords, ORCID iDs, journals and funders you watch, with retraction and correction notices for your DOIs.
• SEC EDGAR Filing Monitor: new SEC filings for the tickers or CIKs you watch.
• SEC Form D Feed: new private fundraising rounds filed with the SEC on Form D, with amounts and industry.
• SEC XBRL Fundamentals: revenue, EPS, cash flow and other reported figures per company and period, from SEC XBRL filings.
• UK Company Check: Companies House status, outstanding charges and risk flags for UK companies, or a list of newly registered ones.
• US Trademark Status and Watch: USPTO status and upcoming deadlines for US trademarks, and what changed since your last run for marks you watch.
• Full Page Website Screenshot: full-page PNG or JPEG screenshots, including pages that load content as you scroll.