> ## 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. # Read a retained Situation brief > Edition-bound as-of explanation, salient Events and actors, supported relationships, time-step traversal, full-scope statistics, frozen citations, previews and detail links. New editions do not forecast. Structure adds typed graph nodes and edges; context adds source-gated existing context. No model calls occur during reads. Unavailable analysis remains explicit. ## OpenAPI ````yaml /api-reference/openapi-v2.json get /api/v2/situations/{story_id}/brief 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}/brief: get: tags: - Situations summary: Read a retained Situation brief description: >- Edition-bound as-of explanation, salient Events and actors, supported relationships, time-step traversal, full-scope statistics, frozen citations, previews and detail links. New editions do not forecast. Structure adds typed graph nodes and edges; context adds source-gated existing context. No model calls occur during reads. Unavailable analysis remains explicit. operationId: get-situation-brief-v2 parameters: - name: story_id in: path required: true schema: type: string description: >- A stored Situation UID (`sit_…`). Published as `story_id` for path compatibility with `/api/v2/situations/{story_id}`, which accepts either; the member lists accept only the UID — a Story id is refused. - name: edition_id in: query required: false schema: type: string description: >- Pin a retained edition. Mutually exclusive with 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. example: sed_0123456789abcdef0123456789abcdef - name: as_of in: query required: false schema: type: string description: >- 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. example: '2026-09-13T00:00:00Z' - name: level in: query required: false schema: type: string description: >- Progressive detail level: brief (default), structure, context. 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: brief responses: '200': description: Success content: application/json: schema: type: object properties: success: type: boolean data: $ref: '#/components/schemas/SituationBrief' examples: default: summary: Brief value: success: true data: {} '400': description: >- `INVALID_DATE_RANGE` — `date_start` is after `date_end`. `INVALID_DATE` — A date is not `YYYY-MM-DD`. `INVALID_SCOPE_VERSION` — A Situation page continuation supplied a malformed scope fingerprint. `INVALID_SITUATION_ID` — The Situation address is not a valid Story ID or Situation UID. '401': description: Missing or invalid API key '403': description: Plan does not include this surface '404': description: '`NOT_FOUND` — No record with that id.' '409': description: >- `SITUATION_SCOPE_CHANGED` — Situation membership changed between pages, so this continuation would mix snapshots. '429': description: Quota or rate limit exceeded '500': description: Server error security: - ApiKeyAuth: [] components: schemas: SituationBrief: type: object properties: title: type: string analysis: type: object properties: title: type: string framing: type: object properties: text: type: string evidence_ids: type: array items: type: string kind: type: string enum: - reporting - assessment required: - text - evidence_ids - kind assessment: type: object properties: text: type: string evidence_ids: type: array items: type: string kind: type: string enum: - reporting - assessment required: - text - evidence_ids - kind changes: type: array items: type: object properties: kind: type: string enum: - development - late_reporting - correction - membership claim: type: object properties: text: type: string evidence_ids: type: array items: type: string kind: type: string enum: - reporting - assessment required: - text - evidence_ids - kind required: - kind - claim threads: type: array items: type: object properties: id: type: string label: type: string role: type: string enum: - core - precursor - development - unresolved explanation: type: object properties: text: type: string evidence_ids: type: array items: type: string kind: type: string enum: - reporting - assessment required: - text - evidence_ids - kind story_ids: type: array items: type: string required: - id - label - role - explanation - story_ids players: type: array items: type: object properties: entity_id: type: string role: type: object properties: text: type: string evidence_ids: type: array items: type: string kind: type: string enum: - reporting - assessment required: - text - evidence_ids - kind required: - entity_id - role key_events: type: array items: type: object properties: event_id: type: string role: type: string enum: - turning_point - response - constraint - consequence - context explanation: type: object properties: text: type: string evidence_ids: type: array items: type: string kind: type: string enum: - reporting - assessment required: - text - evidence_ids - kind required: - event_id - role - explanation relationships: type: array items: type: object properties: source_id: type: string target_id: type: string relation: type: string basis: type: string enum: - recorded_participation - reporting_link - analytical_connection explanation: type: object properties: text: type: string evidence_ids: type: array items: type: string kind: type: string enum: - reporting - assessment required: - text - evidence_ids - kind required: - source_id - target_id - relation - basis - explanation time_steps: type: array items: type: object properties: date: type: string date_basis: type: string enum: - reporting - occurrence - mixed label: type: string explanation: type: object properties: text: type: string evidence_ids: type: array items: type: string kind: type: string enum: - reporting - assessment required: - text - evidence_ids - kind event_ids: type: array items: type: string story_ids: type: array items: type: string required: - date - label - explanation - event_ids - story_ids outlooks: type: array items: type: object properties: id: type: string claim: type: object properties: text: type: string evidence_ids: type: array items: type: string kind: type: string enum: - reporting - assessment required: - text - evidence_ids - kind mechanism: type: object properties: text: type: string evidence_ids: type: array items: type: string kind: type: string enum: - reporting - assessment required: - text - evidence_ids - kind counterevidence: type: array items: type: object properties: text: type: string evidence_ids: type: array items: type: string kind: type: string enum: - reporting - assessment required: - text - evidence_ids - kind horizon_days: oneOf: - type: number enum: - 7 - type: number enum: - 30 issued_at: type: string strengthens: type: array items: type: string description: >- Concrete future observations that make this specific outlook MORE plausible, with the direction explained. These are prospective tests, not evidence already observed and not statements about strengthening an actor. weakens: type: array items: type: string description: >- Concrete future observations that make this specific outlook LESS plausible, with the direction explained. Do not confuse weakening the outlook with harming one of its actors. Do not substitute thread IDs for observable tests. status: type: string enum: - unresolved - supported - contradicted - expired required: - id - claim - mechanism - counterevidence - horizon_days - issued_at - strengthens - weakens - status outlook_updates: type: array items: type: object properties: id: type: string status: type: string enum: - unresolved - supported - contradicted - expired assessment: type: object properties: text: type: string evidence_ids: type: array items: type: string kind: type: string enum: - reporting - assessment required: - text - evidence_ids - kind required: - id - status - assessment coherence: type: array items: type: object properties: story_ids: type: array items: type: string concern: type: object properties: text: type: string evidence_ids: type: array items: type: string kind: type: string enum: - reporting - assessment required: - text - evidence_ids - kind required: - story_ids - concern required: - title - framing - assessment - changes - threads - players - outlooks - outlook_updates - coherence nullable: true statistics: type: object additionalProperties: type: number metrics: type: object additionalProperties: {} nullable: true previews: type: object properties: stories: type: array items: type: object additionalProperties: {} events: type: array items: type: object additionalProperties: {} entities: type: array items: type: object additionalProperties: {} required: - stories - events - entities citations: type: array items: type: object properties: id: type: string excerpt: {} record: {} required: - id - excerpt - record graph: type: object properties: groups: type: array items: type: object properties: id: type: string label: type: string role: type: string story_ids: type: array items: type: string required: - id - label - role - story_ids nodes: type: array items: type: object properties: id: type: string kind: type: string enum: - story - event - entity record_id: type: string label: type: string group_id: type: string nullable: true date: type: string nullable: true importance: type: number roles: type: array items: type: string required: - id - kind - record_id - label - group_id - date - importance edges: type: array items: type: object properties: id: type: string source: type: string target: type: string relation: type: string basis: type: string enum: - reporting - recorded_participation - membership - analysis evidence_ids: type: array items: type: string required: - id - source - target - relation - basis - evidence_ids counts: type: object properties: stories: type: number events: type: number entities: type: number edges: type: number required: - stories - events - entities - edges required: - groups - nodes - edges - counts nullable: true stories: type: array items: type: object additionalProperties: {} events: type: array items: type: object additionalProperties: {} entities: type: array items: type: object additionalProperties: {} context: type: array items: type: object properties: id: type: string subject: type: string source: type: string observed_at: type: string nullable: true captured_at: type: string required_features: type: array items: type: string data: {} required: - id - subject - source - observed_at - captured_at - required_features - data context_coverage: type: string context_status: type: string enum: - available - restricted - not_captured required: - title - analysis - statistics - metrics - previews - citations securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: gdelt_sk_... description: 'GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`.' ````