GDELT Global News Search Scraper

Search worldwide news coverage through the public GDELT DOC 2.0 index and export clean article records for monitoring, research, alerts, and data pipelines.

The Actor accepts ordinary keywords, quoted phrases, Boolean expressions, and supported GDELT query filters. It returns article titles, URLs, seen dates, source domains, languages, source countries, social images, and the query that found each article.

No GDELT account or API key is required.

What does GDELT Global News Search Scraper do?

GDELT Global News Search Scraper turns one or more news searches into a reusable Apify dataset.

Use it to:

• 🔎 search recent worldwide news for a brand, person, place, product, or event;
• 📰 collect article links and source metadata without maintaining API code;
• 🌍 compare coverage across languages, countries, and publishers;
• ⏰ schedule recurring media-monitoring runs;
• 🧠 feed current article evidence into RAG, analysis, or alerting workflows;
• 📊 export the same records as JSON, CSV, Excel, XML, or RSS.

The Actor uses GDELT's public DOC 2.0 ArticleList JSON surface. It does not scrape publisher article bodies and does not claim access to paid GDELT Cloud data.

Who is it for?

PR and communications teams

Track mentions of a company, executive, campaign, product launch, or crisis across international sources.

Journalists and researchers

Discover coverage around an event and retain source, date, country, and language provenance.

Risk and geopolitical analysts

Schedule searches for supply-chain disruptions, sanctions, conflict indicators, infrastructure incidents, or regulatory change.

Developers and data engineers

Create a stable news-search dataset for dashboards, alerts, enrichment, RAG retrieval, or downstream classification.

Competitive-intelligence teams

Monitor competitors, markets, leadership changes, partnerships, funding announcements, and product releases.

Why use this Actor?

Calling a public endpoint once is easy. Operating repeat searches reliably is harder.

This Actor adds:

• ✅ validated Apify input with low-cost defaults;
• ✅ sequential requests that respect GDELT's shared public rate limit;
• ✅ bounded retry handling for throttling and temporary server errors;
• ✅ strict response and content-type validation;
• ✅ normalized, typed output records;
• ✅ duplicate removal by article URL across all queries;
• ✅ query provenance on every record;
• ✅ datasets, schedules, webhooks, API access, and integrations from Apify.

What data can I extract?

Field	Type	Description
query	string	The input query that produced the article.
title	string	Article headline returned by GDELT.
url	string	Public publisher URL.
seendate	string	GDELT's seen-date value.
socialimage	string, optional	Social preview image when available.
domain	string	Publisher/source domain.
language	string	Language label supplied by GDELT.
sourcecountry	string	Source-country label supplied by GDELT.
scrapedAt	string	UTC time when the Actor saved the record.

A social image is not available for every article. Other source metadata may occasionally be an empty string when GDELT does not populate it.

Input

The smallest valid input is:

{
  "queries": ["climate change"]
}

A monitoring input with explicit options is:

{
  "queries": [
    "\"shipping disruption\"",
    "energy infrastructure attack",
    "border closure"
  ],
  "maxResultsPerQuery": 100,
  "timespan": "7d",
  "sort": "DateDesc"
}

Search query syntax

GDELT supports expressive queries.

Common patterns include:

• a keyword: inflation;
• an exact phrase: "climate policy";
• alternatives: earthquake OR tsunami;
• combined terms: semiconductor AND export;
• a source domain: artificial intelligence domain:reuters.com.

Query syntax is interpreted by GDELT. Start with a simple expression, inspect the results, and then add filters.

Time windows

Use timespan for a rolling window relative to the run time.

Examples:

• 15min for the latest fifteen minutes;
• 24h for the latest day;
• 7d for the latest week;
• 2weeks for the latest two weeks;
• 3months for the latest three months.

For a precise range, use startDateTime and/or endDateTime in UTC YYYYMMDDHHMMSS format.

Do not combine a relative timespan with exact date-time fields.

Sort options

Choose one of GDELT's supported ArticleList sort modes:

• DateDesc — newest first;
• DateAsc — oldest first;
• ToneDesc — more positive tone first;
• ToneAsc — more negative tone first;
• HybridRel — hybrid relevance order.

DateDesc is the default and is usually best for scheduled monitoring.

Output example

{
  "query": "climate change",
  "title": "Example headline returned by GDELT",
  "url": "https://example.com/news/example-story",
  "seendate": "20260717T120000Z",
  "socialimage": "https://example.com/images/story.jpg",
  "domain": "example.com",
  "language": "English",
  "sourcecountry": "United States",
  "scrapedAt": "2026-07-17T12:05:00.000Z"
}

The values above illustrate the schema. Actual values come directly from the live GDELT article index.

How to run the scraper

1. Open the Actor input page.
2. Add one or more topics or GDELT query expressions.
3. Keep the result limit small for your first run.
4. Choose a rolling window or exact UTC date range.
5. Select the desired sort order.
6. Click Start.
7. Open the Dataset tab to preview or export articles.

For recurring monitoring, create an Apify schedule after confirming the query returns the coverage you expect.

How much does it cost to search GDELT news?

The Actor uses pay-per-event pricing: every run has a $0.005 run-start fee, then each unique article saved to the dataset is charged at your plan's tiered rate. Malformed records and duplicate URLs are not saved or charged as articles.

Apify plan tier	Run-start fee	Price per saved article	10 articles	100 articles	1,000 articles
FREE	$0.005	$0.0024185	$0.0292	$0.2469	$2.4235
BRONZE	$0.005	$0.002103	$0.0260	$0.2153	$2.1080

These examples use run cost = $0.005 + (saved articles × tier price) and exclude unrelated usage elsewhere in your Apify account. Higher subscription tiers receive larger per-article discounts; confirm your current tier in the Apify pricing panel before starting a run.

Free-plan estimate: Apify currently includes $5 of monthly usage credits on the FREE plan. At the current FREE-tier event prices, that covers approximately 2,065 saved articles in one run (($5 − $0.005) ÷ $0.0024185), before any other usage charged to the same monthly credits. Multiple runs each incur the $0.005 start fee, so their combined article allowance is slightly lower.

Deduplication behavior

Articles are deduplicated by their full URL across the entire run.

If the same URL matches multiple queries, the first matching query in your input is retained in query and the duplicate is skipped.

GDELT or publishers may expose semantically identical stories under different URLs. Those remain separate records because the Actor does not guess that distinct URLs are duplicates.

Scheduling a news monitor

A typical monitoring workflow is:

1. create one focused query per topic or stakeholder;
2. use DateDesc with a short rolling window;
3. schedule the Actor at an interval appropriate for your team;
4. connect a webhook, Make, Zapier, Slack workflow, or database export;
5. filter or classify new dataset rows downstream.

GDELT's public endpoint is shared infrastructure. Avoid schedules that create unnecessary request volume.

Integrations

Google Sheets

Use the Apify Google Sheets integration to append article records to a collaborative tracker.

Slack or Microsoft Teams alerts

Trigger a webhook after a successful run and send selected headlines to an alert channel.

Make and Zapier

Start a run from an automation, retrieve dataset items, then route coverage to a CRM, email, or database.

Data warehouses

Fetch dataset items through the API and load them into BigQuery, Snowflake, PostgreSQL, or your object store.

RAG and AI pipelines

Use article metadata as discovery evidence, then retrieve publisher pages only when your downstream workflow is authorized to do so.

JavaScript API example

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/gdelt-global-news-search-scraper').call({
  queries: ['"climate policy"'],
  maxResultsPerQuery: 25,
  timespan: '7d',
  sort: 'DateDesc',
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Python API example

from apify_client import ApifyClient

client = ApifyClient('YOUR_APIFY_TOKEN')
run = client.actor('automation-lab/gdelt-global-news-search-scraper').call(run_input={
    'queries': ['artificial intelligence domain:reuters.com'],
    'maxResultsPerQuery': 25,
    'timespan': '24h',
    'sort': 'DateDesc',
})

for item in client.dataset(run['defaultDatasetId']).iterate_items():
    print(item)

cURL API example

curl -X POST \
  'https://api.apify.com/v2/acts/automation-lab~gdelt-global-news-search-scraper/runs?token=YOUR_APIFY_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "queries": ["supply chain disruption"],
    "maxResultsPerQuery": 25,
    "timespan": "7d",
    "sort": "DateDesc"
  }'

After the run finishes, read items from its defaultDatasetId.

Use with Apify MCP

Connect the Actor to Claude or another MCP client through Apify MCP.

Claude Code setup

claude mcp add --transport http apify \
  'https://mcp.apify.com?tools=automation-lab/gdelt-global-news-search-scraper'

Claude Desktop setup

Add this server to the Claude Desktop MCP configuration:

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/gdelt-global-news-search-scraper"
    }
  }
}

Cursor setup

Add the same mcpServers JSON to Cursor's MCP settings and restart the client.

VS Code setup

Open the MCP server settings in VS Code, add the Apify HTTP endpoint above, and enable it for your workspace.

Example prompts:

• “Run the GDELT news scraper for semiconductor export controls from the last seven days.”
• “Collect the newest coverage of shipping disruption and summarize sources by country.”
• “Create a dataset of Reuters AI coverage from the last 24 hours.”

Reliability and rate limits

The public GDELT DOC API asks clients to leave at least five seconds between requests on shared infrastructure.

This Actor processes queries sequentially and waits at least six seconds between requests.

Temporary throttling, server errors, timeouts, unexpected content types, and malformed envelopes receive bounded retries.

A query that validly returns zero articles is considered successful. If every query fails at the extraction layer, the Actor fails instead of silently returning a misleading success.

Limitations

• GDELT controls index coverage, ranking, metadata, and retention.
• ArticleList returns at most 250 records per query.
• The Actor does not paginate beyond that public ArticleList limit.
• The Actor returns article metadata, not full publisher article text.
• Some records do not include a social image or complete source metadata.
• Search results can change as GDELT updates its index.
• Publisher links may later move, redirect, or become unavailable.
• Exact-date searches are subject to the time range supported by GDELT.

Tips for better results

• Put multi-word names in quotes when you need phrase matching.
• Use several focused queries instead of one ambiguous expression.
• Begin with 10–25 results before increasing the limit.
• Use a short rolling window for frequent schedules.
• Keep DateDesc for alerts and recent-coverage monitoring.
• Add GDELT-supported domain, language, or source-country filters to the query when needed.
• Review a sample dataset before automating downstream decisions.

Is it legal to use GDELT news data?

This Actor accesses a public GDELT search endpoint and returns metadata plus publisher URLs.

You are responsible for your use of the data and for complying with GDELT terms, publisher terms, copyright rules, privacy laws, and regulations that apply to your jurisdiction and workflow.

Do not treat a search result as permission to republish a publisher's article body. Seek legal advice for high-risk or commercial redistribution use cases.

Troubleshooting

My run returns no articles

Try a simpler query, a wider time window, or a larger result limit. Confirm the expression is supported by GDELT and remove overly restrictive filters.

My exact date range is rejected

Use UTC timestamps in YYYYMMDDHHMMSS format, ensure the start is not after the end, and stay within GDELT's supported search period.

One query failed but the run succeeded

The Actor isolates query failures. It keeps useful results when at least one query completes, and records failed-query details in the run log.

The run takes longer with several queries

This is expected. Queries are intentionally sequential to respect GDELT's public rate limit.

An article appears under only one query

URL deduplication keeps the first occurrence. Reorder the queries if a particular provenance label should win.

FAQ

Does this Actor require a GDELT key?

No. It uses the anonymous public GDELT DOC 2.0 article-search endpoint.

Can I search multiple topics?

Yes. Supply up to ten queries in one run. Each saved record includes its originating query.

Can I retrieve more than 250 articles per query?

No. Version 1 intentionally follows the public ArticleList maximum and does not claim unsupported pagination.

Does it download full article content?

No. It exports GDELT article metadata and publisher links.

Are duplicate articles charged twice?

Not when they share the same URL in one run. Duplicate URLs are skipped before dataset storage and article charging.

Can an empty query result succeed?

Yes. A valid empty GDELT response is different from extraction failure.

Can I export to CSV or Excel?

Yes. Use the dataset export controls or Apify dataset API.

Related Automation Labs actors

For broader search and enrichment workflows, consider:

• Google News Scraper for Google News discovery workflows;
• Google Search Scraper for general web search results;
• Website Content Crawler when you are authorized to retrieve content from selected article URLs.

Choose this Actor when GDELT's worldwide news index, source metadata, and query language are the core requirement.

Support

If a run behaves unexpectedly, open an issue from the Actor page and include:

• a safe copy of the input;
• the run URL or run ID;
• the query that behaved unexpectedly;
• the expected and actual result;
• whether the issue is repeatable.

Do not include secrets, private tokens, or confidential query data in a public report.