Skip to main content
POST
RunScenario

Authorizations

X-WorldMonitor-Key
string
header
required

User-issued WorldMonitor API key.

Headers

Idempotency-Key
string

Optional client-generated idempotency key. Retrying a POST with the same key and an identical request body replays the original response (only the status, body, and Content-Type are reproduced) instead of re-executing; reusing the key with a different body is rejected with 422. For mutations this avoids duplicating the side effect, while for batch-read POSTs it replays a cached snapshot that can be up to 24 hours stale. Keys are scoped per authenticated caller (falling back to the source IP for unauthenticated endpoints) and retained for 24 hours.

Required string length: 1 - 255
Pattern: ^[\x21-\x7E]{1,255}$

Body

application/json

RunScenarioRequest enqueues a scenario job on the scenario-queue:pending Upstash list for the async scenario-worker to pick up.

scenarioId
string
required

Scenario template id — must match an entry in SCENARIO_TEMPLATES.

Required string length: 1 - 128
iso2
string

Optional 2-letter ISO country code to scope the impact computation. When absent, v1 computes only the seeded reporter set: US, CN, RU, IR, IN, TW.

Pattern: ^([A-Z]{2})?$

Response

Accepted — scenario job enqueued. The body carries the job id (jobId), the initial status (always pending) and a poll URL (statusUrl); the Location header points at the same GetScenarioStatus endpoint. Poll it until status is done or failed.

RunScenarioResponse carries the enqueued job id. Clients poll GetScenarioStatus with this id until status != "pending".

NOTE: a successful enqueue returns HTTP 202 Accepted with a Location header pointing at GetScenarioStatus — the legacy (pre-sebuf) contract, restored. The sebuf-generated server still emits 200 for every success (no per-RPC status-code annotation exists), so the gateway upgrades the status via the setSuccessStatusOverride side-channel (server/_shared/response-headers.ts). Treat any 2xx as success; the interim guidance to branch on response body shape instead of the status code remains valid.

jobId
string

Generated job id of the form scenario:{epoch_ms}:{8-char-suffix}.

status
string

Always "pending" at enqueue time.

statusUrl
string

Convenience URL the caller can use to poll this job's status. Server-computed as /api/scenario/v1/get-scenario-status?jobId=<job_id>. Restored after the v1 → v1 sebuf migration because external callers may key off this field.