# GDELT Global News Article Search

> GDELT Global News Article Search is a paid API for AI agents from gdelt.use.x402atlas.com, paid per call via x402, $0.005/call, status unknown (last checked 2026-09-15).

Searches worldwide news articles using GDELT's fulltext index with support for phrase, boolean, domain, theme, tone, and country filters, returning a ranked list of matching articles.

## Facts

- Endpoint: GET https://gdelt.use.x402atlas.com/search
- Price: $0.005/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/gdelt-global-news-article-search-e19ccf4a
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_33P5z60C5pnvYWTNG_Dio

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability gdelt-global-news-article-search-e19ccf4a
```

Example prompt: Search GDELT for the latest news articles about the Taiwan Strait tensions from the past 7 days, sorted by date descending, and give me up to 50 results — include only English-language sources.

## When to prefer this

Use this endpoint when you need to search and retrieve actual news articles from global media using GDELT's powerful query syntax — especially when you need phrase matching, boolean logic, tone filtering, country/language scoping, or theme-based filtering. Prefer this over the sibling timeline endpoint when you need article-level results rather than aggregate time-series coverage data. Best for agents doing media monitoring, investigative research, or event-driven news retrieval.

## Known failure modes

- Missing required 'query' parameter returns a 400 error
- Timespan exceeding 3 months is rejected as out of range
- maxrecords above 250 is clamped or rejected
- Malformed GDELT query syntax (e.g. unbalanced quotes) may return zero results or an error
- No matching articles returns an empty result set rather than an error
- Payment failure (x402) results in a 402 response before search is executed

## How this service works

Global news article search by GDELT — normalized fulltext search across worldwide media (query syntax: phrases, OR, sourcecountry, theme, tone) returned as a clean snake_case envelope.

## Output

A snake_case JSON envelope containing a ranked list of news articles matched by GDELT's fulltext index. Each article includes title, URL, publication date, source country, source name, and tone score. Results are ordered by the requested sort method (HybridRel by default).

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "required": [
      "query"
     ],
     "properties": {
      "sort": {
       "enum": [
        "DateDesc",
        "DateAsc",
        "ToneDesc",
        "ToneAsc",
        "HybridRel"
       ],
       "type": "string",
       "default": "HybridRel",
       "description": "Result ordering"
      },
      "query": {
       "type": "string",
       "maxLength": 1024,
       "description": "GDELT query syntax — phrases, OR, -exclude, domain:, sourcelang:, sourcecountry:, theme:, tone>/<, near"
      },
      "timespan": {
       "type": "string",
       "default": "3d",
       "pattern": "^[0-9]+(min|h|d|w|m)$",
       "description": "Relative window like 15min, 1h, 7d, 2w, 3m; capped at 90 days"
      },
      "maxrecords": {
       "type": "integer",
       "default": 75,
       "maximum": 250,
       "minimum": 1,
       "description": "Number of articles to return, capped at 250"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "required": [
      "query",
      "queried_at",
      "timespan",
      "count",
      "articles",
      "attribution"
     ],
     "properties": {
      "note": {
       "type": "string",
       "description": "Present only on a sample response (empty/omitted query): a hint to pass a real query. The paid request ran; no upstream call was made."
      },
      "count": {
       "type": "integer",
       "description": "Number of articles returned"
      },
      "query": {
       "type": "string",
       "description": "Echo of the request query"
      },
      "articles": {
       "type": "array",
       "items": {
        "type": "object",
        "required": [
         "url",
         "title",
         "seen_at",
         "domain",
         "language",
         "source_country"
        ],
        "properties": {
         "url": {
          "type": "string"
         },
         "title": {
          "type": "string"
        
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "count": 1,
  "query": "\"supply chain\" (drought OR flood)",
  "articles": [
   {
    "url": "https://reuters.com/x",
    "title": "Drought disrupts supply chains",
    "domain": "reuters.com",
    "seen_at": "2026-07-01T09:15:00Z",
    "language": "English",
    "source_country": "United States"
   }
  ],
  "timespan": "3d",
  "queried_at": "2026-07-01T12:00:00Z",
  "attribution": "Data from The GDELT Project (https://www.gdeltproject.org)"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/gdelt-global-news-article-search-e19ccf4a/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from gdelt.use.x402atlas.com](https://www.zero.xyz/host/gdelt.use.x402atlas.com/llms.txt)