> ## 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. # 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. ## OpenAPI ````yaml /api-reference/openapi.documented.json post /v1/simulation/plan 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: post: tags: - Simulation Run Plan summary: Create a run plan description: >- 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. operationId: postV1SimulationPlan requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateRunPlanInput' responses: '201': description: The created run plan content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CreateRunPlanResponse' 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 '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 '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.create({ agentEndpoints: [{ id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' }], direction: 'INBOUND', maxSimulationDurationSeconds: 300, metrics: [{}], name: 'My Run Plan', }); 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.create( agent_endpoints=[{ "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }], direction="INBOUND", max_simulation_duration_seconds=300, metrics=[{}], name="My Run Plan", ) print(simulation_run_plan.data) components: schemas: CreateRunPlanInput: type: object properties: name: type: string minLength: 1 description: Name of the run plan example: My Run Plan 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`. includeFlowMetrics: type: boolean default: true description: >- 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: type: boolean default: true description: >- 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: type: boolean default: false description: >- 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: type: boolean default: false deprecated: true description: >- 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 required: - name - direction - maxSimulationDurationSeconds - agentEndpoints - metrics additionalProperties: false description: Input for creating a new simulation run plan CreateRunPlanResponse: type: object properties: runPlan: $ref: '#/components/schemas/RunPlanResponse' runPlanJob: oneOf: - $ref: '#/components/schemas/RunSimulationPlanResponse' - type: 'null' description: The triggered job, only present if autoRun was true required: - runPlan description: Response when creating a run plan, optionally including a triggered job 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 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 RunSimulationPlanResponse: type: object properties: simulationRunPlanId: type: string format: uuid description: ID of the simulation run plan that was executed simulationRunPlanJobId: type: string format: uuid description: ID of the simulation run plan job that was created status: type: string enum: - PENDING - QUEUED - CREATING_SNAPSHOTS - CREATING_SIMULATIONS - PREPARING_CAPACITY - RUNNING_SIMULATIONS - COMPLETED - FAILED - TIMED_OUT - CANCELLED - CANCELLING - ENDING_SIMULATIONS description: Initial status of the job createdAt: type: string description: When the job was created required: - simulationRunPlanId - simulationRunPlanJobId - status - createdAt description: Response when triggering a simulation run plan example: simulationRunPlanId: 9a8b7c6d-5e4f-3210-abcd-ef9876543210 simulationRunPlanJobId: 7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f status: PENDING createdAt: '2024-01-15T10:30:00Z' 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 ````