> ## 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 triggered Monitor runs

> List the Monitor’s triggered runs retained for seven days. result_count, retained_row_count, and results.length describe different quantities.



## OpenAPI

````yaml /api-reference/openapi-v2.json get /api/v2/monitors/{id}/runs
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: 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: Admin-1 geography 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: 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/monitors/{id}/runs:
    get:
      tags:
        - Monitors
      summary: List triggered Monitor runs
      description: >-
        List the Monitor’s triggered runs retained for seven days. result_count,
        retained_row_count, and results.length describe different quantities.
      operationId: list-monitor-runs-v2
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          description: >-
            Runs per page. Default 25, max 100. A value outside the range is
            refused, not clamped. 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
            maximum: 100000
            default: 0
          description: >-
            Rows to skip, for paging back through the seven-day retention
            window. Plain integer offset — this endpoint has no opaque cursor.
            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'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorRunsResponse'
              examples:
                canonical:
                  summary: Triggered runs retained for seven days
                  value:
                    success: true
                    monitor:
                      id: 5e1d3b89-9c34-4fa1-80fc-17f72f782b33
                      organization_id: 88949d2a-4f00-45cb-9d23-2d242ddfe74d
                      created_by: c6951b53-952b-40bf-99fd-c9d97a176f38
                      name: Port disruption watch
                      description: >-
                        New coverage of port closures and shipping disruption in
                        the United States.
                      enabled: true
                      subject:
                        type: topic
                      criteria:
                        data: events_and_stories
                        search: port closure shipping disruption
                        countries:
                          - USA
                        family_filters:
                          cameoplus:
                            domains:
                              - INFRASTRUCTURE
                            subcategories: []
                          story:
                            categories:
                              - cameoplus_infrastructure
                        fatalities_only: false
                      trigger:
                        type: new_matches
                      schedule:
                        cadence: hourly
                        timezone: UTC
                        daily_hour: 8
                      delivery:
                        email: true
                        webhook:
                          configured: true
                          endpoint: https://example.com/gdelt-webhook
                          consecutive_failures: 0
                          last_success_at: '2026-08-23T14:05:00.000Z'
                          last_failure_at: null
                      created_at: '2026-08-23T13:00:00.000Z'
                      updated_at: '2026-08-23T14:05:00.000Z'
                      last_checked_at: '2026-08-23T14:00:00.000Z'
                      last_triggered_at: '2026-08-23T14:00:00.000Z'
                      legacy: false
                    runs:
                      - id: 6d403a03-83a7-4603-a92d-37012fbf0219
                        execution_key: >-
                          monitor/5e1d3b89-9c34-4fa1-80fc-17f72f782b33/v1/2026-08-24T14:00:00.000Z
                        alert_rule_id: 5e1d3b89-9c34-4fa1-80fc-17f72f782b33
                        alert_log_id: 412
                        shared_run_id: 7b1a1fac-f9dc-4667-b013-3de5ed4bf6fa
                        results:
                          - item_id: story:story_example
                            lane: story
                            id: story_example
                            title: Port operations paused after labor disruption
                        result_count: 3
                        summary_json:
                          total_matches: 3
                          total_matches_is_lower_bound: false
                          candidate_limit: 100
                          retained_matches: 1
                          truncated: true
                          disposition: triggered
                          reason: 3 new matches found in the current window.
                          frequency: hourly
                          target_family: cameoplus
                          selected_families:
                            - cameoplus
                            - conflict
                            - story
                          window_start: '2026-08-24T13:00:00.000Z'
                          window_end: '2026-08-24T14:00:00.000Z'
                          window_label: Previous completed UTC hour
                          family_groups:
                            - label: Story
                              count: 1
                          country_groups:
                            - label: United States
                              count: 1
                          signal_groups: []
                          top_items:
                            - title: Port operations paused after labor disruption
                              family: story
                              meta: United States
                              observed_at: '2026-08-24T13:42:00.000Z'
                        ai_summary: null
                        retained_row_count: 1
                        truncated: true
                        evaluation_json:
                          would_trigger: true
                          disposition: triggered
                          reason: 3 new matches found in the current window.
                          current_count: 3
                          baseline_average: null
                          event_count: null
                          story_count: null
                          event_baseline_average: null
                          story_baseline_average: null
                          new_item_ids:
                            - story:story_example
                          trigger_fingerprint: sha256:opaque
                        executed_at: '2026-08-24T14:00:04.000Z'
                        viewed_at: null
                        expires_at: '2026-08-31T14:00:04.000Z'
                        created_at: '2026-08-24T14:00:04.000Z'
                    total: 1
                    limit: 25
                    offset: 0
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Plan or organization role does not permit this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Monitor not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    MonitorRunsResponse:
      type: object
      required:
        - success
        - monitor
        - runs
        - total
        - limit
        - offset
      properties:
        success:
          type: boolean
          enum:
            - true
        monitor:
          $ref: '#/components/schemas/Monitor'
        runs:
          type: array
          items:
            $ref: '#/components/schemas/MonitorStoredRun'
        total:
          type: integer
          minimum: 0
        limit:
          type: integer
          minimum: 1
          maximum: 100
        offset:
          type: integer
          minimum: 0
    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
    Monitor:
      oneOf:
        - type: object
          properties:
            id:
              type: string
              format: uuid
            organization_id:
              type: string
              nullable: true
              format: uuid
            created_by:
              type: string
              format: uuid
            name:
              type: string
            description:
              type: string
              nullable: true
            enabled:
              type: boolean
            paused_by:
              type: string
              enum:
                - user
                - system
              nullable: true
            auto_paused_at:
              type: string
              nullable: true
            schedule:
              type: object
              properties:
                cadence:
                  type: string
                  enum:
                    - hourly
                    - daily
                timezone:
                  type: string
                  default: UTC
                daily_hour:
                  type: integer
                  default: 8
                  minimum: 0
                  maximum: 23
              required:
                - cadence
                - timezone
                - daily_hour
            delivery:
              type: object
              properties:
                email:
                  type: boolean
                webhook:
                  type: object
                  properties:
                    configured:
                      type: boolean
                    endpoint:
                      type: string
                      format: uri
                      nullable: true
                    consecutive_failures:
                      type: integer
                      minimum: 0
                    last_success_at:
                      type: string
                      nullable: true
                      format: date-time
                    last_failure_at:
                      type: string
                      nullable: true
                      format: date-time
                  required:
                    - configured
                    - endpoint
                    - consecutive_failures
                    - last_success_at
                    - last_failure_at
              required:
                - email
                - webhook
            created_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
            last_checked_at:
              type: string
              nullable: true
              format: date-time
            last_triggered_at:
              type: string
              nullable: true
              format: date-time
            subject:
              oneOf:
                - type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - entity
                    entity_ids:
                      type: array
                      items:
                        type: string
                    match:
                      type: string
                      enum:
                        - coverage
                      default: coverage
                  required:
                    - type
                    - entity_ids
                    - match
                - type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - facility
                    facility_id:
                      type: string
                    radius_km:
                      type: number
                      default: 25
                  required:
                    - type
                    - facility_id
                    - radius_km
                - type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - place
                    latitude:
                      type: number
                    longitude:
                      type: number
                    radius_km:
                      type: number
                  required:
                    - type
                    - latitude
                    - longitude
                    - radius_km
                - type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - geography
                    countries:
                      type: array
                      items:
                        type: string
                      default: []
                      description: >-
                        Location-only country scope for a geography subject:
                        matching events happened in one of these countries.
                    region:
                      type: string
                    continent:
                      type: string
                    admin1:
                      type: string
                  required:
                    - type
                    - countries
                - type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - topic
                  required:
                    - type
                - type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - category
                  required:
                    - type
            criteria:
              type: object
              properties:
                data:
                  type: string
                  enum:
                    - events
                    - stories
                    - events_and_stories
                  default: events_and_stories
                search:
                  type: string
                countries:
                  type: array
                  items:
                    type: string
                  default: []
                  description: >-
                    Country refinement for non-geography subjects. Matches event
                    location or either actor origin, consistent with the Events
                    and Stories API default.
                source_actor_countries:
                  type: array
                  items:
                    type: string
                    enum:
                      - USA
                      - CAN
                      - MEX
                      - BRA
                      - ARG
                      - COL
                      - VEN
                      - CHL
                      - CUB
                      - PER
                      - BOL
                      - URY
                      - PRY
                      - ECU
                      - GTM
                      - HND
                      - CRI
                      - PAN
                      - DOM
                      - HTI
                      - JAM
                      - TTO
                      - BLZ
                      - NIC
                      - SLV
                      - GUY
                      - SUR
                      - PRI
                      - ABW
                      - BHS
                      - BMU
                      - BRB
                      - CUW
                      - CYM
                      - GRD
                      - KNA
                      - LCA
                      - SXM
                      - VCT
                      - VGB
                      - VIR
                      - GBR
                      - DEU
                      - FRA
                      - ITA
                      - ESP
                      - RUS
                      - UKR
                      - POL
                      - NLD
                      - BEL
                      - SWE
                      - NOR
                      - DNK
                      - FIN
                      - AUT
                      - CHE
                      - AND
                      - PRT
                      - GRC
                      - CZE
                      - HUN
                      - ROU
                      - BGR
                      - HRV
                      - SRB
                      - SVK
                      - SVN
                      - ALB
                      - BLR
                      - MDA
                      - LTU
                      - LVA
                      - EST
                      - IRL
                      - LUX
                      - MLT
                      - CYP
                      - MNE
                      - MKD
                      - BIH
                      - XKX
                      - ISL
                      - GIB
                      - JEY
                      - MCO
                      - VAT
                      - IRN
                      - ISR
                      - SAU
                      - TUR
                      - EGY
                      - IRQ
                      - SYR
                      - JOR
                      - LBN
                      - YEM
                      - LBY
                      - MAR
                      - DZA
                      - TUN
                      - QAT
                      - ARE
                      - KWT
                      - OMN
                      - BHR
                      - PSE
                      - NGA
                      - ZAF
                      - ETH
                      - KEN
                      - TZA
                      - UGA
                      - SDN
                      - SOM
                      - ERI
                      - DJI
                      - RWA
                      - COD
                      - CMR
                      - GHA
                      - SEN
                      - CIV
                      - MLI
                      - BFA
                      - NER
                      - TCD
                      - ZMB
                      - ZWE
                      - MOZ
                      - AGO
                      - MDG
                      - TGO
                      - BEN
                      - LBR
                      - SLE
                      - GIN
                      - GNB
                      - MRT
                      - GMB
                      - CPV
                      - STP
                      - GNQ
                      - GAB
                      - COG
                      - CAF
                      - SSD
                      - BDI
                      - COM
                      - MWI
                      - MUS
                      - LSO
                      - SWZ
                      - NAM
                      - BWA
                      - ESH
                      - SYC
                      - CHN
                      - JPN
                      - IND
                      - PAK
                      - AFG
                      - KOR
                      - PRK
                      - VNM
                      - THA
                      - IDN
                      - MYS
                      - PHL
                      - AUS
                      - NZL
                      - SGP
                      - MMR
                      - BGD
                      - LKA
                      - NPL
                      - KHM
                      - LAO
                      - MNG
                      - KAZ
                      - UZB
                      - AZE
                      - GEO
                      - ARM
                      - TJK
                      - TKM
                      - KGZ
                      - TWN
                      - BRN
                      - TLS
                      - PNG
                      - FJI
                      - SLB
                      - VUT
                      - WSM
                      - TON
                      - HKG
                      - MAC
                      - COK
                      - GUM
                      - MHL
                      - NCL
                      - BTN
                      - MDV
                  default: []
                target_actor_countries:
                  type: array
                  items:
                    type: string
                    enum:
                      - USA
                      - CAN
                      - MEX
                      - BRA
                      - ARG
                      - COL
                      - VEN
                      - CHL
                      - CUB
                      - PER
                      - BOL
                      - URY
                      - PRY
                      - ECU
                      - GTM
                      - HND
                      - CRI
                      - PAN
                      - DOM
                      - HTI
                      - JAM
                      - TTO
                      - BLZ
                      - NIC
                      - SLV
                      - GUY
                      - SUR
                      - PRI
                      - ABW
                      - BHS
                      - BMU
                      - BRB
                      - CUW
                      - CYM
                      - GRD
                      - KNA
                      - LCA
                      - SXM
                      - VCT
                      - VGB
                      - VIR
                      - GBR
                      - DEU
                      - FRA
                      - ITA
                      - ESP
                      - RUS
                      - UKR
                      - POL
                      - NLD
                      - BEL
                      - SWE
                      - NOR
                      - DNK
                      - FIN
                      - AUT
                      - CHE
                      - AND
                      - PRT
                      - GRC
                      - CZE
                      - HUN
                      - ROU
                      - BGR
                      - HRV
                      - SRB
                      - SVK
                      - SVN
                      - ALB
                      - BLR
                      - MDA
                      - LTU
                      - LVA
                      - EST
                      - IRL
                      - LUX
                      - MLT
                      - CYP
                      - MNE
                      - MKD
                      - BIH
                      - XKX
                      - ISL
                      - GIB
                      - JEY
                      - MCO
                      - VAT
                      - IRN
                      - ISR
                      - SAU
                      - TUR
                      - EGY
                      - IRQ
                      - SYR
                      - JOR
                      - LBN
                      - YEM
                      - LBY
                      - MAR
                      - DZA
                      - TUN
                      - QAT
                      - ARE
                      - KWT
                      - OMN
                      - BHR
                      - PSE
                      - NGA
                      - ZAF
                      - ETH
                      - KEN
                      - TZA
                      - UGA
                      - SDN
                      - SOM
                      - ERI
                      - DJI
                      - RWA
                      - COD
                      - CMR
                      - GHA
                      - SEN
                      - CIV
                      - MLI
                      - BFA
                      - NER
                      - TCD
                      - ZMB
                      - ZWE
                      - MOZ
                      - AGO
                      - MDG
                      - TGO
                      - BEN
                      - LBR
                      - SLE
                      - GIN
                      - GNB
                      - MRT
                      - GMB
                      - CPV
                      - STP
                      - GNQ
                      - GAB
                      - COG
                      - CAF
                      - SSD
                      - BDI
                      - COM
                      - MWI
                      - MUS
                      - LSO
                      - SWZ
                      - NAM
                      - BWA
                      - ESH
                      - SYC
                      - CHN
                      - JPN
                      - IND
                      - PAK
                      - AFG
                      - KOR
                      - PRK
                      - VNM
                      - THA
                      - IDN
                      - MYS
                      - PHL
                      - AUS
                      - NZL
                      - SGP
                      - MMR
                      - BGD
                      - LKA
                      - NPL
                      - KHM
                      - LAO
                      - MNG
                      - KAZ
                      - UZB
                      - AZE
                      - GEO
                      - ARM
                      - TJK
                      - TKM
                      - KGZ
                      - TWN
                      - BRN
                      - TLS
                      - PNG
                      - FJI
                      - SLB
                      - VUT
                      - WSM
                      - TON
                      - HKG
                      - MAC
                      - COK
                      - GUM
                      - MHL
                      - NCL
                      - BTN
                      - MDV
                  default: []
                region:
                  type: string
                continent:
                  type: string
                admin1:
                  type: string
                family_filters:
                  type: object
                  properties:
                    cameoplus:
                      type: object
                      properties:
                        domains:
                          type: array
                          items:
                            type: string
                            enum:
                              - POLITICAL
                              - CRIME
                              - ECONOMIC
                              - CORPORATE
                              - TECHNOLOGY
                              - INFRASTRUCTURE
                              - ENVIRONMENT
                              - HEALTH
                              - DEMOGRAPHIC
                              - INFORMATION
                          default: []
                        subcategories:
                          type: array
                          items:
                            type: string
                            enum:
                              - '10'
                              - '11'
                              - '12'
                              - '13'
                              - '15'
                              - '16'
                              - '17'
                              - '100'
                              - '101'
                              - '102'
                              - '103'
                              - '104'
                              - '105'
                              - '106'
                              - '107'
                              - '108'
                              - '110'
                              - '111'
                              - '112'
                              - '113'
                              - '114'
                              - '115'
                              - '116'
                              - '120'
                              - '121'
                              - '122'
                              - '123'
                              - '124'
                              - '125'
                              - '126'
                              - '127'
                              - '128'
                              - '129'
                              - '130'
                              - '131'
                              - '132'
                              - '133'
                              - '134'
                              - '135'
                              - '136'
                              - '137'
                              - '138'
                              - '139'
                              - '150'
                              - '151'
                              - '152'
                              - '153'
                              - '154'
                              - '155'
                              - '160'
                              - '161'
                              - '162'
                              - '163'
                              - '164'
                              - '165'
                              - '166'
                              - '170'
                              - '171'
                              - '172'
                              - '174'
                              - '176'
                              - '1011'
                              - '1012'
                              - '1013'
                              - '1014'
                              - '1031'
                              - '1032'
                              - '1033'
                              - '1034'
                              - '1041'
                              - '1042'
                              - '1043'
                              - '1044'
                              - '1051'
                              - '1052'
                              - '1053'
                              - '1054'
                              - '1055'
                              - '1056'
                              - '1121'
                              - '1122'
                              - '1123'
                              - '1124'
                              - '1125'
                              - '1211'
                              - '1212'
                              - '1213'
                              - '1214'
                              - '1221'
                              - '1222'
                              - '1223'
                              - '1224'
                              - '1231'
                              - '1232'
                              - '1233'
                              - '1234'
                              - '1241'
                              - '1242'
                              - '1243'
                              - '1244'
                              - '1245'
                              - '1246'
                              - '1311'
                              - '1312'
                              - '1313'
                              - '1321'
                              - '1322'
                              - '1323'
                              - '1324'
                              - '1381'
                              - '1382'
                              - '1383'
                              - '1384'
                              - '1385'
                              - '1621'
                              - '1622'
                              - '1623'
                              - '1661'
                              - '1662'
                              - '1663'
                              - '1711'
                              - '1712'
                              - '1721'
                              - '1722'
                              - '1723'
                              - '1724'
                              - CR01
                              - CR02
                              - CR03
                              - CR04
                              - CR05
                              - CR06
                              - CR07
                              - CR08
                              - CR09
                              - CR10
                              - EC01
                              - EC02
                              - EC03
                              - EC04
                              - EC05
                              - EC06
                              - EC07
                              - CO01
                              - CO02
                              - CO03
                              - CO04
                              - CO05
                              - CO06
                              - CO07
                              - CO08
                              - TE01
                              - TE02
                              - TE03
                              - TE04
                              - TE05
                              - TE06
                              - IN01
                              - IN02
                              - IN03
                              - IN04
                              - IN05
                              - IN06
                              - EN01
                              - EN02
                              - EN03
                              - EN04
                              - EN05
                              - HE01
                              - HE02
                              - HE03
                              - HE04
                              - HE05
                              - DE01
                              - DE02
                              - DE03
                              - DE04
                              - DE05
                              - IF01
                              - IF02
                              - IF03
                              - IF04
                              - '01'
                              - '02'
                              - '03'
                              - '04'
                              - '05'
                              - '06'
                              - '07'
                              - '08'
                              - '09'
                              - '010'
                              - '011'
                              - '012'
                              - '013'
                              - '014'
                              - '015'
                              - '016'
                              - '017'
                              - '018'
                              - '019'
                              - '020'
                              - '021'
                              - '0211'
                              - '0212'
                              - '0213'
                              - '0214'
                              - '022'
                              - '023'
                              - '0231'
                              - '0232'
                              - '0233'
                              - '0234'
                              - '024'
                              - '0241'
                              - '0242'
                              - '0243'
                              - '0244'
                              - '025'
                              - '0251'
                              - '0252'
                              - '0253'
                              - '0254'
                              - '0255'
                              - '0256'
                              - '026'
                              - '027'
                              - '028'
                              - '030'
                              - '031'
                              - '0311'
                              - '0312'
                              - '0313'
                              - '0314'
                              - '032'
                              - '033'
                              - '0331'
                              - '0332'
                              - '0333'
                              - '0334'
                              - '034'
                              - '0341'
                              - '0342'
                              - '0343'
                              - '0344'
                              - '035'
                              - '0351'
                              - '0352'
                              - '0353'
                              - '0354'
                              - '0355'
                              - '0356'
                              - '036'
                              - '037'
                              - '038'
                              - '039'
                              - '040'
                              - '041'
                              - '042'
                              - '043'
                              - '044'
                              - '045'
                              - '046'
                              - '050'
                              - '051'
                              - '052'
                              - '053'
                              - '054'
                              - '055'
                              - '056'
                              - '057'
                              - '060'
                              - '061'
                              - '062'
                              - '063'
                              - '064'
                              - '070'
                              - '071'
                              - '072'
                              - '073'
                              - '074'
                              - '075'
                              - '080'
                              - '081'
                              - '0811'
                              - '0812'
                              - '0813'
                              - '0814'
                              - '082'
                              - '083'
                              - '0831'
                              - '0832'
                              - '0833'
                              - '0834'
                              - '084'
                              - '0841'
                              - '0842'
                              - '085'
                              - '086'
                              - '0861'
                              - '0862'
                              - '0863'
                              - '087'
                              - '0871'
                              - '0872'
                              - '0873'
                              - '0874'
                              - '090'
                              - '091'
                              - '092'
                              - '093'
                              - '094'
                          default: []
                    conflict:
                      type: object
                      properties:
                        categories:
                          type: array
                          items:
                            type: string
                            enum:
                              - Battles
                              - Protests
                              - Riots
                              - Explosions/Remote violence
                              - Violence against civilians
                              - Strategic developments
                          default: []
                        subcategories:
                          type: array
                          items:
                            type: string
                            enum:
                              - Government regains territory
                              - Non-state actor overtakes territory
                              - Armed clash
                              - Excessive force against protesters
                              - Protest with intervention
                              - Peaceful protest
                              - Violent demonstration
                              - Mob violence
                              - Chemical weapon
                              - Air/drone strike
                              - Suicide bomb
                              - Shelling/artillery/missile attack
                              - Remote explosive/landmine/IED
                              - Grenade
                              - Sexual violence
                              - Attack
                              - Abduction/forced disappearance
                              - Agreement
                              - Arrests
                              - Change to group/activity
                              - Disrupted weapons use
                              - Headquarters or base established
                              - Looting/property destruction
                              - Non-violent transfer of territory
                              - Other
                          default: []
                    story:
                      type: object
                      properties:
                        categories:
                          type: array
                          items:
                            type: string
                            enum:
                              - conflict_security
                              - cameoplus_political
                              - cameoplus_crime
                              - cameoplus_economic
                              - cameoplus_corporate
                              - cameoplus_technology
                              - cameoplus_infrastructure
                              - cameoplus_environment
                              - cameoplus_health
                              - cameoplus_demographic
                              - cameoplus_information
                              - CONFLICT
                              - CORPORATE
                              - CRIME
                              - DEMOGRAPHIC
                              - ECONOMIC
                              - ENVIRONMENT
                              - HEALTH
                              - INFORMATION
                              - INFRASTRUCTURE
                              - POLITICAL
                              - TECHNOLOGY
                          default: []
                  default: {}
                fatalities_only:
                  type: boolean
                  default: false
              default:
                data: events_and_stories
                countries: []
                source_actor_countries: []
                target_actor_countries: []
                family_filters: {}
                fatalities_only: false
              required:
                - data
                - countries
                - family_filters
                - fatalities_only
            trigger:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - new_matches
              required:
                - type
            legacy:
              type: boolean
              enum:
                - false
          required:
            - id
            - organization_id
            - created_by
            - name
            - description
            - enabled
            - paused_by
            - auto_paused_at
            - schedule
            - delivery
            - created_at
            - updated_at
            - last_checked_at
            - last_triggered_at
            - subject
            - trigger
            - legacy
            - criteria
        - type: object
          properties:
            id:
              type: string
              format: uuid
            organization_id:
              type: string
              nullable: true
              format: uuid
            created_by:
              type: string
              format: uuid
            name:
              type: string
            description:
              type: string
              nullable: true
            enabled:
              type: boolean
            paused_by:
              type: string
              enum:
                - user
                - system
              nullable: true
            auto_paused_at:
              type: string
              nullable: true
            schedule:
              type: object
              properties:
                cadence:
                  type: string
                  enum:
                    - hourly
                    - daily
                timezone:
                  type: string
                  default: UTC
                daily_hour:
                  type: integer
                  default: 8
                  minimum: 0
                  maximum: 23
              required:
                - cadence
                - timezone
                - daily_hour
            delivery:
              type: object
              properties:
                email:
                  type: boolean
                webhook:
                  type: object
                  properties:
                    configured:
                      type: boolean
                    endpoint:
                      type: string
                      format: uri
                      nullable: true
                    consecutive_failures:
                      type: integer
                      minimum: 0
                    last_success_at:
                      type: string
                      nullable: true
                      format: date-time
                    last_failure_at:
                      type: string
                      nullable: true
                      format: date-time
                  required:
                    - configured
                    - endpoint
                    - consecutive_failures
                    - last_success_at
                    - last_failure_at
              required:
                - email
                - webhook
            created_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
            last_checked_at:
              type: string
              nullable: true
              format: date-time
            last_triggered_at:
              type: string
              nullable: true
              format: date-time
            subject:
              nullable: true
              enum:
                - null
            criteria:
              nullable: true
              enum:
                - null
            trigger:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - legacy
              required:
                - type
            legacy:
              type: boolean
              enum:
                - true
          required:
            - id
            - organization_id
            - created_by
            - name
            - description
            - enabled
            - paused_by
            - auto_paused_at
            - schedule
            - delivery
            - created_at
            - updated_at
            - last_checked_at
            - last_triggered_at
            - subject
            - criteria
            - trigger
            - legacy
          description: >-
            Read-only compatibility record. It cannot be used as a canonical
            Monitor request body.
    MonitorStoredRun:
      type: object
      required:
        - id
        - alert_rule_id
        - results
        - result_count
        - retained_row_count
        - truncated
        - evaluation_json
        - executed_at
        - expires_at
        - created_at
      properties:
        id:
          type: string
          format: uuid
        execution_key:
          type: string
          description: Opaque stable execution identity for this Monitor schedule/window.
        alert_rule_id:
          type: string
          format: uuid
        alert_log_id:
          type: integer
          nullable: true
        shared_run_id:
          type: string
          nullable: true
          format: uuid
        results:
          type: array
          items:
            type: object
            additionalProperties: true
          description: Bounded retained execution rows.
        result_count:
          type: integer
          minimum: 0
          description: >-
            Run match count. Compare with retained_row_count and truncated
            before treating results[] as complete.
        summary_json:
          type: object
          required:
            - total_matches
            - total_matches_is_lower_bound
            - candidate_limit
            - retained_matches
            - truncated
            - disposition
            - reason
            - frequency
            - target_family
            - selected_families
            - window_start
            - window_end
            - window_label
            - family_groups
            - country_groups
            - signal_groups
            - top_items
          properties:
            total_matches:
              type: integer
              minimum: 0
              description: >-
                Run match count. When total_matches_is_lower_bound is true, this
                reached candidate_limit and is not an exhaustive corpus total.
            total_matches_is_lower_bound:
              type: boolean
              description: >-
                True when total_matches is the semantic candidate ceiling rather
                than a complete count.
            candidate_limit:
              type: integer
              minimum: 1
              nullable: true
              description: >-
                Semantic candidate ceiling for this execution, or null when no
                candidate ceiling applied.
            retained_matches:
              type: integer
              minimum: 0
            truncated:
              type: boolean
              description: Whether the retained results omit matches counted by the run.
            disposition:
              type: string
              enum:
                - no_trigger
                - triggered
                - underreported_risk
                - narrative_amplification
            reason:
              type: string
            frequency:
              type: string
              enum:
                - hourly
                - daily
            target_family:
              type: string
              enum:
                - cameoplus
                - conflict
                - story
            selected_families:
              type: array
              items:
                type: string
                enum:
                  - cameoplus
                  - conflict
                  - story
            window_start:
              type: string
              format: date-time
            window_end:
              type: string
              format: date-time
            window_label:
              type: string
            family_groups:
              type: array
              items:
                $ref: '#/components/schemas/MonitorRunSummaryGroup'
            country_groups:
              type: array
              items:
                $ref: '#/components/schemas/MonitorRunSummaryGroup'
            signal_groups:
              type: array
              items:
                $ref: '#/components/schemas/MonitorRunSummaryGroup'
            top_items:
              type: array
              items:
                $ref: '#/components/schemas/MonitorRunTopItem'
          nullable: true
          description: Compatibility summary retained on the stored result.
        ai_summary:
          type: object
          nullable: true
          properties:
            model:
              type: string
            summary:
              type: string
            bullet_points:
              type: array
              items:
                type: string
            generated_at:
              type: string
              format: date-time
        retained_row_count:
          type: integer
          minimum: 0
        truncated:
          type: boolean
          description: True when result_count exceeds results.length/retained_row_count.
        evaluation_json:
          type: object
          required:
            - would_trigger
            - disposition
            - reason
            - current_count
            - new_item_ids
            - trigger_fingerprint
          properties:
            would_trigger:
              type: boolean
            disposition:
              type: string
              enum:
                - no_trigger
                - triggered
                - underreported_risk
                - narrative_amplification
            reason:
              type: string
            current_count:
              type: integer
              minimum: 0
              description: >-
                Matches counted by this execution. Semantic Monitor v1 evaluates
                a bounded candidate set, so this is not an unbounded corpus
                total.
            baseline_average:
              type: number
              minimum: 0
              nullable: true
            event_count:
              type: integer
              minimum: 0
              nullable: true
            story_count:
              type: integer
              minimum: 0
              nullable: true
            event_baseline_average:
              type: number
              minimum: 0
              nullable: true
            story_baseline_average:
              type: number
              minimum: 0
              nullable: true
            new_item_ids:
              type: array
              items:
                type: string
            trigger_fingerprint:
              type: string
              description: Opaque idempotency fingerprint for the evaluated trigger state.
        executed_at:
          type: string
          format: date-time
        viewed_at:
          type: string
          nullable: true
          format: date-time
        expires_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    MonitorRunSummaryGroup:
      type: object
      required:
        - label
        - count
      properties:
        label:
          type: string
        count:
          type: integer
          minimum: 0
    MonitorRunTopItem:
      type: object
      required:
        - title
        - family
        - meta
        - observed_at
      properties:
        title:
          type: string
        family:
          type: string
          enum:
            - cameoplus
            - conflict
            - story
        meta:
          type: string
          nullable: true
        observed_at:
          type: string
          nullable: true
          format: date-time
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: gdelt_sk_...
      description: 'GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`.'

````