curl --request GET \
--url https://gdeltcloud.com/api/v2/situations/{story_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://gdeltcloud.com/api/v2/situations/{story_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://gdeltcloud.com/api/v2/situations/{story_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"data": {}
}Get a Situation
Every Story and Event belonging to one real-world occurrence. The path accepts EITHER a situation_uid (sit_…) or any member Story id, and both return the same occurrence — a Story resolves to its primary Situation. A situation_uid is minted and content-independent, so it never changes; a Situation that merges into another resolves FORWARD to the survivor rather than 404ing. meta.situation_source says which you got: curated is the stored, adjudicated membership set, and walked is the adjudicated neighbourhood around a Story that no Situation covers yet — the same shape, a weaker claim. Stored members carry route; antecedent and consequence are chronological, not proof of causality. membership reports the basis and any recorded decision reason; missing evidence stays null. origin is the earliest member carrying material coverage and peak the largest; both are derived and recomputed, and neither is the identity. Membership is not exclusive — a Story may belong to more than one Situation. Returns the member Stories (paged, with the relation and the evidence arm that produced each link), a per-day rollup of how the occurrence built up, and its Events collapsed to one row per canonical incident. How Stories adjudicated as the SAME incident are reported DIFFERS BY PATH, so read meta.situation_source first. On a walked situation they are folded out of the member list and listed under duplicates; on a curated one they are admitted as MEMBERS carrying route same_incident, duplicates is empty by construction, and how many there are is totals.story_count minus totals.distinct_incident_count. Either way, if the Story you asked for was the folded side, the situation is served from its survivor and requested_story_id names what you sent. Members and Events resolve through the same settled tables /api/v2/stories and /api/v2/events read, so a situation can never name a record those endpoints will not return. incident_relations publishes only independently adjudicated, directional umbrella/component links; it never changes Event identity or event_count, and null confirmed counts mean relation publication is unavailable or incomplete for the returned Event dates rather than zero. The Situation graph hides confirmed umbrella summaries by default and lets the reader reveal both summaries and containment edges. Curated responses include scopes.whole and scopes.selected, each with a content version and full totals independent of graph limits. narrative, when present, is independently verified and dated; current=false retains a previous publication while a refresh is pending. The incident_adjudication split describes returned incident rows, not unseen Events. Fatalities are reported as both a maximum and a raw sum, and the incident count ships with its adjudication split, because most Events have never been compared to anything. Three arrays are bounded — member Stories, incidents and the entity cast — and caps reports each ceiling and whether it bit, so nothing here is capped in silence.
curl --request GET \
--url https://gdeltcloud.com/api/v2/situations/{story_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://gdeltcloud.com/api/v2/situations/{story_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://gdeltcloud.com/api/v2/situations/{story_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"data": {}
}Authorizations
GDELT Cloud API key. Send as Authorization: Bearer gdelt_sk_....
Path Parameters
A situation_uid (sit_…) or any member Story id; both resolve to the same occurrence.
Query Parameters
Retained edition identifier from get_situation_editions. Pins the published snapshot; use it instead of as_of. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Latest edition published at or before this UTC ISO timestamp. No reconstruction before retention began. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Earliest member date to include. Defaults to seven days before the anchor Story's own date — not to today, because a situation is anchored on a Story, not on the request clock. On a curated Situation it filters the stored membership and coverage is re-derived from the members that survived, so the window reported is never wider than the payload. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Latest member date to include. Defaults to seven days after the anchor Story's own date. The span may not exceed 30 days when both bounds are sent — the same ceiling the service compares against, not a number typed into a sentence. On a curated Situation, sending neither bound returns the whole stored span; sending one leaves the other side open. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Number of records to return on this page; pagination describes how to continue. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
1 <= x <= 200Number of adjudicated connection hops from the anchor in a walked Situation. Indirect reachability is not direct comparison with the anchor. Curated membership ignores this value and discloses that in applied_filters.
1 <= x <= 3Member Story cap for the Situation graph, independent of page size. Read truncated and caps.members; the limit can bound membership totals.
1 <= x <= 250Optional blocks. edges returns one undirected row per adjudicated pair across the bounded graph membership, independently of Story pagination (limit and offset). An edge can reference a Story outside the returned page; fetch the member pages to hydrate those IDs and inspect caps and scopes for coverage. /connections pages membership provenance, not pairwise edges. Edges are omitted by default; totals.edge_count reports all pairs in the selected scope even when the returned graph is capped. Full value list: https://docs.gdeltcloud.com/reference/enums#situation_include
edges Number of records to skip before this page.
x >= 0