---
title: "GetScenarioStatus"
method: GET
path: "/api/scenario/v1/get-scenario-status"
tags: ["ScenarioService"]
---

# GetScenarioStatus

`GET /api/scenario/v1/get-scenario-status`

## Request

- Base URL: `https://api.worldmonitor.app`
- URL: `https://api.worldmonitor.app/api/scenario/v1/get-scenario-status`
- Auth: one of:
  - API key in header `X-WorldMonitor-Key`
  - API key in header `X-Api-Key`
  - HTTP bearer

GetScenarioStatus polls a single job's result. PRO-gated. Returns status="pending" when no result key exists, mirroring the worker's lifecycle state once the key is written. Requires entitlement tier >= 1.

## Query parameters

- `jobId` string, required
- `jmespath` string

## Response `200`

OK

- WorldmonitorScenarioV1GetScenarioStatusResponse: GetScenarioStatusResponse reflects the worker's lifecycle state. "pending" — no key yet (job still queued or very-recent enqueue). "processing" — worker has claimed the job but hasn't completed compute. "done" — compute succeeded; `result` is populated. "failed" — compute errored; `error` is populated.
  - `status` string
  - `result` WorldmonitorScenarioV1ScenarioResult: ScenarioResult is the computed payload the scenario-worker writes back under the `scenario-result:{job_id}` Redis key. Populated only when GetScenarioStatusResponse.status == "done".
    - `affectedChokepointIds` string[]
    - `topImpactCountries` WorldmonitorScenarioV1ScenarioImpactCountry[]
      - `iso2` string: 2-letter ISO country code.
      - `totalImpact` number, double: Raw weighted impact value aggregated across the country's exposed HS2 chapters. Physical scenarios use exposureScore * (disruption_pct / 100) * cost_shock_multiplier; tariff-shock scenarios use vulnerabilityIndex * cost_shock_multiplier. Relative-only - not a currency amount.
      - `impactPct` integer: Impact as a 0-100 share of max(maxReturnedTotalImpact, 1), capped at 100. Because of the denominator floor, the top country can be below 100 when all returned totalImpact values are below 1.
      - `evaluatedRecords` integer: Country/sector records that actually produced total_impact.
      - `requestedRecords` integer: Country/sector records requested for this country.
      - `partialEvidence` boolean: True when evaluated_records < requested_records. total_impact is then a LOWER BOUND over the evidence that was available, not the country's impact, and must not be read as low exposure.
    - `template` WorldmonitorScenarioV1ScenarioResultTemplate: ScenarioResultTemplate carries the EFFECTIVE run parameters, so clients can render them without re-looking up the template registry. All fields except disruption_pct are registry values; disruption_pct is the caller's override when one was supplied.
      - `name` string: Worker-derived template key, not a display name. Physical scenarios join affected_chokepoint_ids with `+`; tariff-type scenarios may use `tariff_shock` when no physical chokepoint is affected.
      - `disruptionPct` integer: 0-100 percent of chokepoint capacity blocked. The EFFECTIVE severity: the caller's RunScenarioRequest.disruption_pct when supplied, else the registry default.
      - `durationDays` integer: Descriptive duration in days; not an input to the impact calculation.
      - `costShockMultiplier` number, double: Freight cost multiplier applied on top of bypass corridor costs.
    - `scenarioId` string: Selected catalog template identifier.
    - `scopedIso2` string: Empty means all countries in the manifest.
    - `coverage` WorldmonitorScenarioV1ScenarioCoverage
      - `status` string: complete, partial, or unknown. Complete refers to the bounded manifest only.
      - `countryIds` string[]
      - `hs2Codes` string[]
      - `records` WorldmonitorScenarioV1ScenarioCoverageRecord[]
        - `iso2` string: Requested 2-letter ISO country code; paired with hs2 as the record reference.
        - `hs2` string: Requested 2-digit HS chapter; paired with iso2 as the record reference.
        - `state` string: evaluated, missing, malformed, incomplete_routes, or not_seeded. incomplete_routes means the cached record was well-formed but did not carry an entry for every chokepoint this scenario disrupts — seeder/template registry drift, NOT corrupt cache data.
        - `basis` string: flow_weighted or country_route_fallback, only for evaluated records.
        - `rawImpact` number, double: Relative score units, not currency. Present only for evaluated records.
        - `fetchedAt` string: Cache production time. Observation date is unknown unless separately supplied.
      - `manifestFetchedAt` string: Seed metadata production time, not trade observation time.
    - `computedAt` string: Computation time, not source observation time.
  - `error` string: Populated only when status == "failed".

## Other responses

- `400`: Validation error
- `401`: Missing or invalid API key.
- `403`: PRO entitlement access denied.
- `429`: Rate limit exceeded.
- `503`: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
- `default`: Gateway or handler error response.

---

[API](https://skmtc.dev/worldmonitor/apis/worldmonitor-api.md) · [All operations](https://skmtc.dev/worldmonitor/apis/worldmonitor-api/llms.txt) · [OpenAPI document](https://skmtc.dev/worldmonitor/apis/worldmonitor-api/revisions/e3dc8463a5c9?raw)