---
title: "Run a simulation plan"
method: POST
path: "/v1/simulation/plan/{planId}/job"
tags: ["Simulation Run Plan Job"]
---

# Run a simulation plan

`POST /v1/simulation/plan/{planId}/job`

Create and execute a job for an existing simulation run plan. Optionally provide runtime variables to override plan-defined variables.

## Path parameters

- `planId` unknown, required

## Request body

- RunSimulationPlanBody — Optional request body for running a simulation plan with runtime variables
  - `variables` union — Runtime variables that override plan-defined scenario variables. Accepts one of two formats: Option 1 — Global (flat key-value object, applies to ALL scenarios): { "orderNumber": "12345", "environment": "staging" } Option 2 — Per-scenario (array of objects with scenarioId + variables): [ { "scenarioId": "550e8400-...", "variables": { "orderNumber": "12345" } }, { "scenarioId": "7a3d2e1f-...", "variables": { "orderNumber": "67890" } } ]
    - object — Global format: key-value pairs that apply to ALL scenarios in the plan
    - object[] — Scenario-specific format: an array of objects, each with a scenarioId and its variable key-value pairs
      - `scenarioId` string, uuid, required — ID of the scenario to apply variables to
      - `variables` object, required — Key-value pairs for this scenario

## Response `200`

Successfully triggered simulation run plan

- object
  - `data` RunSimulationPlanResponse, required — Response when triggering a simulation run plan
    - `simulationRunPlanId` string, uuid, required — ID of the simulation run plan that was executed
    - `simulationRunPlanJobId` string, uuid, required — ID of the simulation run plan job that was created
    - `status` 'PENDING' | 'QUEUED' | 'CREATING_SNAPSHOTS' | 'CREATING_SIMULATIONS' | 'RUNNING_SIMULATIONS' | 'COMPLETED' | 'FAILED' | 'TIMED_OUT' | 'CANCELLED' | 'CANCELLING' | 'ENDING_SIMULATIONS', required — Initial status of the job
    - `createdAt` string, required — When the job was created

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Simulation run plan not found
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.net/roarkhq/apis/roark-analytics-api.md) · [All operations](https://skmtc.net/roarkhq/apis/roark-analytics-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/roarkhq/roark-analytics-api/revisions/83528d3618ef/schema)