# GDELT Entity Graph API

> GDELT Entity Graph API is a paid API for AI agents from gdelt-x402-api.planbdj.workers.dev, paid per call via x402, $0.05/call, status unknown (last checked 2026-09-13).

Returns an entity-centric news intelligence graph including top sources, geo-locations, and sentiment trend for a named entity over a given timespan, powered by the GDELT dataset.

## Facts

- Endpoint: POST https://gdelt-x402-api.planbdj.workers.dev/news/entity-graph
- Price: $0.05/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-13
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/gdelt-entity-graph-api-4778eb28
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_RWhPMMS6dbYO8OkuSfES9

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-entity-graph-api-4778eb28 -d '<json body>'
```

Example prompt: Pull the GDELT entity graph for 'Elon Musk' over the last 7 days — I want to see which news outlets are covering him most, where in the world the coverage is concentrated, and how the sentiment has trended day by day.

## When to prefer this

Choose this endpoint when you need a structured, multi-dimensional intelligence snapshot of how a specific named entity is being covered across global news — including which outlets cover it most, where geographically the coverage is concentrated, and how sentiment is trending over time. It is ideal for brand monitoring, competitive intelligence, geopolitical research, and journalistic investigation. Prefer it over raw news search APIs when you want aggregated, pre-computed entity graphs rather than individual article retrieval.

## Known failure modes

- Entity not found or very low coverage — may return empty arrays for sources, locations, or sentiment
- Invalid timespan format — API may reject or return an error
- GDELT data lag — coverage may be delayed by up to 24 hours for very recent events
- Ambiguous entity names (e.g. 'Apple' could be fruit or company) may return mixed results
- Payment failure on Base mainnet — x402 transaction not confirmed, request blocked

## How this service works

AI-friendly JSON API for global news intelligence. Built on GDELT (free public source), optimized for AI agents — clean responses, 5 use-case endpoints, parallel-aggregated entity graphs, no rate limits, no API keys. Pay-per-query in USDC on Base mainnet via x402.

## Output

A JSON object containing: the queried entity name and timespan, an array of top news source domains with their mention counts, an array of top geographic locations (with latitude, longitude, country name, and mention count), and a sentiment trend array with daily average tone scores (negative = negative sentiment).

## 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",
      "HEAD",
      "DELETE"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "required": [
      "entity"
     ],
     "properties": {
      "entity": {
       "type": "string",
       "description": "Person, organization, or location name"
      },
      "timespan": {
       "type": "string",
       "description": "Time window (default 7d)"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "required": [
      "entity",
      "timespan",
      "sentiment_trend",
      "top_locations",
      "top_sources"
     ],
     "properties": {
      "entity": {
       "type": "string"
      },
      "timespan": {
       "type": "string"
      },
      "top_sources": {
       "type": "array",
       "items": {
        "type": "object",
        "required": [
         "domain",
         "mention_count"
        ],
        "properties": {
         "domain": {
          "type": "string"
         },
         "mention_count": {
          "type": "integer"
         }
        }
       }
      },
      "top_locations": {
       "type": "array",
       "items": {
        "type": "object",
        "required": [
         "name",
         "lat",
         "lng",
         "mention_count"
        ],
        "properties": {
         "lat": {
          "type": "number"
         },
         "lng": {
          "type": "number"
         },
         "name": {
          "type": "string"
         },
         "country_code": {
          "type": "string"
         },
         "mention_count": {
          "type": "integer"
         }
        }
       }
      },
      "sentiment_trend": {
       "type": "array",
       "items": {
        "type": "object",
        "required": [
         "date",
         "avg_tone"
        ],
        "properties": {
         "date": {
          "type": "string"
         },
         "avg_tone": {
          "type": "number"
         }
        }
       }
      }
     }
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "entity": "Elon Musk",
  "timespan": "7d",
  "top_sources": [
   {
    "domain": "ft.com",
    "mention_count": 12
   }
  ],
  "top_locations": [
   {
    "lat": 37.09,
    "lng": -95.71,
    "name": "United States",
    "country_code": "",
    "mention_count": 30
   }
  ],
  "sentiment_trend": [
   {
    "date": "2026-04-30T00:00:00",
    "avg_tone": -1.5
   }
  ]
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/gdelt-entity-graph-api-4778eb28/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from gdelt-x402-api.planbdj.workers.dev](https://www.zero.xyz/host/gdelt-x402-api.planbdj.workers.dev/llms.txt)