> ## Documentation Index > Fetch the complete documentation index at: https://docs.roark.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update a run plan > Updates an existing simulation run plan by its ID. ## OpenAPI ````yaml /api-reference/openapi.documented.json put /v1/simulation/plan/{planId} openapi: 3.1.0 info: title: Roark Analytics API description: >- The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform. version: 1.0.0 servers: - description: Production url: https://api.roark.ai security: - Bearer: [] tags: - name: Agent - name: Agent Endpoint - name: Call - name: Chat - name: Metric - name: Metric Policy - name: Metric Collection Job - name: Customer Flow - name: Customer Flow Edge Case - name: Simulation - name: Simulation Persona - name: Simulation Environment - name: Simulation Scenario - name: Simulation Run Plan - name: Simulation Template - name: Simulation Run Plan Job - name: Simulation Job - name: HTTP Request Definition - name: Webhook - name: Issue - name: Knowledge Base - name: Config - name: CLI Auth - name: Call Analysis - name: Health paths: /v1/simulation/plan/{planId}: put: tags: - Simulation Run Plan summary: Update a run plan description: Updates an existing simulation run plan by its ID. operationId: putV1SimulationPlanByPlanId parameters: - name: planId in: path required: true description: The ID of the run plan to update schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateRunPlanInput' responses: '200': description: The updated run plan content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/RunPlanResponse' required: - data '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Validation error example: type: validation code: invalid_parameter message: The request was invalid param: email description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication error example: type: authentication code: unauthorized message: Authentication required description: Unauthorized '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not found error example: type: not_found code: resource_not_found message: The requested resource could not be found description: Not Found '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Conflict error example: type: conflict code: resource_in_use message: The resource is in use and cannot be deleted description: Conflict '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Rate limit error example: type: rate_limit code: too_many_requests message: Rate limit exceeded description: Too Many Requests '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Server error example: type: internal code: internal_error message: Internal server error description: Internal Server Error x-codeSamples: - lang: JavaScript source: |- 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.update( '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', ); console.log(simulationRunPlan.data); - lang: Python source: |- import os from roark_analytics import Roark client = Roark( bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"), # This is the default and can be omitted ) simulation_run_plan = client.simulation_run_plan.update( plan_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", ) print(simulation_run_plan.data) components: schemas: UpdateRunPlanInput: type: object properties: isHidden: type: boolean description: >- 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. name: type: string minLength: 1 description: Name of the run plan description: type: string description: Description of the run plan direction: type: string enum: - INBOUND - OUTBOUND description: Direction of the simulation (INBOUND or OUTBOUND) iterationCount: type: integer minimum: 1 maximum: 10000 description: Number of iterations to run for each test case (1-10000) maxConcurrentJobs: type: integer minimum: 1 description: Maximum number of concurrent simulation jobs maxSimulationDurationSeconds: type: integer minimum: 1 description: Maximum duration in seconds for each simulation silenceTimeoutSeconds: type: integer minimum: 1 description: Timeout in seconds for silence detection endCallPhrases: type: array items: type: string description: Phrases that trigger end of call. Empty array disables the feature. endCallReasons: type: array items: type: string description: >- Semantic conditions that trigger end of call. The LLM evaluates the conversation against these conditions. Empty array disables the feature. executionMode: type: string enum: - PARALLEL - SEQUENTIAL_SAME_RUN_PLAN - SEQUENTIAL_PROJECT description: Execution mode (PARALLEL or SEQUENTIAL) scenarios: type: array items: type: object properties: id: type: string format: uuid description: Scenario ID variables: type: object additionalProperties: type: string description: >- Template variables for this scenario instance. The same scenario can appear multiple times with different variables. example: customerName: John Doe appointmentDate: '2024-02-15' required: - id deprecated: true description: >- Deprecated: use `flows` instead. Replaces the scenarios on this run plan. Omit to leave them unchanged; send an empty array to detach them all, which is how a scenario-based plan is moved over to flows. flows: type: array items: $ref: '#/components/schemas/RunPlanFlowSelection' description: >- Replaces the customer flows attached to this run plan. Omit to leave them unchanged; send an empty array to detach them all. personas: type: array items: type: object properties: id: type: string format: uuid required: - id minItems: 1 description: Personas to include in this run plan agentEndpoints: type: array items: type: object properties: id: type: string format: uuid required: - id minItems: 1 description: Agent endpoints to include in this run plan metrics: type: array items: $ref: '#/components/schemas/RunPlanMetricRef' minItems: 1 description: >- Metric definitions to include in this run plan. Reference each by `id` (UUID) or `slug`. enrichWithLiveConversation: type: boolean description: >- Whether to merge the customer's own live recording into each simulation of this plan. includeFlowMetrics: type: boolean description: >- Whether to also collect each attached flow's own metrics, on top of this plan's list. includeAutomaticMetrics: type: boolean description: >- Whether to let the run add metrics by itself off the attached flows. See `POST /v1/simulation/plan`. additionalProperties: false description: Input for updating an existing simulation run plan RunPlanResponse: type: object properties: id: type: string format: uuid description: Unique identifier of the run plan name: type: string description: Name of the run plan isConfigManaged: type: boolean description: >- Whether this plan is managed by config as code. A managed plan is reconciled from your config: PUT and DELETE on it return 409, and changes belong in the config file. description: type: - string - 'null' description: Description of the run plan direction: type: string enum: - INBOUND - OUTBOUND description: Direction of the simulation (INBOUND or OUTBOUND) iterationCount: type: integer description: Number of iterations to run for each test case maxConcurrentJobs: type: integer description: Maximum number of concurrent simulation jobs maxSimulationDurationSeconds: type: integer description: Maximum duration in seconds for each simulation silenceTimeoutSeconds: type: integer description: Timeout in seconds for silence detection endCallPhrases: type: array items: type: string description: Phrases that trigger end of call. Empty array means disabled. endCallReasons: type: array items: type: string description: >- Semantic conditions that trigger end of call. The LLM evaluates the conversation against these conditions. Empty array means disabled. executionMode: type: string enum: - PARALLEL - SEQUENTIAL_SAME_RUN_PLAN - SEQUENTIAL_PROJECT description: Execution mode (PARALLEL or SEQUENTIAL) scenarios: type: array items: type: object properties: id: type: string format: uuid variables: type: object additionalProperties: type: string description: >- Template variables for this scenario instance. Absent when no variables are set. The same scenario can appear multiple times with different variables. example: customerName: John Doe appointmentDate: '2024-02-15' required: - id deprecated: true description: >- Deprecated: use `flows` instead. Scenarios included in this run plan. flows: type: array items: $ref: '#/components/schemas/RunPlanFlowSelection' description: Customer flows included in this run plan personas: type: array items: type: object properties: id: type: string format: uuid required: - id description: >- Personas included in this run plan. Only meaningful alongside `scenarios`. agentEndpoints: type: array items: type: object properties: id: type: string format: uuid required: - id description: Agent endpoints included in this run plan evaluators: type: array items: type: object properties: id: type: string format: uuid required: - id description: >- Deprecated: Use metrics instead. Evaluators included in this run plan. metrics: type: array items: type: object properties: id: type: string format: uuid conversationSource: type: - string - 'null' enum: - SIMULATED - LIVE description: >- Which side of an enriched run this metric is scored on. `null` means the default, SIMULATED. required: - id - conversationSource description: Metric definitions included in this run plan enrichWithLiveConversation: type: boolean description: >- Whether this plan merges the customer's own live recording into each simulation. includeFlowMetrics: type: boolean description: >- Whether this plan also collects each attached flow's own metrics, on top of its own list. includeAutomaticMetrics: type: boolean description: >- Whether this plan lets a run add metrics by itself off the attached flows, on top of its own list. False means the `metrics` list is the whole answer. testCaseCount: type: integer description: Total number of test cases generated from the plan configuration createdAt: type: string description: When the run plan was created updatedAt: type: string description: When the run plan was last updated required: - id - name - isConfigManaged - direction - iterationCount - maxConcurrentJobs - maxSimulationDurationSeconds - silenceTimeoutSeconds - endCallPhrases - endCallReasons - executionMode - scenarios - flows - personas - agentEndpoints - evaluators - metrics - enrichWithLiveConversation - includeFlowMetrics - includeAutomaticMetrics - testCaseCount - createdAt - updatedAt description: A simulation run plan defining the test matrix ErrorResponse: type: object properties: type: type: string enum: - validation - authentication - forbidden - not_found - conflict - payment_required - rate_limit - internal description: The error type category examples: - validation - authentication code: type: string description: Machine-readable error code identifier examples: - invalid_parameter - missing_required_field - unauthorized message: type: string description: Human-readable error message examples: - The request was invalid - Authentication required param: type: string description: The parameter that caused the error (if applicable) examples: - email - user_id details: description: Additional error context information required: - type - code - message RunPlanFlowSelection: type: object properties: id: type: string format: uuid description: The customer flow to run. slug: type: string minLength: 1 description: >- The Roark-curated flow to run, by its stable slug. Use instead of `id` for a run you keep in version control: a curated flow’s id differs between deployments, its slug does not. Your own flows have no slug and are named by `id`. example: sf-prompt-injection happyPath: type: boolean description: >- Run the flow's happy path. Resolved when the run starts, so it follows the flow. edgeCases: anyOf: - type: string const: ALL - type: array items: $ref: '#/components/schemas/RunPlanEdgeCaseSelection' description: >- `"ALL"` runs every edge case the flow has when the run starts, so one added later is covered. An array runs only the ones you name, each able to carry its own persona override and values. personaOverrideId: type: - string - 'null' format: uuid description: >- Runs everything this attachment resolves as that persona instead of its own. variables: type: object additionalProperties: type: string description: Values for everything it resolves. example: customerName: John Doe appointmentDate: '2024-02-15' description: >- One customer flow attached to a run plan, and which of its ways of running you cover. Attaching the same flow more than once with different overrides is how you fan it out across personas or values. example: id: 550e8400-e29b-41d4-a716-446655440000 happyPath: true edgeCases: - id: 7c9e6679-7425-40de-944b-e07fc1f90ae7 variables: tier: premium RunPlanMetricRef: type: object properties: id: type: string format: uuid description: Metric definition UUID. Provide either this or `slug`, not both. slug: type: string minLength: 1 description: >- Stable metric slug (e.g. `customer_satisfaction`). Provide either this or `id`, not both. metricId: type: string minLength: 1 description: >- Alias of `slug` accepted for backwards compatibility. Use `slug` for new integrations. conversationSource: type: - string - 'null' enum: - SIMULATED - LIVE description: >- Which side of an enriched run this metric is scored on. Only meaningful with `enrichWithLiveConversation: true`, where a run has both a simulated conversation and the customer's own live recording of it. Defaults to `SIMULATED`. Use `LIVE` for a metric that must be measured against the real recording (audio quality, provider latency) rather than the simulated leg. `null` means the same as omitting it, so a plan read back from GET can be sent straight to PUT. additionalProperties: false RunPlanEdgeCaseSelection: type: object properties: id: type: string format: uuid description: The edge case to run. slug: type: string minLength: 1 description: >- The edge case to run, by its stable slug, matched within this flow. Use instead of `id` for a run you keep in version control: a curated edge case’s id differs between deployments and changes outright if it is renamed. Your own edge cases have no slug and are named by `id`. example: data-embedded-injection personaOverrideId: type: - string - 'null' format: uuid description: Run this one as that persona instead of its own. variables: type: object additionalProperties: type: string description: Values for this one only. example: customerName: John Doe appointmentDate: '2024-02-15' securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ````