Skip to main content

​
Overview

The get_entity tool returns a Wikipedia-verified entity profile from the GDELT Entity Graph (GEG). It provides the entity’s master record, linked story clusters, co-occurring entities, and an activity timeline. This is the primary entity tool — try it first for any person or organization question.
Returns reference cards that link to other products. Use get_media_event_cluster to hydrate linked stories, and get_entity again to hydrate co-occurring entities.

​
Parameters

​
canonical_name
string
required
Entity name in lowercase. Examples: donald trump, elon musk, tesla.
​
type
string
required
Entity type: person or organization.
​
days
integer
default:"1"
Lookback window in days. Default 1, max 30.
​
date
string
Anchor/end date in YYYY-MM-DD format. Defaults to today UTC.
​
detail
string
default:"summary"
Response detail level.
Level~TokensStoriesCo-occsTimeline
summary~3003 ref cards10 ref cardsNo
standard~1,20020 ref cards25 ref cardsYes
full~1,500Paginated50 ref cardsYes
​
limit
integer
default:"10"
Number of linked story clusters (full detail only). Max 50.
​
offset
integer
default:"0"
Story cluster pagination offset (full detail only).
​
language
string
Filter articles by source language (e.g. English, Spanish).
​
category
string
Filter linked stories by topic category.
​
scope
string
Filter linked stories by geographic scope: local, national, global.

​
Response Shape

​
Summary (~300 tokens)

{
  "entity": {
    "canonical_name": "donald trump",
    "display_name": "Donald Trump",
    "wikipedia_url": "https://en.wikipedia.org/wiki/Donald_Trump",
    "type": "person",
    "total_articles": 9241
  },
  "linked_stories": [
    {
      "cluster_id": "abc123",
      "cluster_label": "Trump announces tariffs on imports",
      "category": "economy_business",
      "scope": "global",
      "cluster_article_count": 47
    }
  ],
  "co_occurrences": [
    { "related_name": "joe biden", "related_type": "person", "co_occurrence_count": 142 }
  ],
  "filters": { "days": 7, "detail": "summary" },
  "metadata": { "total_stories": 24, "returned_stories": 3, "has_more": true }
}

​
Standard / Full

Adds timeline (daily article counts + sentiment), richer co-occurrence cards (with avg_combined_salience, last_seen), time_bucket on story refs, and more story/co-occ cards.

​
Usage Examples

# Quick entity lookup
GET /api/v1/entity-geg?canonical_name=elon+musk&type=person&days=7&detail=summary

# Full profile with paginated stories
GET /api/v1/entity-geg?canonical_name=tesla&type=organization&days=30&detail=full&limit=20

# Filter by category
GET /api/v1/entity-geg?canonical_name=donald+trump&type=person&days=7&category=politics_governance

​
Workflow

1

Look up entity

Call get_entity(canonical_name='elon musk', type='person', detail='summary').
2

Explore a linked story

Take a cluster_id from linked_stories and call get_media_event_cluster(cluster_id).
3

Explore co-occurrences

Take a related_name from co_occurrences and call get_entity(related_name, related_type).