---
title: "List project runs"
method: GET
path: "/api/v1/projects/{projectRef}/runs"
tags: ["runs"]
---

# List project runs

`GET /api/v1/projects/{projectRef}/runs`

## Request

- Base URL: `https://api.trigger.dev`
- URL: `https://api.trigger.dev/api/v1/projects/{projectRef}/runs`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/docs/api/v1/projects/:projectRef/runs/get.ts> (a function with typed inputs; its response is checked against the schema)

List runs in a project, across multiple environments, using Personal Access Token auth. 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` object
  - `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
  - `error` string: An error group ID (starts with `error_`). Lists the runs behind that error group.
  - `env` string[]

## 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 request
- `401`: Unauthorized request

## Changes

- **2025-03-21** `7e4036741e50`: 1 breaking, 1 warning, 2 info
  - removed the enum value `WAITING_FOR_DEPLOY` from the property `allOf[#/components/schemas/CommonRunsFilter]/status/items/` of the `query` request parameter `filter`
  - added the new `PENDING_VERSION` enum value to the `data/items/status` response property for the response status `200`
  - added the enum value `PENDING_VERSION` to the property `allOf[#/components/schemas/CommonRunsFilter]/status/items/` of the `query` request parameter `filter`
  - removed the `WAITING_FOR_DEPLOY` enum value from the `data/items/status` response property for the response status `200`
- **2024-07-24** `059ad75e9ad0`: 7 info
  - added the optional property `data/items/baseCostInCents` to the response with the `200` status
  - added the optional property `data/items/costInCents` to the response with the `200` status
  - added the optional property `data/items/delayedUntil` to the response with the `200` status
  - added the optional property `data/items/durationMs` to the response with the `200` status
  - …3 more
- **2024-05-31** `3c0abddc2b32`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/changes/api/v1/projects/:projectRef/runs/get.md)

---

[API](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api.md) - [All operations](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/revisions/441161111493?raw)