> ## Documentation Index > Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /api-reference/openapi-v2.json get /api/v2/situations/{story_id} openapi: 3.0.3 info: title: GDELT Cloud API v2 version: 2.0.0 description: >- Clean v2 REST API for generated GDELT Cloud structured Events, clustered Stories, linked Entities, summaries, admin1 discovery, significance ranking, and paginated article evidence. Event significance is a family-scoped weighted blend, renormalized so every event family spans a true 0-1: each event's raw total is divided by the maximum its own family can reach (Conflict 1.00, CAMEO+ POLITICAL 0.90, other CAMEO+ domains 0.65). All events: Goldstein severity 0.25, article evidence 0.05, confidence 0.05. Conflict only: fatalities 0.55 (log-scaled by body count) and civilian targeting 0.10. CAMEO+ only: magnitude 0.20, systemic importance 0.15, propagation potential 0.10, market sensitivity 0.10. When magnitude is unmeasured its term AND its 0.20 weight are both dropped. The four CAMEO+ metrics are rubric scores produced by published formulas - ordinal ranking signals, not measurements, probabilities, or predicted price moves. goldstein_scale is one canonical public metric, populated for Conflict Events and CAMEO+ POLITICAL Events where meaningful. Story linked_event_count is a Story-to-Event link aggregate, not a distinct Event total. servers: - url: https://gdeltcloud.com description: Production - url: http://localhost:3000 description: Local development security: - ApiKeyAuth: [] tags: - name: Events description: Coded CAMEO+ / conflict events — search, fetch, and summarize. - name: Stories description: Clustered narratives (stories) and their articles. - name: Situations description: >- One real-world occurrence as the Stories and coded Events that belong to it — stored, adjudicated membership (`meta.situation_source: curated`) or a walked neighbourhood around a Story. Discovery, detail, four independently paged member lists, and the only write on the core surface (5 QU with an Idempotency-Key). - name: Entities description: >- People & organizations — resolve a name to an entity, then fetch its profile and tone. Also the publication activity journal (/api/v2/activity): observed evidence of what was published about identities and records — committed batches only, cursor-paged, never source intake. - name: Unified Search description: >- One fuzzy lookup across every id-space — start here with a name, take the entity id, then reuse it on every other surface. This is the resolver the rest of the API assumes you called first. - name: Media Intelligence description: >- Press-coverage tone over time and share of voice against a peer set. Requires the `can_use_tone` / `can_use_share_of_voice` entitlement; social signal is an admin-only preview. - name: Facilities description: >- Unified physical-asset directory — GEM energy assets, World Port Index ports and Epoch AI data centers on one keyed surface, resolved to spine owners. Requires the `can_use_facilities` entitlement. - name: Monitors description: >- Organization-shared scheduled checks over the Core API, with email and signed-webhook delivery. Monitor execution does not consume query units. - name: Geography description: >- Country context and admin-1 geography: /api/v2/countries (publication activity, reporting counts, dated economic and resource fundamentals, facility and office inventories, directory mode over every registered country) and admin-1 lookups. - name: Government description: >- US federal awards (USAspending) and foreign-influence registrations (DOJ NSD FARA), resolved onto the entity spine. Requires the `can_use_gov` entitlement. - name: Political Offices description: >- Public political offices and who holds them — legislatures, cabinets, heads of state, courts and IGO posts, with the office start/end dates the publisher states (valid time), resolved onto the entity spine. Actor context for geopolitical analysis; NOT a PEP or sanctions-screening tool. Requires the `can_use_offices` entitlement. - name: Filings description: >- SEC EDGAR filings, XBRL financials, and relations extracted from filing text. Requires the `can_use_filings` entitlement. - name: Reference Data description: >- The GLEIF Global LEI Index — legal-entity reference data, consolidation relationships, and LEI↔ISIN mappings. Requires the `can_use_gleif` entitlement. - name: Energy description: Global Energy Monitor assets + ownership registry. - name: AI Compute description: >- Epoch AI datasets — models, hardware, data centers, companies and chip sales. Requires the `can_use_epoch_ai` entitlement. - name: Macro Finance description: >- FRED economic time series — catalog, point-in-time observations and releases. Requires the `can_use_macro` entitlement. - name: Screening and Reference description: >- Restricted-party lists, name screening and ownership-chain exposure. Requires the `can_use_screening` / `can_use_exposure` entitlement. Analytical coverage, not an audit-grade compliance control. - name: China description: >- China overseas development finance (AidData GCDF). Requires the `can_use_china` entitlement. - name: Maritime description: >- AIS-derived vessel flow — chokepoint transits, last-known vessel positions, carriers, dwell and AIS-dark gaps. Terrestrial AIS only, so coverage thins in open ocean. Requires the `can_use_maritime` entitlement. - name: Atlas Intelligence description: >- Geopolitical-risk and posture indices computed from GDELT Cloud’s own coded events, normalized to each place’s own frozen baseline. - name: Briefs description: Source-backed monitoring briefs. - name: Meta description: >- Machine-readable discovery: the value vocabularies, the endpoint contracts, and the query-unit cost model. Unmetered, so a client can check before it spends. paths: /api/v2/situations/{story_id}: get: tags: - Situations summary: Get a Situation description: >- 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. operationId: get-situation-v2 parameters: - name: story_id in: path required: true schema: type: string description: >- A `situation_uid` (`sit_…`) or any member Story id; both resolve to the same occurrence. - name: date_start in: query required: false schema: type: string format: date description: >- 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. example: '2026-08-24' - name: date_end in: query required: false schema: type: string format: date description: >- 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. example: '2026-08-29' - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 200 default: 50 description: >- 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. example: '50' - name: depth in: query required: false schema: type: integer minimum: 1 maximum: 3 default: 1 description: >- How 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. example: '1' - name: max_nodes in: query required: false schema: type: integer minimum: 1 maximum: 250 default: 250 description: >- Ceiling 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. example: '250' - name: include in: query required: false style: form explode: false schema: type: array items: type: string enum: - edges description: >- Optional 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 example: edges - name: offset in: query required: false schema: type: integer minimum: 0 default: 0 description: >- Member Stories to skip. The member list is ordered by date then article count. example: '0' responses: '200': description: Success content: application/json: schema: type: object properties: success: type: boolean data: $ref: '#/components/schemas/SituationCard' examples: default: summary: The occurrence around a Story value: success: true data: {} '400': description: >- `INVALID_WINDOW` — The `date_start` / `date_end` span on a Situation is inverted, longer than this endpoint will walk, or — on `/api/v2/situations` — a `country`, `category` or `entity` facet was sent without BOTH reporting bounds. The dates that are present are well-formed; the WINDOW is what is refused. '401': description: Missing or invalid API key '403': description: Plan does not include this surface '404': description: >- `SITUATION_NOT_FOUND` — A `sit_…` id that was never minted. Note that this is NOT what a superseded Situation answers — a Situation that merges into another resolves FORWARD to its survivor and returns it. `STORY_NOT_FOUND` — The path named a Story with no settled row on any date, so there is no situation to assemble around it. Different from a Story that simply has no neighbours — that is an empty situation at HTTP 200. '429': description: Quota or rate limit exceeded '500': description: Server error security: - ApiKeyAuth: [] components: schemas: SituationCard: type: object properties: narrative: type: object properties: method: type: string enum: - extractive - synthesized version: type: string policy_version: type: string published_at: type: string current: type: boolean background: type: array items: type: object properties: text: type: string story_ids: type: array items: type: string required: - text - story_ids what_changed: type: array items: type: object properties: text: type: string story_ids: type: array items: type: string required: - text - story_ids evidence: type: array items: type: object properties: story_id: type: string story_date: type: string title: type: string article_count: type: number route: type: string source_headlines: type: array items: type: string required: - story_id - story_date - title - article_count - route evidence_member_count: type: number whole_member_count: type: number verification: type: object properties: status: type: string enum: - independently_verified model: type: string required: - status - model required: - method - version - policy_version - published_at - current - background - what_changed - evidence - evidence_member_count - whole_member_count - verification nullable: true scopes: type: object properties: whole: type: object properties: version: type: string description: >- Content fingerprint over full served membership and linked Event fatality facts; unchanged re-settles keep this version. date_start: type: string nullable: true date_end: type: string nullable: true serving_updated_at: type: string nullable: true totals: type: object properties: story_count: type: number article_count: type: number event_count: type: number description: >- Unique canonical coded Events linked to served member Stories in this scope, independent of pagination and graph limits. This Event-grain total is separate from the legacy Story-grain distinct_incident_count. distinct_incident_count: type: number description: >- Legacy name: counts member Stories whose membership route is not same_incident, not coded Events. story_count minus this value counts member Stories admitted as retellings. This Story-grain count may exceed event_count or incident_count; do not compare it with an Event total. fatalities_reported_max: type: number nullable: true fatalities_raw_sum: type: number nullable: true incidents_carrying_fatalities: type: number required: - story_count - article_count - event_count - distinct_incident_count - fatalities_reported_max - fatalities_raw_sum - incidents_carrying_fatalities required: - version - date_start - date_end - serving_updated_at - totals selected: type: object properties: version: type: string description: >- Content fingerprint over full served membership and linked Event fatality facts; unchanged re-settles keep this version. date_start: type: string nullable: true date_end: type: string nullable: true serving_updated_at: type: string nullable: true totals: type: object properties: story_count: type: number article_count: type: number event_count: type: number description: >- Unique canonical coded Events linked to served member Stories in this scope, independent of pagination and graph limits. This Event-grain total is separate from the legacy Story-grain distinct_incident_count. distinct_incident_count: type: number description: >- Legacy name: counts member Stories whose membership route is not same_incident, not coded Events. story_count minus this value counts member Stories admitted as retellings. This Story-grain count may exceed event_count or incident_count; do not compare it with an Event total. fatalities_reported_max: type: number nullable: true fatalities_raw_sum: type: number nullable: true incidents_carrying_fatalities: type: number required: - story_count - article_count - event_count - distinct_incident_count - fatalities_reported_max - fatalities_raw_sum - incidents_carrying_fatalities required: - version - date_start - date_end - serving_updated_at - totals filtered: type: boolean required: - whole - selected - filtered description: >- Whole Situation and selected reporting-window totals, independent of graph and page limits. situation_uid: type: string title: type: string origin: type: object properties: story_id: type: string story_date: type: string nullable: true required: - story_id - story_date peak: type: object properties: story_id: type: string story_date: type: string nullable: true required: - story_id - story_date anchor: type: object properties: story_id: type: string story_date: type: string title: type: string nullable: true article_count: type: number required: - story_id - story_date - title - article_count requested_story_id: type: string nullable: true canonical_anchor: type: object properties: story_id: type: string story_date: type: string title: type: string nullable: true required: - story_id - story_date - title nullable: true coverage: type: object properties: start: type: string end: type: string required: - start - end depth: type: number truncated: type: boolean edges: type: array items: type: object properties: from_story_id: type: string from_story_date: type: string to_story_id: type: string to_story_date: type: string relation: type: string enum: - same_day - continuation - duplicate edge_source: type: string confidence: type: number distance: type: number required: - from_story_id - from_story_date - to_story_id - to_story_date - relation - edge_source - confidence - distance stories: type: array items: type: object properties: story_id: type: string story_date: type: string relation: type: string enum: - precursor - same_day - continuation edge_source: type: string confidence: type: number distance: type: number hop: type: number title: type: string nullable: true article_count: type: number significance: type: number nullable: true category: type: string nullable: true country: type: string nullable: true linked_event_count: type: number nullable: true facts_status: type: string enum: - available - unavailable membership: type: object properties: basis: type: string enum: - seed - stored_membership - pairwise_path route: type: string nullable: true route_basis: type: string enum: - seed - chronology - same_incident_decision - pairwise_chronology reason: type: string nullable: true evidence_status: type: string enum: - decision_available - not_recorded - not_loaded - pairwise_only decision: type: object properties: verdict: type: string policy_version: type: string decided_at: type: string required: - verdict - policy_version - decided_at nullable: true via: type: object properties: kind: type: string enum: - story - situation id: type: string required: - kind - id nullable: true required: - basis - route - route_basis - reason - evidence_status - decision - via served_in_list: type: boolean via_story_id: type: string nullable: true route: type: string image_url: type: string nullable: true required: - story_id - story_date - relation - edge_source - confidence - distance - hop - title - article_count - significance - category - country - linked_event_count - served_in_list - via_story_id by_date: type: array items: type: object properties: date: type: string story_count: type: number article_count: type: number incident_count: type: number required: - date - story_count - article_count - incident_count incidents: type: array items: type: object properties: event_uid: type: string occurred_on: type: string title: type: string nullable: true category: type: string nullable: true subcategory: type: string nullable: true event_family: type: string nullable: true country_iso3: type: string nullable: true source_actor_country_iso3: type: string nullable: true target_actor_country_iso3: type: string nullable: true admin1: type: string nullable: true latitude: type: number nullable: true longitude: type: number nullable: true significance: type: number nullable: true fatalities: type: number nullable: true civilian_targeting: type: boolean nullable: true story_ids: type: array items: type: string taxonomy_status: type: string enum: - coded - detail_missing - undeclared_code nullable: true event_code: type: string nullable: true event_root_code: type: string nullable: true event_description: type: string nullable: true source_actor: type: string nullable: true target_actor: type: string nullable: true source_actor_country: type: string nullable: true target_actor_country: type: string nullable: true source_actor_entity_id: type: string nullable: true source_actor_id_space: type: string nullable: true target_actor_entity_id: type: string nullable: true target_actor_id_space: type: string nullable: true goldstein_scale: type: number nullable: true quad_class: type: string nullable: true magnitude: type: number nullable: true systemic_importance: type: number nullable: true propagation_potential: type: number nullable: true market_sensitivity: type: number nullable: true confidence: type: number nullable: true civilian_targeting_label: type: string nullable: true fatalities_basis: type: string enum: - reported_exact - reported_minimum - reported_range - estimated - none_reported nullable: true injured: type: number nullable: true civilians_killed: type: number nullable: true civilians_injured: type: number nullable: true language_breakdown: type: array items: type: object properties: language: type: string count: type: number required: - language - count top_language: type: string nullable: true incident_resolution: type: string required: - event_uid - occurred_on - title - category - subcategory - event_family - country_iso3 - source_actor_country_iso3 - target_actor_country_iso3 - admin1 - latitude - longitude - significance - fatalities - civilian_targeting - story_ids - taxonomy_status - event_code - event_root_code - event_description - source_actor - target_actor - source_actor_country - target_actor_country - source_actor_entity_id - source_actor_id_space - target_actor_entity_id - target_actor_id_space - goldstein_scale - quad_class - magnitude - systemic_importance - propagation_potential - market_sensitivity - confidence - civilian_targeting_label - fatalities_basis - injured - civilians_killed - civilians_injured - language_breakdown - top_language - incident_resolution duplicates: type: object properties: collapsed: type: number article_count: type: number stories: type: array items: type: object properties: story_id: type: string story_date: type: string title: type: string nullable: true article_count: type: number required: - story_id - story_date - title - article_count required: - collapsed - article_count - stories totals: type: object properties: story_count: type: number article_count: type: number edge_count: type: number incident_count: type: number description: >- Unique canonical coded Events linked to served member Stories in this scope, independent of pagination and graph limits. This Event-grain total is separate from the legacy Story-grain distinct_incident_count. distinct_incident_count: type: number description: >- Legacy name: counts member Stories whose membership route is not same_incident, not coded Events. story_count minus this value counts member Stories admitted as retellings. This Story-grain count may exceed event_count or incident_count; do not compare it with an Event total. fatalities_reported_max: type: number nullable: true fatalities_raw_sum: type: number nullable: true incidents_carrying_fatalities: type: number required: - story_count - article_count - edge_count - incident_count - distinct_incident_count - fatalities_reported_max - fatalities_raw_sum - incidents_carrying_fatalities caps: type: object properties: members: type: object properties: limit: type: number returned: type: number truncated: type: boolean total_available: type: number required: - limit - returned - truncated incidents: type: object properties: limit: type: number returned: type: number truncated: type: boolean required: - limit - returned - truncated entities: type: object properties: limit: type: number rolled_up: type: number returned: type: number truncated: type: boolean required: - limit - rolled_up - returned - truncated required: - members - incidents - entities applied_filters: type: object properties: date_start: type: string date_end: type: string depth: type: number max_nodes: type: number include: type: array items: type: string ignored: type: object additionalProperties: type: string required: - max_nodes - ignored incident_adjudication: type: object properties: unadjudicated: type: number self: type: number llm: type: number required: - unadjudicated - self - llm entities: type: array items: type: object properties: entity_id: type: string display_name: type: string entity_type: type: string nullable: true wikidata_qid: type: string nullable: true story_count: type: number mention_count: type: number article_count: type: number story_ids: type: array items: type: string first_seen: type: string last_seen: type: string required: - entity_id - display_name - entity_type - wikidata_qid - story_count - mention_count - article_count - story_ids - first_seen - last_seen composition: type: object properties: categories: type: array items: type: object properties: key: type: string incident_count: type: number story_count: type: number required: - key - incident_count - story_count subcategories: type: array items: type: object properties: key: type: string category: type: string nullable: true incident_count: type: number required: - key - category - incident_count countries: type: array items: type: object properties: iso3: type: string incident_count: type: number story_count: type: number required: - iso3 - incident_count - story_count required: - categories - subcategories - countries required: - anchor - requested_story_id - canonical_anchor - coverage - depth - truncated - stories - by_date - incidents - duplicates - totals - caps - applied_filters - incident_adjudication - entities - composition securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: gdelt_sk_... description: 'GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`.' ````