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. 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.
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
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.
How many member Stories to return. The per-day rollup, the incidents and every total always describe the WHOLE situation, so a small page never shrinks the numbers. 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 <= 200How many adjudicated hops out from the anchor to walk. depth=1 returns only Stories a judge compared with the anchor DIRECTLY. Higher values reach further across time — no link in the source spans more than two days, so a week is depth, not distance — but a Story at hop 2 or 3 was never compared with the anchor itself: it was reached along a path of individually adjudicated edges, which edges and each Story's hop and via_story_id make explicit. Treat depth > 1 as reachability, not membership. NOT APPLICABLE on a curated Situation, whose membership was adjudicated rather than traversed: there is no frontier, so the value appears under applied_filters.ignored beside meta.situation_source: "curated" rather than being echoed back as honoured.
1 <= x <= 3Ceiling on member Stories. On a walked situation it bounds the frontier, ordered largest-first so a cut is reproducible rather than dependent on row order. On a curated one it bounds the membership read, taking them in the order stories is served in — earliest date first, largest within a date — so the cut is the head of the list you would have paged through rather than an arbitrary slice. truncated and caps.members say whether it bit, both measured. It is a FILTER, not a page size: the totals describe the members it admitted, while limit pages those members without changing any number.
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 Member Stories to skip. The member list is ordered by date then article count.
x >= 0