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

JavaScript

JavaScript

import Roark from '@roarkanalytics/sdk';

const client = new Roark({
  bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted
});

const simulationRunPlan = await client.simulationRunPlan.create({
  agentEndpoints: [{ id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' }],
  direction: 'INBOUND',
  maxSimulationDurationSeconds: 300,
  metrics: [{}],
  name: 'My Run Plan',
});

console.log(simulationRunPlan.data);

201

{
  "data": {
    "runPlan": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "isConfigManaged": true,
      "direction": "INBOUND",
      "iterationCount": 123,
      "maxConcurrentJobs": 123,
      "maxSimulationDurationSeconds": 123,
      "silenceTimeoutSeconds": 123,
      "endCallPhrases": [
        "<string>"
      ],
      "endCallReasons": [
        "<string>"
      ],
      "executionMode": "PARALLEL",
      "scenarios": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "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"
              }
            }
          ]
        }
      ],
      "personas": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
      ],
      "agentEndpoints": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
      ],
      "evaluators": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
      ],
      "metrics": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "conversationSource": "SIMULATED"
        }
      ],
      "enrichWithLiveConversation": true,
      "includeFlowMetrics": true,
      "includeAutomaticMetrics": true,
      "testCaseCount": 123,
      "createdAt": "<string>",
      "updatedAt": "<string>",
      "description": "<string>"
    },
    "runPlanJob": {
      "simulationRunPlanId": "9a8b7c6d-5e4f-3210-abcd-ef9876543210",
      "simulationRunPlanJobId": "7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f",
      "status": "PENDING",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Input for creating a new simulation run plan

name · string · required

Name of the run plan

Minimum string length: 1

Example:

"My Run Plan"

direction · enum<string> · required

Direction of the simulation (INBOUND or OUTBOUND)

Available options: INBOUND, OUTBOUND

Example:

"INBOUND"

maxSimulationDurationSeconds · integer · required

Maximum duration in seconds for each simulation

Required range: x >= 1

Example:

300

agentEndpoints · object[] · required

Agent endpoints to include in this run plan

Minimum array length: 1

Show child attributes

metrics · object[] · required

Metric definitions to include in this run plan. Reference each by id (UUID) or slug.

Minimum array length: 1

Show child attributes

description · string

Description of the run plan

Example:

"A run plan for testing inbound calls"

iterationCount · integer · default: 1

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

Required range: 1 <= x <= 10000

Example:

1

maxConcurrentJobs · integer · default: 5

Maximum number of concurrent simulation jobs

Required range: x >= 1

Example:

5

silenceTimeoutSeconds · integer · default: 30

Timeout in seconds for silence detection

Required range: x >= 1

Example:

30

endCallPhrases · string[]

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

Example:

["goodbye"]

endCallReasons · string[]

Semantic conditions that trigger end of call. The LLM evaluates the conversation against these conditions. Empty array disables the feature.

Example:

["Order has been confirmed by the agent"]

executionMode · enum<string> · default: PARALLEL

Execution mode (PARALLEL or SEQUENTIAL)

Available options: PARALLEL, SEQUENTIAL_SAME_RUN_PLAN, SEQUENTIAL_PROJECT

Example:

"PARALLEL"

scenarios · object[] · deprecated

Deprecated: use flows instead. Scenarios to include in this run plan. The same scenario ID can appear multiple times with different variables.

Minimum array length: 1

Show child attributes

flows · object[]

Customer flows to include in this run plan. The same flow can appear more than once with a different persona override or different variables.

Minimum array length: 1

Show child attributes

personas · object[]

Personas to include in this run plan. Required with scenarios; ignored with flows, where each variant carries its own persona.

Minimum array length: 1

Show child attributes

includeFlowMetrics · boolean · default: true

Also collect each attached flow's own metrics, on top of the metrics named here.

Default true, which is what you want when you brought your own flows and their graders. Set false for a run whose metric list is meant to be exhaustive: a template like Load Testing or Voicemail deliberately grades a narrow set, and inheriting every flow metric on top multiplies analysis cost across the volume without adding signal.

GET /v1/simulation/template returns the value each template expects.

Example:

true

includeAutomaticMetrics · boolean · default: true

Let the run add metrics by itself off the attached flows, on top of the metrics named here.

Two attach this way today: Agent Expectations wherever an attached flow has agent expectations written on it, and Keypad Entry wherever one has steps where the agent is expected to press keys. Both grade something authored on the flow that nothing else measures, which is why it is on by default.

Set false when the metrics list is meant to be exhaustive: a plan testing only whether the caller can complete the flow may not want the agent graded on its expectations as well. False also pins the plan against any automatic metric Roark adds later.

Example:

true

enrichWithLiveConversation · boolean · default: false

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.

Example:

false

autoRun · boolean · default: false · deprecated

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:

false

Response

201

application/json

The created run plan

data · object · required

Response when creating a run plan, optionally including a triggered job

Show child attributes