> ## 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. # Preview Monitor > Execute one validated Monitor specification on demand without saving it. API-key calls return the query Preview only. Signed-in Builder calls also send a canonical signed monitor.test event to a short-lived first-party receiver and return the actual request/response transcript. Accepted previews cost 1 QU; authentication, validation, plan, and internal execution failures cost 0 QU. Scheduled Monitor executions cost 0 QU. sample_rows are representative; sample_count is the execution count, and semantic Monitor v1 evaluates a bounded candidate set. When count_truncated is true, sample_count reached candidate_limit and is a lower bound rather than an exhaustive corpus total. ## OpenAPI ````yaml /api-reference/openapi-v2.json post /api/v2/monitors/preview 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/preview: post: tags: - Monitors summary: Preview Monitor description: >- Execute one validated Monitor specification on demand without saving it. API-key calls return the query Preview only. Signed-in Builder calls also send a canonical signed monitor.test event to a short-lived first-party receiver and return the actual request/response transcript. Accepted previews cost 1 QU; authentication, validation, plan, and internal execution failures cost 0 QU. Scheduled Monitor executions cost 0 QU. sample_rows are representative; sample_count is the execution count, and semantic Monitor v1 evaluates a bounded candidate set. When count_truncated is true, sample_count reached candidate_limit and is a lower bound rather than an exhaustive corpus total. operationId: preview-monitor-v2 parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MonitorPreviewRequest' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/MonitorPreviewResponse' examples: canonical: summary: One accepted mixed-data Preview value: success: true preview: success: true normalized_spec: alert_kind: every_hit target_family: cameoplus filters: selected_families: - cameoplus - conflict - story countries: - USA search: port closure shipping disruption evaluation: sample_limit: 10 primitive_name: event_search sample_rows: - item_id: story:story_example lane: story id: story_example title: Port operations paused after labor disruption observed_at: '2026-08-24T13:42:00.000Z' sample_count: 3 count_truncated: false candidate_limit: 100 evaluation: 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 execution_time_ms: 842 window_start: '2026-08-24T13:00:00.000Z' window_end: '2026-08-24T14:00:00.000Z' window_label: Rolling last hour UTC explanation: trigger_type_label: New matches chart_kind: simple_count interpretation_headline: 3 matches in this window interpretation_body: Representative rows are shown below. formula_label: null did_trigger: true current_window_count: 3 threshold_count: null baseline_average: null baseline_window_counts: [] event_count: null story_count: null event_threshold: null story_threshold: null comparison_mode: null chart_points: [] evidence_default_label: null evidence_event_label: null evidence_story_label: null '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' security: - ApiKeyAuth: [] components: schemas: MonitorPreviewRequest: type: object properties: name: type: string description: type: string 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 additionalProperties: false - type: object properties: type: type: string enum: - facility facility_id: type: string radius_km: type: number default: 25 minimum: 0 exclusiveMinimum: true maximum: 1000 description: >- Great-circle radius in kilometers; greater than 0 and at most 1000. required: - type - facility_id additionalProperties: false - type: object properties: type: type: string enum: - place latitude: type: number minimum: -90 maximum: 90 longitude: type: number minimum: -180 maximum: 180 radius_km: type: number minimum: 0 exclusiveMinimum: true maximum: 1000 description: >- Great-circle radius in kilometers; greater than 0 and at most 1000. required: - type - latitude - longitude - radius_km additionalProperties: false - 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 additionalProperties: false - type: object properties: type: type: string enum: - topic required: - type additionalProperties: false - type: object properties: type: type: string enum: - category required: - type additionalProperties: false 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: [] additionalProperties: false 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: [] additionalProperties: false 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: [] additionalProperties: false default: {} additionalProperties: false fatalities_only: type: boolean default: false default: data: events_and_stories countries: [] source_actor_countries: [] target_actor_countries: [] family_filters: {} fatalities_only: false additionalProperties: false trigger: type: object properties: type: type: string enum: - new_matches required: - type additionalProperties: false 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 description: Local wall-clock hour, as an integer from 0 through 23. required: - cadence additionalProperties: false delivery: type: object properties: email: type: boolean default: false webhook_url: type: string format: uri default: email: false additionalProperties: false description: >- Preview owns its temporary first-party delivery. email may be false and webhook_url may be omitted; no saved delivery is created. required: - name - subject - trigger - schedule additionalProperties: false MonitorPreviewResponse: type: object required: - success - preview properties: success: type: boolean enum: - true preview: $ref: '#/components/schemas/MonitorPreviewExecution' 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 MonitorPreviewExecution: type: object properties: success: type: boolean enum: - true normalized_spec: type: object properties: alert_kind: type: string enum: - every_hit target_family: type: string enum: - cameoplus - conflict - story filters: {} evaluation: type: object properties: sample_limit: type: number default: 10 default: sample_limit: 10 required: - alert_kind - target_family - filters primitive_name: type: string enum: - events - events_summary - story_search - story_detail - coverage sample_rows: type: array items: type: object additionalProperties: {} description: >- Representative retained rows; inspect them before saving. This array is not the total. sample_count: type: number description: >- Matches counted by the Preview execution, not sample_rows.length. Read count_truncated before treating it as exhaustive. count_truncated: type: boolean description: >- True when sample_count reached candidate_limit and is a lower bound rather than a complete corpus count. candidate_limit: type: number nullable: true description: >- Semantic candidate ceiling for this execution, or null when no candidate ceiling applied. evaluation: type: object properties: would_trigger: type: boolean disposition: type: string enum: - no_trigger - triggered - underreported_risk - narrative_amplification reason: type: string current_count: type: number default: 0 baseline_average: type: number nullable: true default: null event_count: type: number nullable: true default: null story_count: type: number nullable: true default: null event_baseline_average: type: number nullable: true default: null story_baseline_average: type: number nullable: true default: null new_item_ids: type: array items: type: string default: [] new_item_count: type: number nullable: true default: null trigger_fingerprint: type: string required: - would_trigger - disposition - reason - trigger_fingerprint execution_time_ms: type: number window_start: type: string format: date-time description: Inclusive beginning of this rolling Preview window. window_end: type: string format: date-time description: Exclusive end of this rolling Preview window. window_label: type: string historical_example: type: object properties: basis: type: string enum: - expanded_window reason: type: string enum: - configured_window_empty sample_rows: type: array items: type: object additionalProperties: {} sample_count: type: number count_truncated: type: boolean candidate_limit: type: number nullable: true window_start: type: string window_end: type: string window_label: type: string required: - basis - reason - sample_rows - sample_count - count_truncated - candidate_limit - window_start - window_end - window_label nullable: true historical_example_status: type: string enum: - not_needed - available - empty - unavailable explanation: type: object properties: trigger_type_label: type: string chart_kind: type: string enum: - simple_count - threshold_meter - spike_series - coverage_split interpretation_headline: type: string interpretation_body: type: string formula_label: type: string nullable: true default: null did_trigger: type: boolean current_window_count: type: number threshold_count: type: number nullable: true default: null baseline_average: type: number nullable: true default: null baseline_window_counts: type: array items: type: number default: [] event_count: type: number nullable: true default: null story_count: type: number nullable: true default: null event_threshold: type: number nullable: true default: null story_threshold: type: number nullable: true default: null comparison_mode: type: string enum: - both - underreported_risk - narrative_amplification nullable: true default: null chart_points: type: array items: type: object properties: label: type: string value: type: number role: type: string required: - label - value - role default: [] evidence_default_label: type: string nullable: true default: null evidence_event_label: type: string nullable: true default: null evidence_story_label: type: string nullable: true default: null required: - trigger_type_label - chart_kind - interpretation_headline - interpretation_body - did_trigger - current_window_count required: - success - normalized_spec - primitive_name - sample_rows - sample_count - count_truncated - candidate_limit - evaluation - execution_time_ms - window_start - window_end - window_label - historical_example - historical_example_status - explanation securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: gdelt_sk_... description: 'GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`.' ````