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

# Search Stories

> Search clustered Stories for narrative and article evidence with broad result coverage by default. Story cards include linked Events, linked Entities, normalized geo, metrics, public URLs, and top 3 inline articles. Use category/subcategory to filter by linked Event taxonomy.



## OpenAPI

````yaml /api-reference/openapi-v2.json get /api/v2/stories
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:
    get:
      tags:
        - Stories
      summary: Search Stories
      description: >-
        Search clustered Stories for narrative and article evidence with broad
        result coverage by default. Story cards include linked Events, linked
        Entities, normalized geo, metrics, public URLs, and top 3 inline
        articles. Use category/subcategory to filter by linked Event taxonomy.
      operationId: search-stories-v2
      parameters:
        - $ref: '#/components/parameters/dateStart'
        - $ref: '#/components/parameters/dateEnd'
        - $ref: '#/components/parameters/country'
        - $ref: '#/components/parameters/region'
        - $ref: '#/components/parameters/continent'
        - $ref: '#/components/parameters/admin1'
        - name: bbox
          in: query
          required: false
          schema:
            type: string
          description: >-
            Bounding box `lat_min,lon_min,lat_max,lon_max`. Keeps stories with
            AT LEAST ONE linked event inside the box — the same linked-event
            geography semantics as `country`/`admin1`. Note the returned
            `linked_event_count` / fatalities stay FULL-story aggregates, not
            box-restricted. Malformed or out-of-range values return 400
            INVALID_BBOX.
          example: 24,49,30,57
        - $ref: '#/components/parameters/category'
        - $ref: '#/components/parameters/storyCategory'
        - $ref: '#/components/parameters/eventCategory'
        - $ref: '#/components/parameters/subcategory'
        - $ref: '#/components/parameters/domain'
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/hasEvents'
        - $ref: '#/components/parameters/hasFatalities'
        - $ref: '#/components/parameters/civilianTargeting'
        - $ref: '#/components/parameters/articleCountMin'
        - $ref: '#/components/parameters/articleCountMax'
        - $ref: '#/components/parameters/languages'
        - $ref: '#/components/parameters/includeImages'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: Story cards
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/StoryCard'
                      sort:
                        $ref: '#/components/schemas/Sort'
              examples:
                stories:
                  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
                    pagination:
                      limit: 25
                      cursor: null
                      next_cursor: eyJvZmZzZXQiOjI1fQ==
                    sort: significance
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl "https://gdeltcloud.com/api/v2/stories" \
              -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
components:
  parameters:
    dateStart:
      name: date_start
      in: query
      description: >-
        Inclusive start date in YYYY-MM-DD, matched against the event or story
        date. Alias `start_date` is accepted for compatibility. Omit dates for
        the default recent window; explicit windows may not exceed 30 days.
      schema:
        type: string
        format: date
        example: '2026-04-11'
      example: '2026-04-11'
    dateEnd:
      name: date_end
      in: query
      description: >-
        Inclusive end date in YYYY-MM-DD, matched against the event or story
        date. Alias `end_date` is accepted for compatibility. Omit dates for the
        default recent window; explicit windows may not exceed 30 days.
      schema:
        type: string
        format: date
        example: '2026-04-17'
      example: '2026-04-17'
    country:
      name: country
      in: query
      description: >-
        Country filter, resolved through the shared `resolveCountryInput` layer
        so a plain English country name (`United States`), an ISO-2 code (`US`),
        an ISO-3 code (`USA`), or a common alias (`UK`, `UAE`, `Czechia`) all
        work interchangeably; output normalizes to the country name. Accepts a
        comma-separated list (any part unresolvable → `400 INVALID_COUNTRY`),
        and can be combined with `region`/`continent`.
      schema:
        type: string
        example: Lebanon
      example: Lebanon
    region:
      name: region
      in: query
      description: >-
        Plain English region such as `Middle East`, `Western Africa`, `South
        Asia`, or `Europe`. The backend expands this value to an ISO-3 country
        list; Events match location and actor-origin countries, while Stories
        match linked Event primary location.
      schema:
        type: string
        example: Middle East
        enum:
          - Africa
          - Asia
          - Middle East
          - Northern Africa
          - Western Africa
          - Eastern Africa
          - Middle Africa
          - Southern Africa
          - Europe
          - Eastern Europe
          - South Asia
          - Southeast Asia
          - East Asia
          - Central Asia
          - North America
          - Central America
          - Caribbean
          - South America
          - Oceania
      example: Middle East
    continent:
      name: continent
      in: query
      description: >-
        Plain English continent such as `Africa`, `Asia`, `Europe`, `North
        America`, `South America`, or `Oceania`. The backend expands this value
        to an ISO-3 country list; Events match location and actor-origin
        countries, while Stories match linked Event primary location.
      schema:
        type: string
        example: Africa
        enum:
          - Africa
          - Asia
          - Europe
          - North America
          - South America
          - Oceania
      example: Africa
    admin1:
      name: admin1
      in: query
      description: >-
        Optional state/province/admin1 location filter. Discover valid values
        through `/api/v2/geo/admin1`. Filters Event or Story location only, not
        actor origin.
      schema:
        type: string
        example: Beirut
      example: Beirut
    category:
      name: category
      in: query
      description: >-
        Stable linked Event product category. Use a Conflict event type such as
        `Battles`, `Protests`, or `Explosions/Remote violence`, or one CAMEO+
        domain such as `POLITICAL`, `INFRASTRUCTURE`, or `CRIME`; values may be
        single or comma-separated. On Story endpoints this filters linked Event
        evidence. Use `story_category` only for legacy Story-cluster categories
        such as `conflict_security`. Full list: [Taxonomy &
        Codes](/api-reference/taxonomy).
      schema:
        type: string
        example: Battles
      example: Battles
    storyCategory:
      name: story_category
      in: query
      required: false
      schema:
        type: string
        example: conflict_security
        enum:
          - conflict_security
          - cameoplus_political
          - cameoplus_crime
          - cameoplus_economic
          - cameoplus_corporate
          - cameoplus_technology
          - cameoplus_infrastructure
          - cameoplus_environment
          - cameoplus_health
          - cameoplus_demographic
          - cameoplus_information
      description: >-
        Legacy Story-cluster category filter such as `conflict_security` or
        `cameoplus_infrastructure`. Prefer linked Event `category`/`subcategory`
        for product taxonomy filtering.
    eventCategory:
      name: event_category
      in: query
      required: false
      deprecated: true
      schema:
        type: string
      description: >-
        Deprecated alias for `category` on Story endpoints. Prefer
        `category=Battles` or a CAMEO+ domain such as `category=CRIME`. Full
        list: [Taxonomy & Codes](/api-reference/taxonomy).
    subcategory:
      name: subcategory
      in: query
      description: >-
        More specific linked Event subtype, CAMEO+ event description, or CAMEO+
        code. Requires parent `category` and must belong to at least one
        selected category. For Conflict categories, use sub-event types such as
        `Armed clash`, `Peaceful protest`, or `Air/drone strike`. Validation
        errors include accepted_values, nearest_values when practical, and a
        corrected example. Full list: [Taxonomy &
        Codes](/api-reference/taxonomy).
      schema:
        type: string
        example: Armed clash
      example: Armed clash
    domain:
      name: domain
      in: query
      description: >-
        Deprecated legacy CAMEO+ domain enum. Prefer `category`/`categories` for
        new integrations; retained for backwards compatibility. Full list:
        [Taxonomy & Codes](/api-reference/taxonomy).
      schema:
        $ref: '#/components/schemas/Domain'
      deprecated: true
    search:
      name: search
      in: query
      description: >-
        Free-text semantic search. The API ranks the filtered candidate set by
        semantic similarity against stored Event or Story representations. It is
        not a lexical keyword filter and has no public similarity cutoff.
      schema:
        type: string
        example: attacks on energy infrastructure
      example: attacks on energy infrastructure
    hasEvents:
      name: has_events
      in: query
      description: >-
        For Stories, set `true` to require linked structured Events or `false`
        for Stories without linked Events.
      schema:
        type: boolean
        example: true
      example: true
    hasFatalities:
      name: has_fatalities
      in: query
      description: >-
        Set `true` for fatality monitoring. v2 intentionally exposes only this
        boolean fatality filter.
      schema:
        type: boolean
        example: true
      example: true
    civilianTargeting:
      name: civilian_targeting
      in: query
      description: >-
        Filter Conflict-linked evidence by ACLED civilian_targeting. `true`
        keeps records where civilians are the primary target; `false` excludes
        those records.
      schema:
        type: boolean
    articleCountMin:
      name: article_count_min
      in: query
      description: Minimum Story article count.
      schema:
        type: integer
        minimum: 0
        example: 2
      example: 2
    articleCountMax:
      name: article_count_max
      in: query
      description: Maximum Story article count.
      schema:
        type: integer
        minimum: 0
        example: 25
      example: 25
    languages:
      name: languages
      in: query
      description: >-
        Filter to items with at least one linked article in these source
        (origin) languages. Comma-separated ISO codes — `en`, `zh`, `ar`, `es`,
        `fr`, … — normalized case-insensitively and OR'd together; the alias
        `language` is accepted. Unknown codes are dropped rather than erroring.
      schema:
        type: string
        example: en,zh
      example: en,zh
    includeImages:
      name: include_images
      in: query
      description: >-
        Include best-effort representative article image URLs on each row — a
        top-level `image_url` plus `top_articles[].image_url`. Defaults to
        `true`; set `false` to skip image enrichment for a lighter, faster
        response.
      schema:
        type: boolean
        default: true
        example: true
    sort:
      name: sort
      in: query
      description: >-
        `significance` is the default analyst ranking. Use `recent` when
        freshness matters more than importance.
      schema:
        $ref: '#/components/schemas/Sort'
        example: significance
      example: significance
    limit:
      name: limit
      in: query
      description: Number of records to return.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
        example: 25
      example: 25
    cursor:
      name: cursor
      in: query
      description: Pagination cursor from `pagination.next_cursor`.
      schema:
        type: string
  schemas:
    PaginatedResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        pagination:
          $ref: '#/components/schemas/Pagination'
    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.
    Sort:
      type: string
      enum:
        - significance
        - recent
      default: significance
    Domain:
      type: string
      enum:
        - POLITICAL
        - ECONOMIC
        - CORPORATE
        - TECHNOLOGY
        - INFRASTRUCTURE
        - HEALTH
        - DEMOGRAPHIC
        - INFORMATION
        - ENVIRONMENT
        - CRIME
    Pagination:
      type: object
      properties:
        limit:
          type: integer
        cursor:
          type: string
          nullable: true
        next_cursor:
          type: string
          nullable: true
    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
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: gdelt_sk_...
      description: 'GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`.'

````