GDELT Worldwide News Scraper

Search worldwide news through the GDELT 2.0 DOC API and get back one row per article: title, url, domain, sourceCountry, language, publishedAt and socialImage.

GDELT indexes online news from most of the planet in 65+ languages. The endpoint is public and unauthenticated, which is why this runs without a browser and doesn't need a proxy.

The pacing rule you should know about

GDELT asks for one request every 5 seconds per IP and answers 429 with that sentence in the body when you go faster. The actor paces itself to that limit and backs off in multiples of it, so a throttled run recovers instead of coming back empty. GDELT itself often takes 10–15 seconds to answer, so a run legitimately taking a minute is normal, not stuck.

Input

Field	Type	Default	Notes
query	string	— (required)	Quote phrases: "climate change". Combine with OR, or operators like domain:reuters.com.
maxItems	integer	100	Hard-capped at 250 — that's GDELT's own per-request ceiling, not ours.
sort	string	DateDesc	DateDesc (newest), DateAsc (oldest), HybridRel (relevance).
timespan	string	—	1d, 3d, 1w, 1m, 3m.
sourceCountry	string	—	GDELT country code, appended as sourcecountry:{code} — US, UK, FR, DE, IN.
sourceLang	string	—	Appended as sourcelang:{code} — english, french, spanish.
proxyConfiguration	object	—	Optional and unnecessary. Only helps if your own IP is the one being throttled.

{ "query": "\"electric vehicles\"", "timespan": "3d", "sort": "DateDesc", "maxItems": 250 }

Very short or very common single words get rejected by GDELT itself. Add a second word or quote a phrase.

Output

{
  "ok": true,
  "title": "…",
  "url": "https://…",
  "domain": "example.com",
  "sourceCountry": "United States",
  "language": "English",
  "publishedAt": "2026-06-11T12:00:00.000Z",
  "socialImage": "https://…"
}

Rows are deduplicated by URL. Any of these fields can be null — GDELT doesn't populate them all on every article. socialImage is missing often, and publishedAt is null when GDELT's seendate won't parse. A row with neither a url nor a title is dropped before it's counted.

Limits worth knowing

• 250 articles per query, full stop. That's a GDELT limit on the DOC API, and there's no pagination past it. To go wider, split the job by keyword, by sourceCountry, or by narrower timespan windows and stitch the results.
• GDELT's index covers roughly the last 3 months. Older news isn't in there to find.
• Headline-level data only. You get the title, link and metadata — not the article body. Follow the url yourself if you need the text.
• On a malformed query GDELT sometimes returns a plain-text error string with HTTP 200 instead of JSON. The actor catches that and turns it into a BAD_INPUT row rather than crashing.

Billing

$2.00 per 1,000 articles ($0.002 each), and nothing charged for starting a run. It's the same $2.00 on the free plan as on any paid one, with nothing tiered by volume.

There is exactly one charge event on this actor. No per-query fee, no proxy surcharge, no monthly minimum. Diagnostic rows, rejected queries and no-result runs are all free, so a query GDELT refuses costs $0.00.

Diagnostic rows

Failures come back as a single ok: false row with an errorCode, never as a silent empty dataset, and are never charged.

• BAD_INPUT — GDELT rejected the query, usually for being too short or too common. Quote the phrase.
• NO_RESULTS — valid query, nothing matched. Broaden it or widen timespan.
• RATE_LIMITED / SERVER_ERROR / NETWORK — transient. The actor already retried with backoff before writing this.