Track an entity across datasets

One task, end to end: watch what is happening to a company — in the news, in federal contracting, and in the physical world. It takes four calls, and the shape of it generalises to almost everything else you will build here. The responses below are examples recorded in August 2026. Run the calls for current data and inspect meta.query_window, meta.coverage and applied_filters before using the results. The design starts by resolving the name once. Then check which identifier each destination accepts: an e_… identity works on many surfaces, while a wiki:… or llm:… candidate and source-specific records may need a different, documented key. Never infer a cross-dataset join from a name alone.

Resolve the name

Never filter by a company name string. Names are ambiguous, they change, and every surface spells them differently. Ask the resolver instead:

curl -G "https://gdeltcloud.com/api/v2/search" \
  --data-urlencode "q=Lockheed Martin" \
  --data-urlencode "type=organization" \
  --data-urlencode "country_match=strict" \
  --data-urlencode "limit=3" \
  -H "Authorization: Bearer $GDELT_API_KEY"

Illustrative candidate response; counts and source availability depend on the request and account:

{
  "success": true,
  "query": "Lockheed Martin",
  "count": 1,
  "data": [
    {
      "entity_id": "e_7e9bc31057830fbf",
      "name": "LOCKHEED MARTIN CORP",
      "entity_type": "organization",
      "match_type": "exact_alias",
      "match_reason": "Exact normalized name match",
      "coverage_30d": 76,
      "monitorable": true,
      "sources": {
        "news": true, "sec": true, "gov": true, "wiki": true,
        "gem": false, "sanctions": false, "china": false, "epoch": false
      },
      "identifiers": {
        "ticker": ["LMT"],
        "us_sec_cik": ["936468"],
        "gleif": ["DPRBOZP0K5RM2YE8UU08"],
        "wikidata_qid": ["Q7240"]
      }
    }
  ]
}

Three fields decide what you do next:

entity_id is the selected identity. Keep its exact value and reuse it only on endpoints that accept its identifier space; e_…, wiki:… and llm:… are not interchangeable. A facility has a separate facility_id.
sources describes measured source availability. It does not establish the result count of another endpoint or prove that an entity owns no facilities. Withheld source keys are omitted; missing or failed coverage remains unknown. Inspect the actual selected-ID response.
identifiers helps reach source-specific surfaces. SEC filing detail takes a CIK; some asset and ownership endpoints use GEM owner IDs or LEIs. Check the identifier parameters for each call.

An empty result means this search found no candidate; it does not establish that the entity does not exist or has no activity. Refine the name, type or country evidence before concluding anything. When several candidates come back, show them — do not auto-pick the top one.

What is happening to it

curl -G "https://gdeltcloud.com/api/v2/events" \
  --data-urlencode "entity=e_7e9bc31057830fbf" \
  --data-urlencode "days=30" \
  --data-urlencode "sort=significance" \
  --data-urlencode "limit=3" \
  -H "Authorization: Bearer $GDELT_API_KEY"

Three coded events, ranked by how much they matter rather than by when they landed:

`event_date`	`title`	`significance`
2026-07-30	US signs $58.6 billion Patriot missile deal amid stockpile concerns	0.7507
2026-08-03	U.S. signs deal to boost production of missile interceptors and parts	0.7037
2026-08-12	Pentagon signs $4.7 billion PAC-3 production deal with Lockheed Martin	0.5685

sort=significance is the default and the one you want for monitoring. Sorting by recency gives you a feed dominated by whatever a wire service published in the last hour.Start wide. The most common mistake on this API is stacking four filters on the first call and concluding the data is missing when the empty result is really your AND.

Read the evidence

An event is a claim; the articles are why we made it. Every event links to the story it was coded from — take the top row of that table:

curl "https://gdeltcloud.com/api/v2/events/cameoplus_997814ae67ea431e/stories" \
  -H "Authorization: Bearer $GDELT_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "464f8872c1f3",
      "title": "US signs $58.6 billion Patriot missile deal amid stockpile concerns",
      "story_date": "2026-07-30",
      "article_count": 22,
      "relation": "primary"
    }
  ]
}

Then follow the story id to the source URLs:

curl "https://gdeltcloud.com/api/v2/stories/464f8872c1f3/articles?limit=3" \
  -H "Authorization: Bearer $GDELT_API_KEY"

{
  "success": true,
  "data": [
    {
      "url": "https://www.ensonhaber.com/abd-ordusu-patriot-siparisini-586-milyar-dolara-cikardi-h1553674",
      "title": "ABD ordusu, Patriot siparişini 58,6 milyar dolara çıkardı",
      "domain": "ensonhaber.com",
      "article_date": "2026-07-30",
      "role": "core",
      "language": "tr"
    },
    {
      "url": "https://www.hindustantimes.com/world-news/pentagon-widens-patriot-missile-order-to-nearly-59-billion-101785405420219.html",
      "title": "Pentagon Widens Patriot Missile Order to Nearly $59 Billion",
      "domain": "hindustantimes.com",
      "article_date": "2026-07-30",
      "role": "core",
      "language": "en"
    },
    {
      "url": "https://www.khaama.com/us-army-awards-lockheed-martin-up-to-58-6-billion-patriot-missile-contract/",
      "title": "US Army Awards Lockheed Martin Up to $58.6 Billion Patriot Missile Contract",
      "domain": "khaama.com",
      "article_date": "2026-07-30",
      "role": "core",
      "language": "en"
    }
  ]
}

Twenty-two articles back that one story, and the first three are Turkish, Indian and Afghan outlets — independent coverage rather than one wire story republished, which is how you tell a well-supported event from a thin one. Build citation into your feed from the start; an alert nobody can verify gets ignored the second time it fires.

Fan out using supported identifiers

This selected e_… ID is accepted by the examples below. Other candidates may have a wiki:… or llm:… ID that a destination cannot use. Check the destination contract and the actual response; the sources map alone cannot promise rows or establish absence.Press tone over time — scored by us across news coverage, per entity per story per day.

curl "https://gdeltcloud.com/api/v2/entities/e_7e9bc31057830fbf/tone?days=30" \
  -H "Authorization: Bearer $GDELT_API_KEY"

{
  "status": "available",
  "start_date": "2026-07-28",
  "end_date": "2026-08-26",
  "rows": [
    {
      "bucket_date": "2026-08-22",
      "scored_story_count": 1,
      "avg_tone_score": 20,
      "avg_news_tone_score": 20,
      "avg_risk_score": 10,
      "avg_confidence": 0.65,
      "languages": ["en"]
    }
  ]
}

Rows come back under rows, one per bucket date, and 22 of the 27 buckets in that real response carried avg_news_tone_score: null — days with coverage but no news-tone reading. That is not a zero. Charting it as one invents a trend.Share of voice — the same tone in context: a drop reads differently when coverage volume tripled the same week.

curl -G "https://gdeltcloud.com/api/v2/share-of-voice" \
  --data-urlencode "entity_id=e_7e9bc31057830fbf" \
  --data-urlencode "days=30" \
  --data-urlencode "country=United States" \
  -H "Authorization: Bearer $GDELT_API_KEY"

{
  "denominator": {
    "hash": "2c71eadfb2976692801df82539286f8ac4a77059f6a3220a117e7a189a482c02",
    "scope": { "country": ["USA"] },
    "unit": "story",
    "total_story_count": 9281
  },
  "rows": [
    {
      "bucket_date": "2026-08-12",
      "entity_story_count": 4,
      "denominator_story_count": 412,
      "story_share": 0.009708737864077669,
      "avg_tone_score": 20
    }
  ]
}

This endpoint refuses to compute without a denominator — a share with no stated denominator is not a number. Omit one and you get 400 DENOMINATOR_REQUIRED, whose details.allowed_filters names every filter that defines one. The denominator comes back with a hash, so the same share is reproducible months later.Federal awards — the same id against USAspending.

curl "https://gdeltcloud.com/api/v2/gov/awards?entity=e_7e9bc31057830fbf&limit=3" \
  -H "Authorization: Bearer $GDELT_API_KEY"

{
  "summary": {
    "recipients": 22,
    "total_awards": 227,
    "total_obligated": 527864339702.59
  },
  "awards": [
    {
      "award_id": "FA862524F3034",
      "recipient_name": "LOCKHEED MARTIN CORP",
      "award_amount": 1564462687,
      "awarding_agency": "Department of Defense",
      "awarding_sub_agency": "Department of the Air Force",
      "action_date": "2028-12-31",
      "source_url": "https://www.usaspending.gov/award/CONT_AWD_FA862524F3034_9700_FA862520D3000_9700"
    }
  ],
  "cross_source": {
    "federal_awards": { "awards": 227, "total_obligated": 527864339702.58997 },
    "sec_filer": true,
    "facilities_owned": 0
  }
}

Twenty-two SAM.gov recipient records roll up under one entity id. That collapse is the product: filtering by the name string would have matched some of the twenty-two and silently dropped the rest.Physical assets — same call shape for this e_… identifier. The example resolver response reported "gem": false for Lockheed Martin, but that flag alone does not prove the company owns no facilities. Here we use another selected identity, Chevron Corp, e_7efd743ec55a5285.

curl "https://gdeltcloud.com/api/v2/facilities?entity=e_7efd743ec55a5285&limit=3" \
  -H "Authorization: Bearer $GDELT_API_KEY"

{
  "success": true,
  "data": [
    {
      "facility_id": "s_53d5bbd26e78ba71",
      "name": "Advantage Oil Pipeline",
      "facility_type": "oil_pipeline",
      "country_iso3": "USA",
      "status": "operating",
      "owners": [
        { "entity_id": "e_7efd743ec55a5285", "name": "Chevron Corp" },
        { "entity_id": "e_5c06663ad563ae9f", "name": "Plains All American Pipeline LP" }
      ],
      "owner_portfolio_url": "/api/v2/facilities?owner_entity_id=e_7efd743ec55a5285"
    }
  ]
}

If you had filtered by name instead of by id, each of these four would have matched a different subset and you would have silently dropped half the data — without any endpoint returning an error.

Every request and response above was run on 2026-08-26 and is reproduced as returned, trimmed to the fields each step uses. Live rows carry more, and the values move with the news.

Doing the same thing through MCP

Same four steps, no HTTP. Point an agent at the MCP server and it discovers the tools itself:

gdelt_cloud_tool_call("search", {q: "Lockheed Martin", type: "organization", limit: 3})
gdelt_cloud_tool_call("events", {entity: "e_...", days: 30})
gdelt_cloud_tool_call("event_stories", {event_id: "..."})
gdelt_cloud_tool_call("gov_awards", {entity: "e_..."})

Use REST when you are writing a service; use MCP when a model is deciding what to call next. The data and the gating are identical — the MCP routes to the same serve functions.

Four things worth knowing before you build

Read the effective query window

Without an entity filter, Event and Story lists default to a rolling 24 hours; an entity-filtered list defaults to 30 calendar days. Other families have their own defaults. Read meta.query_window and pass days or explicit date_start/date_end whenever the window matters. Windows are bounded — an unbounded scan across the whole corpus is refused rather than served slowly.

Read applied_filters on every response

It echoes what the server actually applied, using canonical names whatever spelling you sent. If a strict endpoint does not recognize a parameter, the request fails with 400 UNKNOWN_PARAM and names the parameters it does accept. On an endpoint still using the compatibility contract, the request may succeed but list that parameter under applied_filters.ignored — a 200 that quietly answered a different question. In either case, correct the request before using the returned data.

null is not zero

A null metric means the observable was not found. A 0 means it was found and measured as zero. The tone response above is the live case: most buckets have no news-tone reading, and charting them as 0 invents a trend that is not there.

Paginate with the cursor, not an offset

For Event and Story lists, copy pagination.next_cursor into the next request’s cursor until it is null; page at the documented maximum when collecting all rows. QU is charged per call, so a shorter page does not save QU. Do not infer completeness from a short page. Check meta.coverage.window_complete before treating a date range as complete.

Run it on a schedule

Hand this same question to a hosted Monitor and have it deliver new matches to you.

Recipes

Short copy-paste queries for the common shapes.

Start here

Monitors

Products

Data

How the data is made

Use cases

Track an entity across datasets

Doing the same thing through MCP

Four things worth knowing before you build

Next

Run it on a schedule

Recipes

​Doing the same thing through MCP

​Four things worth knowing before you build

​Next

Run it on a schedule

Recipes

Doing the same thing through MCP

Four things worth knowing before you build

Next