Retrieve Stories by topic and country, inspect their sources, then connect reporting to structured Events. Build a repeatable feed without assembling the ingestion and grouping pipeline yourself.
GET /api/v2/storiesChoose a topic, country and date window. 3 records in this saved page.
Country filter: USA. May match actor origin or reported location; returned Stories can concern places outside this country.
Zelensky says US is preparing investments in Ukraine
Serhiy Koretsky discusses defense and energy with US envoy
Indiana Gov. Mike Braun announces nuclear regulatory partnership
Captured 2026-09-25. These are the exact saved dates and identifiers. Running this request again can return changed results.
GET https://gdeltcloud.com/api/v2/stories?date_start=2026-09-18&date_end=2026-09-24&limit=3&include_images=false&include_entity_images=false&sort=recent&country=USA&has_events=true&search=energy&search_mode=lexical: "${GDELT_CLOUD_API_KEY:?Set GDELT_CLOUD_API_KEY}"
curl --fail-with-body --max-time 60 --get 'https://gdeltcloud.com/api/v2/stories' \
--header "Authorization: Bearer $GDELT_CLOUD_API_KEY" \
--header 'Accept: application/json' \
--data-urlencode 'date_start=2026-09-18' \
--data-urlencode 'date_end=2026-09-24' \
--data-urlencode 'limit=3' \
--data-urlencode 'include_images=false' \
--data-urlencode 'include_entity_images=false' \
--data-urlencode 'sort=recent' \
--data-urlencode 'country=USA' \
--data-urlencode 'has_events=true' \
--data-urlencode 'search=energy' \
--data-urlencode 'search_mode=lexical'Pagination: this is one saved page. Follow the response’s pagination contract to retrieve additional pages; each request uses additional QU. Treat incomplete coverage as incomplete, including an empty result.
All requested dates were served in this capture. 7 served dates. Recorded examples are historical; current results may differ.
INSIDE THE EVENT RECORD
GDELT Cloud adds structured classification, actor roles, geographic precision and explainable Event metrics to the raw article stream. Here is what the API returned for one Event in this workflow.
Make Public Statement · 2026-09-24
Prioritize within the returned feed.
How confidently the reporting was coded.
Intensity on the event’s domain scale.
How much the wider system depends on the node.
Potential for effects to travel beyond the event.
Exposure of traded claims to the development.
Model judgments for prioritization, not measured losses or calibrated probabilities. Compare magnitude within its event domain. Missing scores stay unknown.
The event described is Zelensky's neutral public statement about preparations for investment.
The article excerpt does not describe third-party commitments dependent on this relationship.
The statement concerns possible US investment in Ukraine, but no active transmission mechanism or binding commitment is described.
The reported investment is being prepared; no binding or realized change to a claim is described.
THREE STEPS, A WORKING WORKFLOW
Dates, topics, places and classification are explicit request parameters.
Keep original sources, model scores and coverage beside the result.
Copy a request into your application. Start with one bounded page.
DATA BEHIND THIS WORKFLOW
GDELT Cloud codes Events and clusters Stories from the raw GDELT article stream. These structured records are GDELT Cloud outputs; GDELT’s own coded Events, themes and tone are not inputs.
Open the selected Story’s linked Events and source articles. Inspect what happened, how it is classified and which reporting supports it.
Detail is fetched using the first returned Story ID. Only Events and sources actually linked by the response are shown.
Select “Add more context” in the saved demo to inspect the additional records ↑SHAPED BY CUSTOMER USAGE
Paying news and marketing accounts use recent, country-filtered and topic-filtered Story queries through REST and MCP. The example below adapts that recurring feed pattern.
Based on observed recurring requests from paying accounts. This adapted demo is illustrative; the additional dataset combination is a possibility you can build, not a claim about the customer’s deployment.
WORK WITH WHAT YOU HAVE
Feed a CMS, newsletter workflow or media-monitoring product with grouped reporting and the sources behind it.
Start with a topic feed in Explore, then copy its request into a small application or MCP workflow.
YOUR WORKLOAD, MADE EXPLICIT
Model the whole retrieval workflow before you integrate it. Adjust polling, pagination, detail calls and additional context.
This estimate uses 30 days. Detail calls are 1 QU each; saved enrichment is charged once per run. Retries default to zero. It does not include other account usage.
Lowest current public monthly plan covering these QU and required REST capabilities. 1,500 QU included.
Annual option: $590 billed yearly.
Hosted Monitors are separate: 3 capacity · daily minimum cadence. This calculator models API polling.
REST + MCP
Copy the captured request in curl, Python or TypeScript above. For an AI workflow, connect the GDELT Cloud MCP server and ask your client to use the same supported filters. Inspect the tool’s current schema before calling it; REST query names are not assumed to be MCP argument names.
Read the API and MCP documentationMORE WAYS TO BUILD