> ## 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 group > Groups several simulation runs so they read as one, and starts generating the group report: one document across every run, with a scorecard summed across them and the issues found, each merged from the per-run debriefs. Send `simulationRunPlanJobIds` to group runs that already exist (runs still in progress are fine: the report waits for them). Send `simulationRunPlanIds` to start one run of each plan and group those; this places real calls, exactly as starting each plan would. Poll GET /v1/simulation/run-group/{groupId} until `latestReport.status` is READY. ## OpenAPI ````yaml /api-reference/openapi.documented.json post /v1/simulation/run-group 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: Autoimprove - name: Agent Config - name: Knowledge Base - name: Config - name: Organization Project - name: Organization Project Member - name: Organization Project API Key - name: Organization Config - name: CLI Auth - name: Me - name: Project - name: Usage - name: Benchmark - name: Health - name: Prospect Simulation paths: /v1/simulation/run-group: post: tags: - Simulation summary: Create a run group description: >- Groups several simulation runs so they read as one, and starts generating the group report: one document across every run, with a scorecard summed across them and the issues found, each merged from the per-run debriefs. Send `simulationRunPlanJobIds` to group runs that already exist (runs still in progress are fine: the report waits for them). Send `simulationRunPlanIds` to start one run of each plan and group those; this places real calls, exactly as starting each plan would. Poll GET /v1/simulation/run-group/{groupId} until `latestReport.status` is READY. operationId: postV1SimulationRun-group requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateSimulationRunGroupInput' responses: '201': description: The run group, with its report requested content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/SimulationRunGroup' 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: A run or plan was not found in this project '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 simulationRunGroup = await client.simulationRunGroup.create(); console.log(simulationRunGroup.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_group = client.simulation_run_group.create() print(simulation_run_group.data) components: schemas: CreateSimulationRunGroupInput: type: object properties: name: type: string minLength: 1 maxLength: 200 description: >- What to call the group. Defaults to the plans' names when starting plans, and to the runs' plan names when grouping existing runs. example: Release 4.2 regression simulationRunPlanJobIds: type: array items: type: string format: uuid minItems: 2 maxItems: 20 description: >- Runs that already exist, in display order (2 to 20). Runs still in progress are fine: the group report waits for them. Send this or `simulationRunPlanIds`, not both. example: - 7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f - 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d simulationRunPlanIds: type: array items: type: string format: uuid minItems: 2 maxItems: 20 description: >- Plans to run once each, in display order (2 to 20). Each plan starts a run, exactly as POST /v1/simulation/plan/{planId}/job would. Send this or `simulationRunPlanJobIds`, not both. example: - 7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f - 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d additionalProperties: false description: Group existing runs, or start one run per plan and group those. example: name: Release 4.2 regression simulationRunPlanIds: - 3c1d2e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f - 6d7e8f9a-0b1c-4d2e-9f3a-4b5c6d7e8f9a SimulationRunGroup: type: object properties: id: type: string format: uuid name: type: string createdAt: type: string description: ISO 8601 runCount: type: integer runs: type: array items: $ref: '#/components/schemas/SimulationRunGroupRun' latestReport: oneOf: - $ref: '#/components/schemas/SimulationRunGroupReport' - type: 'null' description: >- The latest group report in any status. Null when none has been requested. required: - id - name - createdAt - runCount - runs - latestReport description: Several simulation runs read as one. 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 SimulationRunGroupRun: type: object properties: simulationRunPlanJobId: type: string format: uuid description: The run, readable at GET /v1/simulation/plan/job/{jobId} simulationRunPlanId: type: string format: uuid planName: type: - string - 'null' description: The name of the plan the run ran. Null when the plan was deleted. runNumber: type: - integer - 'null' description: Per-project run number, shown as SR-42 in the app. status: type: string enum: - PENDING - QUEUED - CREATING_SNAPSHOTS - CREATING_SIMULATIONS - PREPARING_CAPACITY - RUNNING_SIMULATIONS - COMPLETED - FAILED - TIMED_OUT - CANCELLED - CANCELLING - ENDING_SIMULATIONS createdAt: type: string description: ISO 8601 startedAt: type: - string - 'null' endedAt: type: - string - 'null' required: - simulationRunPlanJobId - simulationRunPlanId - planName - runNumber - status - createdAt - startedAt - endedAt description: One run in the group, in group order. SimulationRunGroupReport: type: object properties: id: type: string format: uuid status: type: string enum: - PENDING - GENERATING - READY - FAILED description: >- PENDING and GENERATING are in flight; READY carries the document; FAILED carries errorMessage. errorMessage: type: - string - 'null' createdAt: type: string description: ISO 8601 completedAt: type: - string - 'null' description: ISO 8601. Null until the report settles. document: oneOf: - $ref: '#/components/schemas/SimulationRunGroupReportDocument' - type: 'null' description: Null until the report is READY. required: - id - status - errorMessage - createdAt - completedAt - document description: One generation of the group report. SimulationRunGroupReportDocument: type: object properties: version: type: number const: 1 generatedAtIso: type: string model: type: string simulationRunGroupId: type: string headline: type: object properties: groupName: type: string runCount: type: integer reportedRunCount: type: integer passedRunCount: type: integer callCount: type: integer verdict: type: string enum: - PASSED - THRESHOLD_FAILED completedAtIso: type: - string - 'null' verdictProse: type: string statTiles: type: array items: type: object properties: label: type: string value: type: string sub: type: - string - 'null' deltaDirection: type: - string - 'null' enum: - POSITIVE - NEGATIVE - NEUTRAL required: - label - value - sub - deltaDirection required: - groupName - runCount - reportedRunCount - passedRunCount - callCount - verdict - completedAtIso - verdictProse - statTiles runs: type: array items: type: object properties: simulationRunPlanJobId: type: string runLabel: type: string runNumber: type: - integer - 'null' status: type: string enum: - PENDING - QUEUED - CREATING_SNAPSHOTS - CREATING_SIMULATIONS - PREPARING_CAPACITY - RUNNING_SIMULATIONS - COMPLETED - FAILED - TIMED_OUT - CANCELLED - CANCELLING - ENDING_SIMULATIONS verdict: type: - string - 'null' enum: - PASSED - THRESHOLD_FAILED callCount: type: integer checksPassed: type: integer checksTotal: type: integer themeCount: type: integer completedAtIso: type: - string - 'null' summary: type: - string - 'null' required: - simulationRunPlanJobId - runLabel - runNumber - status - verdict - callCount - checksPassed - checksTotal - themeCount - completedAtIso - summary executiveSummary: type: array items: type: object properties: heading: type: string body: type: string required: - heading - body scorecard: type: array items: type: object properties: checkName: type: string runCount: type: integer failedRunCount: type: integer failedCount: type: integer evaluatedCount: type: integer passRatePct: type: - number - 'null' required: - checkName - runCount - failedRunCount - failedCount - evaluatedCount - passRatePct wentWell: type: array items: type: object properties: title: type: string body: type: string evidence: type: array items: type: object properties: text: type: string simulationRunPlanJobId: type: string conversationId: type: string callId: type: - string - 'null' personaName: type: - string - 'null' cueMs: type: - integer - 'null' required: - text - simulationRunPlanJobId - conversationId - callId - personaName - cueMs required: - title - body - evidence issues: type: array items: type: object properties: order: type: integer title: type: string body: type: string severity: type: string enum: - HIGH - MEDIUM - LOW rootCauseChannel: type: - string - 'null' enum: - PROMPT - VOICE_CONFIG - STT - SPEECH_MODEL - LLM_MODEL - INFRA - EXTERNAL affectedCallCount: type: integer runLabels: type: array items: type: string checkNames: type: array items: type: string sourceThemes: type: array items: type: object properties: simulationRunPlanJobId: type: string slug: type: string required: - simulationRunPlanJobId - slug evidence: type: array items: type: object properties: text: type: string simulationRunPlanJobId: type: string conversationId: type: string callId: type: - string - 'null' personaName: type: - string - 'null' cueMs: type: - integer - 'null' required: - text - simulationRunPlanJobId - conversationId - callId - personaName - cueMs calls: type: array items: type: object properties: simulationRunPlanJobId: type: string conversationId: type: string callId: type: - string - 'null' personaName: type: - string - 'null' cueMs: type: - integer - 'null' required: - simulationRunPlanJobId - conversationId - callId - personaName - cueMs required: - order - title - body - severity - rootCauseChannel - affectedCallCount - runLabels - checkNames - sourceThemes - evidence - calls smallerItems: type: array items: type: object properties: order: type: integer title: type: string body: type: string severity: type: string enum: - HIGH - MEDIUM - LOW rootCauseChannel: type: - string - 'null' enum: - PROMPT - VOICE_CONFIG - STT - SPEECH_MODEL - LLM_MODEL - INFRA - EXTERNAL affectedCallCount: type: integer runLabels: type: array items: type: string checkNames: type: array items: type: string sourceThemes: type: array items: type: object properties: simulationRunPlanJobId: type: string slug: type: string required: - simulationRunPlanJobId - slug evidence: type: array items: type: object properties: text: type: string simulationRunPlanJobId: type: string conversationId: type: string callId: type: - string - 'null' personaName: type: - string - 'null' cueMs: type: - integer - 'null' required: - text - simulationRunPlanJobId - conversationId - callId - personaName - cueMs calls: type: array items: type: object properties: simulationRunPlanJobId: type: string conversationId: type: string callId: type: - string - 'null' personaName: type: - string - 'null' cueMs: type: - integer - 'null' required: - simulationRunPlanJobId - conversationId - callId - personaName - cueMs required: - order - title - body - severity - rootCauseChannel - affectedCallCount - runLabels - checkNames - sourceThemes - evidence - calls recommendations: type: array items: type: object properties: order: type: integer title: type: string body: type: string channel: type: - string - 'null' enum: - PROMPT - VOICE_CONFIG - STT - SPEECH_MODEL - LLM_MODEL - INFRA - EXTERNAL issueOrders: type: array items: type: integer required: - order - title - body - channel - issueOrders aggregates: type: array items: type: object properties: metricName: type: string averageLabel: type: - string - 'null' medianLabel: type: - string - 'null' p95Label: type: - string - 'null' evaluatedCount: type: integer required: - metricName - averageLabel - medianLabel - p95Label - evaluatedCount methodology: type: string required: - version - generatedAtIso - model - simulationRunGroupId - headline - runs - executiveSummary - scorecard - wentWell - issues - smallerItems - recommendations - aggregates - methodology description: >- The group report: the runs it covers, a scorecard summed across them, what went well, and the issues found, each merged from the per-run debriefs with call-level evidence. Every figure is computed from the runs; the prose is AI-written around those facts. securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.