Sign in
Simulation Run Plan

Create a run plan

Creates a new simulation run plan.

To run a simulation, use POST /v1/simulation/run instead: it starts a run from a plan or from an inline configuration, and takes runtime variables. Create a plan here when you want a reusable, named one to run later.

post/v1/simulation/plan

Request body

namestring required

Name of the run plan

descriptionstring

Description of the run plan

direction'INBOUND' | 'OUTBOUND' required

Direction of the simulation (INBOUND or OUTBOUND)

iterationCountinteger

Number of iterations to run for each test case (1-10000)

maxConcurrentJobsinteger

Maximum number of concurrent simulation jobs

maxSimulationDurationSecondsinteger required

Maximum duration in seconds for each simulation

silenceTimeoutSecondsinteger

Timeout in seconds for silence detection

endCallPhrasesstring[]

Phrases that trigger end of call. Empty array disables the feature.

endCallReasonsstring[]

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)

enrichWithLiveConversationboolean

Merge the customer's own recording of the real call into each simulation, so metrics can be scored against the live leg as well as the simulated one. This is the API equivalent of the dashboard's live-enrichment toggle.

With this on, the run provisions a phone number and holds each call open for up to 15 minutes waiting for a matching call to be posted to POST /v1/call. A call matches on the provisioned number (roarkPhoneNumber on the job) with a start time inside the simulation window. If nothing arrives, the simulation still completes and any LIVE-sourced metric produces no value.

Required by any metric whose requiresLiveConversation is true: without it that metric is silently skipped.

autoRunboolean

Deprecated: use POST /v1/simulation/run, which starts a run and accepts runtime variables as well. This flag runs the plan with only the values pinned on it.

Example request

{
  "name": "My Run Plan",
  "description": "A run plan for testing inbound calls",
  "direction": "INBOUND",
  "iterationCount": 1,
  "maxConcurrentJobs": 5,
  "maxSimulationDurationSeconds": 300,
  "silenceTimeoutSeconds": 30,
  "endCallPhrases": [
    "goodbye"
  ],
  "endCallReasons": [
    "Order has been confirmed by the agent"
  ],
  "executionMode": "PARALLEL",
  "scenarios": [
    {
      "variables": {
        "customerName": "John Doe",
        "appointmentDate": "2024-02-15"
      }
    }
  ],
  "flows": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "happyPath": true,
      "edgeCases": [
        {
          "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
          "variables": {
            "tier": "premium"
          }
        }
      ]
    }
  ]
}

Response

The created run plan

Example response

{
  "data": {
    "runPlan": {
      "scenarios": [
        {
          "variables": {
            "customerName": "John Doe",
            "appointmentDate": "2024-02-15"
          }
        }
      ],
      "flows": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "happyPath": true,
          "edgeCases": [
            {
              "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
              "variables": {
                "tier": "premium"
              }
            }
          ]
        }
      ]
    },
    "runPlanJob": {
      "simulationRunPlanId": "9a8b7c6d-5e4f-3210-abcd-ef9876543210",
      "simulationRunPlanJobId": "7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f",
      "status": "PENDING",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  }
}

Changes