---
title: "List runs"
method: GET
path: "/api/v1/runs"
tags: ["runs"]
---

# List runs

`GET /api/v1/runs`

List runs in a specific environment. You can filter the runs by status, created at, task identifier, version, and more.

## Query parameters

- `page` object
  - `size` integer — Number of runs per page. Maximum is 100.
  - `after` string — The ID of the run to start the page after. This will set the direction of the pagination to forward.
  - `before` string — The ID of the run to start the page before. This will set the direction of the pagination to backward.
- `filter` CommonRunsFilter
  - `createdAt` object
    - `from` string, date-time — The start date to filter the runs by
    - `to` string, date-time — The end date to filter the runs by
    - `period` string — The period to filter the runs by
  - `status` string[]
  - `taskIdentifier` string[] — The identifier of the task that was run
  - `version` string[] — The version of the worker that executed the run
  - `bulkAction` string — The bulk action ID to filter the runs by
  - `schedule` string — The schedule ID to filter the runs by
  - `isTest` boolean — Whether the run is a test run or not
  - `tag` string[] — The tags that are attached to the run

## Response `200`

Successful request

- ListRunsResult
  - `data` ListRunItem[]
    - `id` string, required — The unique ID of the run, prefixed with `run_`
    - `status` 'PENDING_VERSION' | 'QUEUED' | 'EXECUTING' | 'REATTEMPTING' | 'FROZEN' | 'COMPLETED' | 'CANCELED' | 'FAILED' | 'CRASHED' | 'INTERRUPTED' | 'SYSTEM_FAILURE', required — The status of the run
    - `taskIdentifier` string, required — The identifier of the task that was run
    - `version` string — The version of the worker that executed the run
    - `env` object, required — The environment of the run
      - `id` string, required — The unique ID of the environment
      - `name` string, required — The name of the environment
      - `user` string — If this is a dev environment, the username of the user represented by this environment
    - `idempotencyKey` string — The idempotency key used to prevent creating duplicate runs, if provided
    - `isTest` boolean, required — Whether the run is a test run or not
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `startedAt` string, date-time — The time the run started
    - `finishedAt` string, date-time — The time the run finished
    - `delayedUntil` string, date-time — If the run was triggered with a delay, this will be the time the run will be enqueued to execute
    - `ttl` union — The time-to-live for this run. If the run is not executed within this time, it will be removed from the queue and never execute. You can use a string in this format: `1h`, `1m`, `1h42m` or a number of seconds (min. 1).
      - string
      - number
    - `expiredAt` string, date-time — If the run had a TTL and that time has passed, when the run "expired".
    - `tags` string[] — Tags can be attached to a run to make it easy to find runs (in the dashboard or using SDK functions like `runs.list`)
    - `costInCents` number — The compute cost of the run (so far) in cents. This cost does not apply to DEV runs.
    - `baseCostInCents` number — The invocation cost of the run in cents. This cost does not apply to DEV runs.
    - `durationMs` number — The duration of compute (so far) in milliseconds. This does not include waits.
  - `pagination` object
    - `next` string — The run ID to start the next page after. This should be used as the `page[after]` parameter in the next request.
    - `previous` string — The run ID to start the previous page before. This should be used as the `page[before]` parameter in the next request.

## Other responses

- `400` — Invalid query parameters
- `401` — Unauthorized request

---

[API](https://skmtc.net/winsenlabs/apis/trigger-dev-v3-rest-api.md) · [All operations](https://skmtc.net/winsenlabs/apis/trigger-dev-v3-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/winsenlabs/trigger-dev-v3-rest-api/versions/737c498e605b/schema)