---
title: "List simulation plan jobs"
method: GET
path: "/v1/simulation/plan/jobs"
tags: ["Simulation Run Plan Job"]
---

# List simulation plan jobs

`GET /v1/simulation/plan/jobs`

Returns a paginated list of simulation run plan jobs. Filter by status, plan ID, or label to find specific simulation batches.

## Query parameters

- `limit` integer — Maximum number of plan jobs to return (default: 20, max: 50)
- `after` string, uuid — Cursor for pagination - use the nextCursor value from a previous response
- `status` 'PENDING' | 'QUEUED' | 'CREATING_SNAPSHOTS' | 'CREATING_SIMULATIONS' | 'PREPARING_CAPACITY' | 'RUNNING_SIMULATIONS' | 'COMPLETED' | 'FAILED' | 'TIMED_OUT' | 'CANCELLED' | 'CANCELLING' | 'ENDING_SIMULATIONS' — Filter by plan job status (PENDING, QUEUED, CREATING_SNAPSHOTS, CREATING_SIMULATIONS, PREPARING_CAPACITY, RUNNING_SIMULATIONS, COMPLETED, FAILED, TIMED_OUT, CANCELLED, CANCELLING, ENDING_SIMULATIONS)
- `simulationRunPlanId` string, uuid — Filter by simulation run plan ID
- `labelId` string, uuid — Filter by label ID attached to the plan job. Use this if you know the label ID.
- `labelName` string — Filter by label name attached to the plan job. More user-friendly alternative to labelId. Case-insensitive.

## Response `200`

Paginated list of simulation plan jobs

- GetSimulationPlanJobsResponse — Paginated list of simulation run plan jobs
  - `data` object[], required
    - `simulationRunPlanJobId` string, uuid, required — ID of the simulation run plan job
    - `simulationRunPlanId` string, uuid, required — ID of the simulation run plan
    - `status` 'PENDING' | 'QUEUED' | 'CREATING_SNAPSHOTS' | 'CREATING_SIMULATIONS' | 'PREPARING_CAPACITY' | 'RUNNING_SIMULATIONS' | 'COMPLETED' | 'FAILED' | 'TIMED_OUT' | 'CANCELLED' | 'CANCELLING' | 'ENDING_SIMULATIONS', required — Job status
    - `triggeredBy` 'SCHEDULED' | 'USER_TRIGGERED_FROM_UI' | 'RE_RUN' | 'TRIGGERED_FROM_API' | 'SYSTEM', required — How the job was triggered (SCHEDULED, USER_TRIGGERED_FROM_UI, TRIGGERED_FROM_API, RE_RUN, or SYSTEM). SYSTEM is used when the job was started by an internal admin acting on behalf of the project (the original user identity is not exposed).
    - `createdAt` string, required — When the job was created
    - `startedAt` string, nullable — When the job started
    - `endedAt` string, nullable — When the job ended
  - `pagination` object, required
    - `total` number, required — Total number of matching plan jobs
    - `hasMore` boolean, required — Whether there are more results available
    - `nextCursor` string, nullable — Cursor to use for fetching the next page

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `429` — Too Many Requests
- `500` — Internal Server Error

## Changes

- **2026-08-20** `9080f2313118` — 1 warning, 1 info
  - added the new `PREPARING_CAPACITY` enum value to the `data/items/status` response property for the response status `200`
  - added the new enum value `PREPARING_CAPACITY` to the `query` request parameter `status`
- **2026-08-17** `887b091b3d81` — 9 warning
  - added the new `SYSTEM` enum value to the `data/items/triggeredBy` response property for the response status `200`
  - added the new `conflict` enum value to the `type` response property for the response status `401`
  - added the new `conflict` enum value to the `type` response property for the response status `403`
  - added the new `conflict` enum value to the `type` response property for the response status `429`
  - …5 more

[Change history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/simulation/plan/jobs/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-service-production.skmtc.workers.dev/v1/apis/roarkhq/roark-analytics-api/revisions/1d61b68e9429/schema)