---
title: "Get a run group"
method: GET
path: "/v1/simulation/run-group/{groupId}"
tags: ["Simulation"]
---

# Get a run group

`GET /v1/simulation/run-group/{groupId}`

## Request

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

Returns a run group with its runs in group order and its latest group report, including the report document once READY.

## Path parameters

- `groupId` string, uuid, required

## Response `200`

The run group

- 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
- `403`: Forbidden
- `404`: Run group not found
- `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/:groupId/get.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)