> ## 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. # Run a simulation > Runs a simulation and returns the run that was started. Describe the simulation in `plan`, or name an existing one with `planId`. Every run is backed by a run plan, but you only get one you can see and re-use if you ask for it with `saveAsPlanName`; otherwise the plan is created hidden and simply carries the run. This replaces creating a plan and then starting a job against it. The response carries `simulationJobCount`, the number of calls the run places, each of which is billed. ## OpenAPI ````yaml /api-reference/openapi.documented.json post /v1/simulation/run 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: Simulation - name: Simulation Persona - name: Simulation Environment - name: Simulation Customer Flow - name: Simulation Customer Flow Variant - name: Simulation Scenario - name: Simulation Run Plan - name: Simulation Run Plan Job - name: Simulation Job - name: HTTP Request Definition - name: Webhook - name: Issue - name: Knowledge Base - name: Call Analysis - name: Health paths: /v1/simulation/run: post: tags: - Simulation summary: Run a simulation description: >- Runs a simulation and returns the run that was started. Describe the simulation in `plan`, or name an existing one with `planId`. Every run is backed by a run plan, but you only get one you can see and re-use if you ask for it with `saveAsPlanName`; otherwise the plan is created hidden and simply carries the run. This replaces creating a plan and then starting a job against it. The response carries `simulationJobCount`, the number of calls the run places, each of which is billed. operationId: postV1SimulationRun requestBody: content: application/json: schema: $ref: '#/components/schemas/RunSimulationInput' responses: '200': description: The run that was started content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/RunSimulationResponse' 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 '402': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Insufficient credit example: type: payment_required code: insufficient_credits message: >- Not enough credit to start this work. Add credit and try again. description: Payment Required '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Permission error example: type: forbidden code: permission_denied message: You do not have permission to access this resource description: Forbidden '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 '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 response = await client.simulation.run(); console.log(response.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 ) response = client.simulation.run() print(response.data) components: schemas: RunSimulationInput: type: object properties: plan: $ref: '#/components/schemas/InlineRunPlanConfig' description: >- The simulation to run. A run plan is created for it behind the scenes. planId: type: string format: uuid description: >- Run a plan that already exists instead of describing one. Mutually exclusive with `plan`. saveAsPlanName: type: string minLength: 1 description: >- Keep this run as a reusable plan under this name. Left unset, the run still needs a plan to execute, but it is created hidden: it does not appear in GET /v1/simulation/plan and exists only to carry the run. Applies only alongside `plan`, since `planId` names a plan that already exists. example: Billing regression variables: anyOf: - type: object additionalProperties: type: string description: >- Global format: key-value pairs that apply to ALL scenarios in the plan example: orderNumber: '12345' environment: staging - type: array items: type: object properties: scenarioId: type: string format: uuid description: ID of the scenario to apply variables to variables: type: object additionalProperties: type: string description: Key-value pairs for this scenario required: - scenarioId - variables description: >- Scenario-specific format: an array of objects, each with a scenarioId and its variable key-value pairs example: - scenarioId: 550e8400-e29b-41d4-a716-446655440000 variables: orderNumber: '12345' - scenarioId: 7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e variables: orderNumber: '67890' description: >- Runtime variables that override the values defined on the plan. Accepts one of two formats: Option 1, global (a flat key-value object): { "orderNumber": "12345", "environment": "staging" } Option 2, per-scenario (an array of objects with scenarioId + variables): [ { "scenarioId": "550e8400-...", "variables": { "orderNumber": "12345" } }, { "scenarioId": "7a3d2e1f-...", "variables": { "orderNumber": "67890" } } ] On a flow-based plan the global format applies to every variant the run resolves. The per-scenario format targets scenarios, so use `flowVariables` to override a specific flow or variant instead. flowVariables: type: array items: type: object properties: flowId: type: string format: uuid description: ID of a customer flow attached to this plan variantId: type: string format: uuid description: >- Target a single variant. Omit to apply to every variant this plan runs for the flow. variables: type: object additionalProperties: type: string description: Key-value pairs to apply required: - flowId - variables description: >- Runtime variable overrides targeted at the plan’s customer flows, taking precedence over the values pinned on the flow attachment. An entry without `variantId` applies to every variant the attachment resolves. A flow that is not attached to this plan, or a variant that does not belong to the flow, is rejected rather than ignored. example: - flowId: 550e8400-e29b-41d4-a716-446655440000 variables: orderNumber: '12345' - flowId: 550e8400-e29b-41d4-a716-446655440000 variantId: 7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e variables: orderNumber: '67890' description: >- Input for running a simulation, either from an inline configuration or an existing plan. RunSimulationResponse: type: object properties: simulationRunPlanJobId: type: string format: uuid description: The run. Poll it with GET /v1/simulation/plan/job/{jobId}. status: type: string enum: - PENDING - QUEUED - CREATING_SNAPSHOTS - CREATING_SIMULATIONS - RUNNING_SIMULATIONS - COMPLETED - FAILED - TIMED_OUT - CANCELLED - CANCELLING - ENDING_SIMULATIONS description: >- Initial status. PENDING normally, or QUEUED when the plan runs sequentially and another job of its is still active. createdAt: type: string description: When the run was created, ISO 8601. simulationRunPlanId: type: string format: uuid description: >- The run plan behind this run, present whether or not it was saved. Pass it back as `planId` to run the same configuration again. savedAsPlan: type: boolean description: >- Whether that plan is listed by GET /v1/simulation/plan. False for an unsaved run, whose plan is hidden. simulationJobCount: type: integer description: How many simulated calls this run places. Each is billed. required: - simulationRunPlanJobId - status - createdAt - simulationRunPlanId - savedAsPlan - simulationJobCount description: A started simulation run. 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 InlineRunPlanConfig: type: object properties: description: type: string description: Description of the run plan example: A run plan for testing inbound calls direction: type: string enum: - INBOUND - OUTBOUND description: Direction of the simulation (INBOUND or OUTBOUND) example: INBOUND iterationCount: type: integer minimum: 1 maximum: 10000 default: 1 description: Number of iterations to run for each test case (1-10000) example: 1 maxConcurrentJobs: type: integer minimum: 1 default: 5 description: Maximum number of concurrent simulation jobs example: 5 maxSimulationDurationSeconds: type: integer minimum: 1 description: Maximum duration in seconds for each simulation example: 300 silenceTimeoutSeconds: type: integer minimum: 1 default: 30 description: Timeout in seconds for silence detection example: 30 endCallPhrases: type: array items: type: string default: - goodbye description: Phrases that trigger end of call. Empty array disables the feature. example: - goodbye endCallReasons: type: array items: type: string default: [] description: >- 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: type: string enum: - PARALLEL - SEQUENTIAL_SAME_RUN_PLAN - SEQUENTIAL_PROJECT default: PARALLEL description: Execution mode (PARALLEL or SEQUENTIAL) example: PARALLEL 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 minItems: 1 deprecated: true description: >- Deprecated: use `flows` instead. Scenarios to include in this run plan. The same scenario ID can appear multiple times with different variables. flows: type: array items: $ref: '#/components/schemas/RunPlanFlowSelection' minItems: 1 description: >- Customer flows to include in this run plan. The same flow can appear more than once with a different persona override or different variables. personas: type: array items: type: object properties: id: type: string format: uuid required: - id minItems: 1 description: >- Personas to include in this run plan. Required with `scenarios`; ignored with `flows`, where each variant carries its own persona. 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`. required: - direction - maxSimulationDurationSeconds - agentEndpoints - metrics description: >- A simulation to configure and run. Identical to the create-run-plan body without its `name`. RunPlanFlowSelection: type: object properties: customerFlowId: type: string format: uuid variantSelectionMode: type: string enum: - ALL_VARIANTS - DEFAULT_VARIANT - SPECIFIC_VARIANT variants: type: array items: type: object properties: id: type: string format: uuid personaOverrideId: type: - string - 'null' format: uuid variables: type: object additionalProperties: type: string required: - id default: [] personaOverrideId: type: - string - 'null' format: uuid variables: type: object additionalProperties: type: string required: - customerFlowId - variants description: >- One customer flow attached to a run plan. To run specific variants, list them in `variants`. Each entry may carry its own `personaOverrideId` and `variables`, so pinning two variants of one flow at different values is a single attachment. To let the run resolve the variants instead, leave `variants` out and set `variantSelectionMode`: ALL_VARIANTS: every variant the flow has when the run starts DEFAULT_VARIANT: only its default, so it follows the flow as the default moves There is no default mode. Each variant is a separate simulated call, so a forgotten field would quietly change how many calls a run places. `personaOverrideId` runs a variant as that persona instead of its own. Set it on the attachment to apply to every variant it resolves, or on a `variants` entry for one. The entry wins. Attaching the same flow more than once with different overrides is how you fan it out across personas. `variables` pins {{variable}} values the same way. Anything left unset is asked for when the run starts. example: customerFlowId: 550e8400-e29b-41d4-a716-446655440000 variants: - id: 7c9e6679-7425-40de-944b-e07fc1f90ae7 variables: tier: premium - id: 9f8c7b6a-5d4e-4c3b-8a29-1e0f2d3c4b5a variables: tier: basic 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. securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ````