---
title: "List run groups"
method: GET
path: "/v1/simulation/run-group"
tags: ["Simulation"]
---

# List run groups

`GET /v1/simulation/run-group`

## Request

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

Returns the run groups in the project, newest first, with their runs and where each group report stands. Read a report document from GET /v1/simulation/run-group/{groupId}.

## Query parameters

- `limit` integer: Maximum number of run groups to return (default: 20, max: 100)
- `offset` integer: Pagination offset

## Response `200`

Paginated list of run groups

- ListSimulationRunGroupsResponse
  - `data` SimulationRunGroupListItem[], required
    - `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` SimulationRunGroupReportSummary, required: Where the group report stands, without its document.
      - `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.
  - `pagination` object, required
    - `limit` integer, required
    - `offset` integer, required
    - `total` integer, required: Total run groups in the project, ignoring this page.
    - `hasMore` boolean, required

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `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/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)