> ## 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. # List Situations > Discover stored Situations by title, current servable span overlap and volume counts, or member-linked coded Event location/category. Event facets require a reporting window of at most 30 days and match the same Event; they do not establish a primary country or category. Directory filtering, ordering and totals use current full serving membership. scope and selected_scope distinguish whole-Situation counts from requested reporting dates and carry content versions. narrative is a dated, independently verified summary when one has been published; null means unavailable. Entity counts cover all current servable members and are null if measurement fails. ## OpenAPI ````yaml /api-reference/openapi-v2.json get /api/v2/situations 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: get: tags: - Situations summary: List Situations description: >- Discover stored Situations by title, current servable span overlap and volume counts, or member-linked coded Event location/category. Event facets require a reporting window of at most 30 days and match the same Event; they do not establish a primary country or category. Directory filtering, ordering and totals use current full serving membership. scope and selected_scope distinguish whole-Situation counts from requested reporting dates and carry content versions. narrative is a dated, independently verified summary when one has been published; null means unavailable. Entity counts cover all current servable members and are null if measurement fails. operationId: list-situations-v2 parameters: - name: entity in: query required: false schema: type: string description: >- Canonical entity handle or name, using the same identity resolution as Stories. Requires both reporting date bounds, at most 30 days. 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: Tesla - name: story_id in: query required: false schema: type: string description: >- Only Situations containing this currently served Story. 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: story_123 - name: event_uid in: query required: false schema: type: string description: >- Only Situations containing a served Story linked to this coded Event. 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: event_123 - name: include_map in: query required: false schema: type: boolean default: false description: >- Include country aggregates over every matching Situation, independently of page size. Requires a reporting window of at most 30 days. example: 'true' - name: date_start in: query required: false schema: type: string format: date description: >- Return Situations still running on or after this date (YYYY-MM-DD) — matched against `span_end`, so an occurrence that began earlier and is ongoing IS returned. Optional and independent of `date_end`. There is no maximum span: the Situations table is one row per adjudicated occurrence and is small by construction, so this is a filter on a stored column rather than a bound on how much is scanned. 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-26' - name: date_end in: query required: false schema: type: string format: date description: >- Return Situations that had already begun by this date (YYYY-MM-DD) — matched against `span_start`. Sent together with `date_start` the pair selects every occurrence whose span OVERLAPS the window; sent alone it leaves the other side open. An inverted pair is refused with `INVALID_DATE_RANGE` rather than answered empty. 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: search in: query required: false schema: type: string description: >- Free text matched against the stored `title` — a case-insensitive match requiring EVERY whitespace-separated term to appear somewhere in it, so `nepal flood` matches "Flash floods hit northern Nepal-Tibet border". What it CANNOT do, because there is nothing behind it to do it with: it does not read the member Stories, their article text or their entities; it is not semantic, so a synonym finds nothing; and `title` is the PEAK member's headline, re-stamped every time the Situation is recomputed — a term that matched yesterday can stop matching tomorrow without the occurrence changing. At most 8 terms; more is refused with `INVALID_SEARCH` rather than silently truncated. To search what a Situation is actually ABOUT, run `GET /api/v2/stories?search=` and take any returned Story id to `/api/v2/situations/{story_id}`. 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: nepal flood - name: min_stories in: query required: false schema: type: integer minimum: 0 maximum: 4294967295 description: >- Minimum member Stories across the whole current servable membership, not the selected reporting window. The public discovery page sends min_stories=2&min_events=2; the API applies no minimum when omitted. Use min_stories=1&min_events=0 to include emerging seeds. This filter does not change creation, growth or direct UID lookup. example: '5' - name: min_articles in: query required: false schema: type: integer minimum: 0 maximum: 4294967295 description: >- Minimum articles across the member Stories — the best single proxy for how big an occurrence got, and the default sort key. Compared against the stored `article_count`. example: '500' - name: min_events in: query required: false schema: type: integer minimum: 0 maximum: 4294967295 description: >- Minimum coded Events at canonical-incident grain across the whole current servable membership. The public discovery page sends min_stories=2&min_events=2; the API applies no minimum when omitted. Use min_stories=1&min_events=0 to include emerging seeds, including reporting with no coded Events. Explicit zero is permitted. example: '1' - name: sort in: query required: false schema: type: string enum: - article_count - story_count - event_count - recent - created - span_days default: recent description: >- Ranking. `recent` (default) uses latest reporting date, then first-observed membership time; `created` orders by immutable creation time, newest first; article_count, story_count and event_count are volume alternatives; `span_days` puts the longest-running occurrence first — the inclusive day count between `span.start` and `span.end`, with an unmeasured span last. Recent never uses refresh time or volume. Every order breaks ties on `situation_uid`, so paging with `offset` is stable. Full value list: https://docs.gdeltcloud.com/reference/enums#situation_sort example: recent - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 200 default: 25 description: >- Situations per page. Default 25, max 200. `pagination.total` is the true number matching your filters, counted separately from the page, so `has_more` is measured rather than inferred from a full page. 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: '25' - name: offset in: query required: false schema: type: integer minimum: 0 default: 0 description: >- Situations to skip. This endpoint pages by offset and has no cursor — every sort is a total order (ties break on `situation_uid`), so an offset walk cannot repeat or skip a row. example: '0' - name: country in: query required: false schema: type: string description: >- Any member-linked coded Event located in this ISO-3 country. Actor nationality is not used. Requires date_start and date_end, at most 30 inclusive days. Both country and category match the SAME Event. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#country example: NPL - name: category in: query required: false style: form explode: false schema: type: array items: type: string enum: - Battles - Protests - Riots - Explosions/Remote violence - Violence against civilians - Strategic developments - POLITICAL - CRIME - ECONOMIC - CORPORATE - TECHNOLOGY - INFRASTRUCTURE - ENVIRONMENT - HEALTH - DEMOGRAPHIC - INFORMATION description: >- Any member-linked coded Event in this Event taxonomy category, not Story category or a primary Situation label. Requires both reporting date bounds, at most 30 days. Country and category match the same Event. Full value list: https://docs.gdeltcloud.com/reference/enums#event_category example: ENVIRONMENT responses: '200': description: Success content: application/json: schema: type: object properties: success: type: boolean data: type: array items: $ref: '#/components/schemas/SituationSummaryCard' examples: default: summary: The biggest occurrences we hold 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. `INVALID_DATE_RANGE` — `date_start` is after `date_end`. `INVALID_DATE` — A date is not `YYYY-MM-DD`. `INVALID_COUNTRY` — A country value is not a recognised ISO-3 code, ISO-2 code or country name. `INVALID_SEARCH` — The free-text `search` term was refused before any query ran: it is too short to narrow anything (`/api/v2/stories` requires two characters), or it names more terms than the endpoint will conjoin (`/api/v2/situations` matches at most `details.max_terms`, since every term must appear in one stored title). '401': description: Missing or invalid API key '403': description: Plan does not include this surface '404': description: Not found '429': description: Quota or rate limit exceeded '500': description: Server error security: - ApiKeyAuth: [] components: schemas: SituationSummaryCard: type: object properties: created_at: type: string description: Immutable UTC creation time of this Situation, used by sort=created. category_summaries: type: array items: type: object properties: category: type: string event_count: type: number required: - category - event_count description: >- Distinct coded Events by category across the selected reporting membership. lifecycle: type: string enum: - active - archived 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 scope: 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_scope: 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 image_url: type: string nullable: true latest_development: type: object properties: story_id: type: string story_date: type: string title: type: string nullable: true precision: type: string enum: - day first_observed_at: type: string nullable: true required: - story_id - story_date - title nullable: true entity_count_status: type: string enum: - complete - unavailable entity_count_measured_at: type: string nullable: true description: >- When the full-membership entity read completed, independently of counts_updated_at. entity_scope: type: object properties: situation_uid: type: string member_count: type: number date_start: type: string nullable: true date_end: type: string nullable: true kind: type: string enum: - full_servable_membership version: type: string required: - situation_uid - member_count - date_start - date_end - kind nullable: true description: >- Current servable membership underlying entity_count; stored Story/Event/article snapshots may differ. situation_uid: type: string title: type: string policy_version: 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 span: type: object properties: start: type: string nullable: true end: type: string nullable: true required: - start - end totals: type: object properties: story_count: type: number article_count: type: number event_count: type: number unresolved_entity_count: type: number nullable: true description: >- Linked IDs without an available registry label; included in entity_count, not omitted. entity_count: type: number nullable: true description: >- Exact canonical linked entity count over full current servable membership; null when measurement failed. required: - story_count - article_count - event_count counts_updated_at: type: string nullable: true required: - situation_uid - title - policy_version - origin - peak - span - totals - counts_updated_at securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: gdelt_sk_... description: 'GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`.' ````