ROroarkhq
Simulation Run Plan

Update a run plan

Changed on

Updates an existing simulation run plan by its ID.

put/v1/simulation/plan/{planId}

Request

  • Base URL
    https://api.roark.ai
  • URL
    https://api.roark.ai/v1/simulation/plan/{planId}
  • Auth
    HTTP bearer

Path parameters

planIdstring uuid required

The ID of the run plan to update

Request body

isHiddenboolean

Whether this plan is hidden from GET /v1/simulation/plan.

A run started without saveAsPlan creates a hidden plan to carry it. Send { "name": "...", "isHidden": false } to keep that configuration as a reusable plan, which is what the app does when you save a one-off run.

namestring

Name of the run plan

descriptionstring

Description of the run plan

direction'INBOUND' | 'OUTBOUND'

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

Maximum duration in seconds for each simulation

silenceTimeoutSecondsinteger

Timeout in seconds for silence detection

maxNoResponseRetriesinteger

How many more times to run a test case when the agent under test never responds: it never speaks on a call or never replies in a chat (0-10). 0 turns retries off. Failed checks and failures on Roark’s side are never retried.

Each retry is a separate attempt, billed like any other, so a plan retrying N times can place up to N + 1 calls per test case. Every silent attempt stays on the run with its own call; the run settles once each test case has a final attempt, and the agent never spoke verdict is judged on each test case’s last attempt.

noResponseRetryBackoffSecondsinteger

Seconds a retry waits before it dials (30-600). Only used when maxNoResponseRetries is above 0.

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

Whether to merge the customer's own live recording into each simulation of this plan.

includeFlowMetricsboolean

Whether to also collect each attached flow's own metrics, on top of this plan's list.

includeAutomaticMetricsboolean

Whether to let the run add metrics by itself off the attached flows. See POST /v1/simulation/plan.

comparisonProperty'ACCENT' | 'AGE' | 'BACKGROUND_NOISE' | 'BACKGROUND_NOISE_VOLUME' | 'BASE_EMOTION' | 'CONFIRMATION_STYLE' | 'GENDER' | 'INTENT_CLARITY' | 'LANGUAGE' | 'INTERRUPTION' | 'MEMORY_RELIABILITY' | 'RESPONSE_TIMING' | 'SPEECH_CLARITY' | 'SPEECH_PACE' nullable

The property this plan investigates. Send null to clear the comparison; omit the field to leave it unchanged. See POST /v1/simulation/plan.

The pair moves together. Sending comparisonProperty without comparisonBaseline keeps the stored baseline when the property is unchanged and the baseline is still one of the values being run. Otherwise it becomes the new property's norm, or null when that norm is not being run either, because a baseline is a value of one specific property.

comparisonBaselinestring nullable

The reference value, shown first in the results. See POST /v1/simulation/plan.

A real value cannot be sent on its own: the property it belongs to decides which values are legal, and an omitted property means "leave unchanged", which this endpoint cannot check a baseline against. Send comparisonProperty with it, or get a 400.

null on its own IS allowed, and clears just the baseline while leaving the property set. Nothing needs validating when clearing, and a property with no baseline is a real state: the report falls back to that property's own norm, and GENDER has no norm to fall back to.

Example request

{
  "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"
          }
        }
      ]
    }
  ],
  "metrics": [
    {
      "minPassRate": 80
    }
  ],
  "comparisonValues": [
    "NONE",
    {
      "value": "OFFICE",
      "backgroundNoiseVolume": 0.6
    },
    {
      "value": "DRIVING",
      "backgroundNoiseVolume": 0.7
    },
    {
      "value": "DRIVING",
      "backgroundNoiseVolume": 1
    }
  ],
  "notifications": {
    "email": {
      "enabled": true,
      "recipients": []
    },
    "slack": [
      {
        "channelId": "C07ABCDEF12",
        "channelName": "qa-reports"
      }
    ]
  }
}

Response

The updated run plan

Example response

{
  "data": {
    "template": "accent-handling",
    "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"
            }
          }
        ]
      }
    ]
  }
}

Changes

  • 1e3d72699f2aRevision changes
    • info

      added the new optional request property

    • info

      added the required property / to the response with the status

  • e7b6b5cc7fa6Revision changes
    • breaking

      the / request property type changed from string to no type

    • info

      added subschema #1 to the / request property anyOf list

    • info

      added the required property / to the response with the status