> ## 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 Story

> Fetch one known Story by ID with linked Events, linked Entities, metrics, public URL, normalized geo, and top 3 inline articles.



## OpenAPI

````yaml /api-reference/openapi-v2.json get /api/v2/stories/{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: Entities
    description: >-
      People & organizations — resolve a name to an entity, then fetch its
      profile and tone.
  - name: Geography
    description: Admin-1 geography lookups.
  - name: Energy
    description: Global Energy Monitor assets + ownership registry.
  - name: Facilities
    description: >-
      Unified physical-asset directory — GEM energy assets + World Port Index
      ports + Epoch AI data centers on one keyed surface, resolved to spine
      owners. Plan-gated (Analyst plan and up).
  - name: Screening and Reference
    description: >-
      Restricted-party lists, screening, and ownership-chain exposure.
      Plan-gated (`can_use_screening` / `can_use_exposure`).
  - name: China
    description: >-
      China overseas development finance (AidData GCDF). Plan-gated
      (`can_use_china`).
  - name: Media Intelligence
    description: >-
      Entity tone (`can_use_tone`) and Share of Voice (`can_use_share_of_voice`)
      are plan-gated. Social signal remains an admin-only preview.
  - name: Filings
    description: >-
      SEC EDGAR filings, XBRL financials, and AI-extracted relations. Requires a
      plan with SEC filings access (`can_use_filings`) — the Corporate & Supply
      Chain plan and above.
  - name: Macro Finance
    description: >-
      FRED economic time series (catalog, point-in-time observations, releases).
      Plan-gated (`can_use_macro`).
  - name: Maritime
    description: >-
      AIS-derived vessel-flow signals across maritime chokepoints — chokepoint
      transits, last-known vessel positions, carriers, dwell, and AIS-dark gaps.
      Plan-gated (`can_use_maritime`).
  - name: Briefs
    description: Source-backed monitoring briefs.
paths:
  /api/v2/stories/{story_id}:
    get:
      tags:
        - Stories
      summary: Get Story
      description: >-
        Fetch one known Story by ID with linked Events, linked Entities,
        metrics, public URL, normalized geo, and top 3 inline articles.
      operationId: get-story-v2
      parameters:
        - name: story_id
          in: path
          required: true
          description: Story ID returned by Search Stories or linked from an Event.
          schema:
            type: string
      responses:
        '200':
          description: Story detail
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/StoryCard'
              examples:
                story:
                  value:
                    success: true
                    data:
                      id: story_123
                      url: https://gdeltcloud.com/story/example-story
                      title: Data center projects in Asia
                      story_date: '2026-04-15'
                      category: infrastructure
                      subcategory: null
                      geo:
                        country: Japan
                        region: Eastern Asia
                        continent: Asia
                        admin1: Tokyo
                        location: Tokyo
                        latitude: 35.6762
                        longitude: 139.6503
                      metrics:
                        significance: 0.82
                        article_count: 12
                        linked_event_count: 2
                        max_linked_event_significance: 0.71
                      has_events: true
                      has_fatalities: false
                      fatalities: 0
                      linked_events:
                        - id: cameoplus_abc123
                          title: Infrastructure investment announced
                      entity_refs: []
                      top_articles:
                        - url: https://www.example.com/data-center
                          title: New data center project announced
                          domain: example.com
                          rank: 1
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl "https://gdeltcloud.com/api/v2/stories/story_123" \
              -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
components:
  schemas:
    StoryCard:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
          nullable: true
        title:
          type: string
          nullable: true
        image_url:
          type: string
          format: uri
          nullable: true
          description: >-
            First available top-article sharing image promoted to the Story
            card.
        story_date:
          type: string
          format: date
        category:
          type: string
          nullable: true
        subcategory:
          type: string
          nullable: true
        geo:
          $ref: '#/components/schemas/Geo'
        geo_context:
          $ref: '#/components/schemas/GeoContext'
        metrics:
          type: object
          properties:
            significance:
              type: number
            article_count:
              type: integer
            linked_event_count:
              type: integer
            max_linked_event_significance:
              type: number
            civilian_targeting_event_count:
              type: integer
              description: Number of linked Events with ACLED civilian_targeting populated.
        has_events:
          type: boolean
        has_fatalities:
          type: boolean
        fatalities:
          type: integer
        linked_events:
          type: array
          items:
            type: object
        entity_refs:
          type: array
          items:
            $ref: '#/components/schemas/EntityRef'
        top_articles:
          type: array
          maxItems: 3
          items:
            $ref: '#/components/schemas/Article'
        has_civilian_targeting:
          type: boolean
          description: >-
            True when linked Conflict Events include civilian targeting
            evidence.
    Geo:
      type: object
      properties:
        country:
          type: string
          nullable: true
        region:
          type: string
          nullable: true
        continent:
          type: string
          nullable: true
        admin1:
          type: string
          nullable: true
        location:
          type: string
          nullable: true
        latitude:
          type: number
          nullable: true
        longitude:
          type: number
          nullable: true
    GeoContext:
      type: object
      description: >-
        Explains broad geography matches. geo is the event/story location;
        actor_origin_countries explains matches where the requested country,
        region, or continent came from actor origin instead.
      properties:
        location_country:
          type: string
          nullable: true
        actor_origin_countries:
          type: array
          items:
            type: string
    EntityRef:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          nullable: true
        wikipedia_url:
          type: string
          format: uri
          nullable: true
        image_url:
          type: string
          format: uri
          nullable: true
          description: Best-effort Wikipedia thumbnail URL for UI rendering.
        avatar_url:
          type: string
          format: uri
          nullable: true
          description: Best-effort compact avatar URL, usually the same as image_url.
    Article:
      type: object
      properties:
        id:
          type: string
          nullable: true
        url:
          type: string
          format: uri
        title:
          type: string
          nullable: true
        domain:
          type: string
          nullable: true
        domain_avatar_url:
          type: string
          format: uri
          nullable: true
          description: Best-effort source-domain avatar/favicon URL for UI rendering.
        image_url:
          type: string
          format: uri
          nullable: true
          description: Best-effort source article sharing image from the GDELT GKG layer.
        article_date:
          type: string
          format: date
          nullable: true
        rank:
          type: integer
          nullable: true
        role:
          type: string
          nullable: true
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: string
        code:
          type: string
        details:
          type: object
          description: >-
            Recoverable validation context when available, such as param,
            invalid_value, accepted_values, nearest_values, and a corrected
            example.
          additionalProperties: true
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: gdelt_sk_...
      description: 'GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`.'

````