How to Scrape GDELT News Articles & Trends in 2026

If you’ve ever tried to monitor how a story is covered worldwide, you know the pain: every news site has its own layout, its own paywall, and its own anti-bot posture, and stitching a dozen of them into one feed is a full-time job. GDELT already did that work — it indexes the world’s broadcast, print and web news in over 100 languages, updated every 15 minutes, and exposes it through a free public API. The catch is that its Document API returns a bounded slice per request and uses a specific query syntax, so pulling a large, time-spanning corpus means paging through date windows correctly. This guide covers how GDELT’s Document 2.0 API works, what its query language can do, and how to pull thousands of articles, volume timelines or image-rich stories in a single run.

What’s worth extracting

Every article record from the actor carries 10 fields, straight from GDELT’s index:

• title — the article headline as GDELT indexed it.
• url — the full article URL (the publisher’s link).
• domain — the source domain, e.g. bbc.co.uk, nytimes.com.
• seendate — when GDELT first indexed the article, in 20260708T124500Z format.
• language — the detected language name, e.g. English, Spanish.
• sourcecountry — the country of the publishing outlet, e.g. United States, Germany.
• socialimage — the article’s OpenGraph / social preview image URL.
• tone — GDELT’s tone score for the article (positive values = positive framing, negative = negative).
• query — the search query that produced the row.
• mode — which mode produced it: articles, timeline or images.

In timeline mode, records instead carry series (e.g. Volume Intensity) and a numeric value, bucketed by seendate — that’s your trend line rather than a list of links.

How the source actually works

The actor calls the GDELT Document 2.0 API at api.gdeltproject.org/api/v2/doc/doc. GDELT (the Global Database of Events, Language, and Tone) is a public, open-data project — no key, no account, no cost on GDELT’s side. There are three modes:

• articles — the full news list with URL, domain, language, country, tone and social image.
• timeline — hourly/daily volume intensity via the timelinevol endpoint, for trend and breaking-news detection.
• images — the subset of articles guaranteed to have a social preview image, for dashboards and social cards.

The power of GDELT is its query syntax, which the actor passes through directly. You get AND / OR / NOT operators, exact-phrase matching with quotes, and field filters like sourcelang:english, sourcecountry:AU, theme:, domain: and more. A precise multi-filter query:

{
  "query": "\"climate change\" AND (floods OR wildfire) sourcelang:english sourcecountry:AU",
  "mode": "articles",
  "maxResults": 1000,
  "timespan": "3m",
  "sortBy": "datedesc"
}

You can also use the separate language and country input fields instead of inline filters — the actor folds them into the query for you. sortBy accepts datedesc, dateasc, rel, hybridrel and socialsharecount. A simple keyword run over the last three months looks like the actor’s own default input:

{
  "query": "artificial intelligence",
  "mode": "articles",
  "maxResults": 1000,
  "timespan": "3m",
  "sortBy": "datedesc"
}

▶ Open the GDELT News Scraper on Apify — one run yields thousands of articles across 100+ languages and nearly every country, with domain, language, tone and image on every row. No API key, no login. Export to JSON, CSV or Excel.

The access reality: pagination via date windows

Here’s the part that trips people up. GDELT’s Document API returns up to 250 articles per request — that’s the hard ceiling on a single call. To reach a larger maxResults (up to 10,000), the actor uses sliding date-window pagination: it fetches up to 250 articles from a time window, then slides the window back in time and fetches again, repeating until it hits your maxResults target or exhausts the requested timespan. That’s how one run yields thousands of unique articles across weeks or months of coverage.

Two consequences follow directly:

• Longer timespans give you more windows. For a large pull (say 2,000 articles), use a timespan of at least 3m so there are enough date windows to fill the quota. A big maxResults over a 1-day window simply can’t be satisfied.
• The actor enforces a 6-second inter-request delay to respect GDELT’s rate limit. So a run’s time scales with the number of windows, not just the article count. A 500-article pull is typically 2–3 requests and finishes in under 2 minutes; a 10,000-article pull over several months is many windows and takes proportionally longer.

timespan accepts 1d, 1w, 1m, 3m, 6m, 1y. Note that maxResults is ignored in timeline mode — that mode returns the volume series for the whole window.

Example output

Two articles-mode rows for the same query, across different source countries:

[
  {
    "title": "EU Passes Landmark Artificial Intelligence Safety Act",
    "url": "https://www.politico.eu/article/eu-ai-safety-act-2026/",
    "domain": "politico.eu",
    "seendate": "20260708T080000Z",
    "language": "English",
    "sourcecountry": "Belgium",
    "socialimage": "https://www.politico.eu/uploads/2026/07/ai-act.jpg",
    "tone": "-2.14",
    "query": "artificial intelligence",
    "mode": "articles"
  },
  {
    "title": "China Deploys AI Models for National Infrastructure Monitoring",
    "url": "https://www.globaltimes.cn/page/202607/1300001.shtml",
    "domain": "globaltimes.cn",
    "seendate": "20260708T070000Z",
    "language": "English",
    "sourcecountry": "China",
    "socialimage": "",
    "tone": "1.85",
    "query": "artificial intelligence",
    "mode": "articles"
  }
]

The tone scale runs roughly from negative ten to positive ten; the first row’s negative tone signals critical framing, the second’s positive tone signals favorable coverage. An empty socialimage is normal — not every article ships a preview image (which is exactly what images mode filters out).

Typical use cases

• Global coverage tracking — monitor a company name, executive or product across 50+ countries and dozens of languages in one query.
• Topic feeds — build a continuously refreshed news feed for any subject: AI regulation, climate events, elections.
• Breaking-news detection — use timeline mode to watch volume intensity spike when a story breaks or peaks.
• Social monitoring dashboards — collect image-rich articles via images mode for visual cards.
• Cross-lingual media research — study how a scientific term (mRNA, quantum computing) is covered in non-English media by filtering sourcelang:.
• NLP corpora — build news datasets for topic modeling, framing analysis or sentiment training, with tone already scored.

Build-it-yourself vs. managed actor

GDELT is free and keyless, so a naive script is easy — until you hit the 250-per-request ceiling and realize you need correct date-window pagination, the 6-second rate-limit discipline, query-string assembly from separate filter fields, and the mode routing between the doc and timelinevol endpoints. That’s the part that turns a one-off script into maintenance.

On cost, the actor is pay-per-result — a fraction of a cent per article row plus a tiny per-run start fee. There’s no proxy subscription (GDELT’s API is open), so a scheduled hourly monitor of a topic costs very little per month for the article volume it returns. You’re paying for the pagination-and-rate-limit engineering being solved once, not for the data itself.

Common pitfalls

• Sort out your timespan-to-volume ratio. Asking for thousands of articles over a 1-day window returns far fewer than you expect — there simply aren’t enough date windows. Widen timespan when maxResults is large.
• Zero results usually means an over-specific query. A long multi-word phrase, or a restrictive language/country filter, can match nothing in the window. Broaden the query or drop a filter first.
• seendate is index time, not publish time. It records when GDELT first saw the article, in the 20260708T124500Z format — parse it accordingly, and don’t assume it’s the article’s original publication timestamp.
• Tone is a heuristic score, not ground truth. It’s derived from the article text on a roughly negative-ten-to-positive-ten scale. Useful for trend direction, not for definitive sentiment labeling of any single article.
• Deduplicate across scheduled runs. For ongoing monitoring, use overlapping windows (e.g. run hourly with a 2-hour timespan) and dedupe by url or seendate, or you’ll reprocess the same articles.
• This is metadata, not article text. The actor returns GDELT’s indexed metadata — title, URL, domain, tone, image — not the full article body. To get body text, you’d fetch each publisher’s URL yourself, subject to their robots.txt and terms.

Wrapping up

GDELT is one of the best open news datasets on the planet, and its Document API is free — but the 250-per-request ceiling and date-window pagination are what stand between you and a large, time-spanning corpus. This actor handles both, plus the rate-limit pacing and the full query syntax, so you can go from a keyword to thousands of scored, multilingual articles in one run.

▶ Run the GDELT News Scraper on Apify — articles, volume timelines or image-rich stories across 100+ languages, with tone, domain and country on every row. No API key, no login. Export to JSON, CSV or Excel, and start on Apify’s free monthly credit.