---
title: "Create a run plan"
method: POST
path: "/v1/simulation/plan"
tags: ["Simulation Run Plan"]
---

# Create a run plan

`POST /v1/simulation/plan`

Creates a new simulation run plan. Optionally triggers a job immediately if autoRun is true.

## Request body

- CreateRunPlanInput — Input for creating a new simulation run plan
  - `name` string, required — Name of the run plan
  - `description` string — Description of the run plan
  - `direction` 'INBOUND' | 'OUTBOUND', required — Direction of the simulation (INBOUND or OUTBOUND)
  - `iterationCount` integer — Number of iterations to run for each test case. Must be 1 for OUTBOUND direction.
  - `maxConcurrentJobs` integer — Maximum number of concurrent simulation jobs
  - `maxSimulationDurationSeconds` integer, required — Maximum duration in seconds for each simulation
  - `silenceTimeoutSeconds` integer — Timeout in seconds for silence detection
  - `endCallPhrases` string[] — Phrases that trigger end of call. Empty array disables the feature.
  - `endCallReasons` string[] — Semantic conditions that trigger end of call. The LLM evaluates the conversation against these conditions. Empty array disables the feature.
  - `executionMode` 'PARALLEL' | 'SEQUENTIAL_SAME_RUN_PLAN' | 'SEQUENTIAL_PROJECT' — Execution mode (PARALLEL or SEQUENTIAL)
  - `scenarios` object[], required — Scenarios to include in this run plan. The same scenario ID can appear multiple times with different variables.
    - `id` string, uuid, required — Scenario ID
    - `variables` object — Template variables for this scenario instance. The same scenario can appear multiple times with different variables.
  - `personas` object[], required — Personas to include in this run plan
    - `id` string, uuid, required
  - `agentEndpoints` object[], required — Agent endpoints to include in this run plan
    - `id` string, uuid, required
  - `metrics` object[], required — Metric definitions to include in this run plan
    - `id` string, uuid, required
  - `autoRun` boolean — Whether to automatically trigger a job after creating the run plan

## Response `201`

The created run plan

- object
  - `data` CreateRunPlanResponse, required — Response when creating a run plan, optionally including a triggered job
    - `runPlan` RunPlanResponse, required — A simulation run plan defining the test matrix
      - `id` string, uuid, required — Unique identifier of the run plan
      - `name` string, required — Name of the run plan
      - `description` string, nullable — Description of the run plan
      - `direction` 'INBOUND' | 'OUTBOUND', required — Direction of the simulation (INBOUND or OUTBOUND)
      - `iterationCount` integer, required — Number of iterations to run for each test case
      - `maxConcurrentJobs` integer, required — Maximum number of concurrent simulation jobs
      - `maxSimulationDurationSeconds` integer, required — Maximum duration in seconds for each simulation
      - `silenceTimeoutSeconds` integer, required — Timeout in seconds for silence detection
      - `endCallPhrases` string[], required — Phrases that trigger end of call. Empty array means disabled.
      - `endCallReasons` string[], required — Semantic conditions that trigger end of call. The LLM evaluates the conversation against these conditions. Empty array means disabled.
      - `executionMode` 'PARALLEL' | 'SEQUENTIAL_SAME_RUN_PLAN' | 'SEQUENTIAL_PROJECT', required — Execution mode (PARALLEL or SEQUENTIAL)
      - `scenarios` object[], required — Scenarios included in this run plan
        - `id` string, uuid, required
        - `variables` object — Template variables for this scenario instance. Absent when no variables are set. The same scenario can appear multiple times with different variables.
      - `personas` object[], required — Personas included in this run plan
        - `id` string, uuid, required
      - `agentEndpoints` object[], required — Agent endpoints included in this run plan
        - `id` string, uuid, required
      - `evaluators` object[], required — Deprecated: Use metrics instead. Evaluators included in this run plan.
        - `id` string, uuid, required
      - `metrics` object[], required — Metric definitions included in this run plan
        - `id` string, uuid, required
      - `testCaseCount` integer, required — Total number of test cases generated from the plan configuration
      - `createdAt` string, required — When the run plan was created
      - `updatedAt` string, required — When the run plan was last updated
    - `runPlanJob` RunSimulationPlanResponse — 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

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `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)