---
title: "Create a run group"
method: POST
path: "/v1/simulation/run-group"
tags: ["Simulation"]
---

# Create a run group

`POST /v1/simulation/run-group`

## Request

- Base URL: `https://api.roark.ai`
- URL: `https://api.roark.ai/v1/simulation/run-group`
- Auth: HTTP bearer

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.

## Request body

- CreateSimulationRunGroupInput: Group existing runs, or start one run per plan and group those.
  - `name` string: What to call the group. Defaults to the plans' names when starting plans, and to the runs' plan names when grouping existing runs.
  - `simulationRunPlanJobIds` string[]: 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.
  - `simulationRunPlanIds` string[]: 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.

## Response `201`

The run group, with its report requested

- object
  - `data` SimulationRunGroup, required: Several simulation runs read as one.
    - `id` string, uuid, required
    - `name` string, required
    - `createdAt` string, required: ISO 8601
    - `runCount` integer, required
    - `runs` SimulationRunGroupRun[], required
      - `simulationRunPlanJobId` string, uuid, required: The run, readable at GET /v1/simulation/plan/job/{jobId}
      - `simulationRunPlanId` string, uuid, required
      - `planName` string, nullable, required: The name of the plan the run ran. Null when the plan was deleted.
      - `runNumber` integer, nullable, required: Per-project run number, shown as SR-42 in the app.
      - `status` 'PENDING' | 'QUEUED' | 'CREATING_SNAPSHOTS' | 'CREATING_SIMULATIONS' | 'PREPARING_CAPACITY' | 'RUNNING_SIMULATIONS' | 'COMPLETED' | 'FAILED' | 'TIMED_OUT' | 'CANCELLED' | 'CANCELLING' | 'ENDING_SIMULATIONS', required
      - `createdAt` string, required: ISO 8601
      - `startedAt` string, nullable, required
      - `endedAt` string, nullable, required
    - `latestReport` SimulationRunGroupReport, required: One generation of the group report.
      - `id` string, uuid, required
      - `status` 'PENDING' | 'GENERATING' | 'READY' | 'FAILED', required: PENDING and GENERATING are in flight; READY carries the document; FAILED carries errorMessage.
      - `errorMessage` string, nullable, required
      - `createdAt` string, required: ISO 8601
      - `completedAt` string, nullable, required: ISO 8601. Null until the report settles.
      - `document` SimulationRunGroupReportDocument, required: 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.
        - `version` 1, required
        - `generatedAtIso` string, required
        - `model` string, required
        - `simulationRunGroupId` string, required
        - `headline` object, required
          - `groupName` string, required
          - `runCount` integer, required
          - `reportedRunCount` integer, required
          - `passedRunCount` integer, required
          - `callCount` integer, required
          - `verdict` 'PASSED' | 'THRESHOLD_FAILED', required
          - `completedAtIso` string, nullable, required
          - `verdictProse` string, required
          - `statTiles` object[], required
            - `label` string, required
            - `value` string, required
            - `sub` string, nullable, required
            - `deltaDirection` 'POSITIVE' | 'NEGATIVE' | 'NEUTRAL', nullable, required
        - `runs` object[], required
          - `simulationRunPlanJobId` string, required
          - `runLabel` string, required
          - `runNumber` integer, nullable, required
          - `status` 'PENDING' | 'QUEUED' | 'CREATING_SNAPSHOTS' | 'CREATING_SIMULATIONS' | 'PREPARING_CAPACITY' | 'RUNNING_SIMULATIONS' | 'COMPLETED' | 'FAILED' | 'TIMED_OUT' | 'CANCELLED' | 'CANCELLING' | 'ENDING_SIMULATIONS', required
          - `verdict` 'PASSED' | 'THRESHOLD_FAILED', nullable, required
          - `callCount` integer, required
          - `checksPassed` integer, required
          - `checksTotal` integer, required
          - `themeCount` integer, required
          - `completedAtIso` string, nullable, required
          - `summary` string, nullable, required
        - `executiveSummary` object[], required
          - `heading` string, required
          - `body` string, required
        - `scorecard` object[], required
          - `checkName` string, required
          - `runCount` integer, required
          - `failedRunCount` integer, required
          - `failedCount` integer, required
          - `evaluatedCount` integer, required
          - `passRatePct` number, nullable, required
        - `wentWell` object[], required
          - `title` string, required
          - `body` string, required
          - `evidence` object[], required
            - `text` string, required
            - `simulationRunPlanJobId` string, required
            - `conversationId` string, required
            - `callId` string, nullable, required
            - `personaName` string, nullable, required
            - `cueMs` integer, nullable, required
        - `issues` object[], required
          - `order` integer, required
          - `title` string, required
          - `body` string, required
          - `severity` 'HIGH' | 'MEDIUM' | 'LOW', required
          - `rootCauseChannel` 'PROMPT' | 'VOICE_CONFIG' | 'STT' | 'SPEECH_MODEL' | 'LLM_MODEL' | 'INFRA' | 'EXTERNAL', nullable, required
          - `affectedCallCount` integer, required
          - `runLabels` string[], required
          - `checkNames` string[], required
          - `sourceThemes` object[], required
            - `simulationRunPlanJobId` string, required
            - `slug` string, required
          - `evidence` object[], required
            - `text` string, required
            - `simulationRunPlanJobId` string, required
            - `conversationId` string, required
            - `callId` string, nullable, required
            - `personaName` string, nullable, required
            - `cueMs` integer, nullable, required
          - `calls` object[], required
            - `simulationRunPlanJobId` string, required
            - `conversationId` string, required
            - `callId` string, nullable, required
            - `personaName` string, nullable, required
            - `cueMs` integer, nullable, required
        - `smallerItems` object[], required
          - `order` integer, required
          - `title` string, required
          - `body` string, required
          - `severity` 'HIGH' | 'MEDIUM' | 'LOW', required
          - `rootCauseChannel` 'PROMPT' | 'VOICE_CONFIG' | 'STT' | 'SPEECH_MODEL' | 'LLM_MODEL' | 'INFRA' | 'EXTERNAL', nullable, required
          - `affectedCallCount` integer, required
          - `runLabels` string[], required
          - `checkNames` string[], required
          - `sourceThemes` object[], required
            - `simulationRunPlanJobId` string, required
            - `slug` string, required
          - `evidence` object[], required
            - `text` string, required
            - `simulationRunPlanJobId` string, required
            - `conversationId` string, required
            - `callId` string, nullable, required
            - `personaName` string, nullable, required
            - `cueMs` integer, nullable, required
          - `calls` object[], required
            - `simulationRunPlanJobId` string, required
            - `conversationId` string, required
            - `callId` string, nullable, required
            - `personaName` string, nullable, required
            - `cueMs` integer, nullable, required
        - `recommendations` object[], required
          - `order` integer, required
          - `title` string, required
          - `body` string, required
          - `channel` 'PROMPT' | 'VOICE_CONFIG' | 'STT' | 'SPEECH_MODEL' | 'LLM_MODEL' | 'INFRA' | 'EXTERNAL', nullable, required
          - `issueOrders` integer[], required
        - `aggregates` object[], required
          - `metricName` string, required
          - `averageLabel` string, nullable, required
          - `medianLabel` string, nullable, required
          - `p95Label` string, nullable, required
          - `evaluatedCount` integer, required
        - `methodology` string, required

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `402`: Payment Required
- `403`: Forbidden
- `404`: A run or plan was not found in this project
- `429`: Too Many Requests
- `500`: Internal Server Error

## Changes

> 187 revisions in range; 1 not diffed.

- **2026-10-12** `e3008a49666a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/simulation/run-group/post.md)

---

[API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) - [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roarkhq/apis/roark-analytics-api/revisions/1a91a5c90e44?raw)