> ## 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. # List run plans > Returns a paginated list of simulation run plans. Optionally filter by search text or agent ID. ## OpenAPI ````yaml /api-reference/openapi.documented.json get /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: Benchmark - name: Health paths: /v1/simulation/plan: get: tags: - Simulation Run Plan summary: List run plans description: >- Returns a paginated list of simulation run plans. Optionally filter by search text or agent ID. operationId: getV1SimulationPlan parameters: - in: query name: limit schema: type: integer minimum: 1 maximum: 50 default: 20 description: 'Maximum number of run plans to return (default: 20, max: 50)' example: 20 - in: query name: after schema: type: string description: >- Cursor for pagination - use the nextCursor value from a previous response - in: query name: searchText schema: type: string description: Search text to filter run plans by name - in: query name: agentId schema: type: string format: uuid description: Filter run plans by agent ID responses: '200': description: Paginated list of run plans content: application/json: schema: $ref: '#/components/schemas/GetRunPlansResponse' '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 simulationRunPlans = await client.simulationRunPlan.list(); console.log(simulationRunPlans.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_plans = client.simulation_run_plan.list() print(simulation_run_plans.data) components: schemas: GetRunPlansResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/RunPlanResponse' pagination: type: object properties: total: type: number description: Total number of items hasMore: type: boolean description: Whether there are more items to fetch nextCursor: type: - string - 'null' description: Cursor for the next page of items required: - total - hasMore - nextCursor required: - data - pagination description: Paginated list of simulation run plans 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 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. minPassRate: type: - number - 'null' description: >- THE BAR. The share of the run's simulations (0-100) that must pass this check. `null` means the 80% default. required: - id - conversationSource - minPassRate 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 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 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 ````