---
title: "ListRuns"
method: POST
path: "/depot.ci.v1.CIService/ListRuns"
tags: ["CIService"]
---

# ListRuns

`POST /depot.ci.v1.CIService/ListRuns`

## Request

- Base URL: `https://api.depot.dev`
- URL: `https://api.depot.dev/depot.ci.v1.CIService/ListRuns`
- Auth: HTTP bearer

Returns CI runs for the authenticated organization, newest first. Filter by status, repository, commit SHA, trigger, or pull request number. Use `pageSize` and `pageToken` to page through additional results.

## Headers

- `Connect-Protocol-Version` 1, required: Define the version of the Connect protocol
- `Connect-Timeout-Ms` number: Define the timeout, in ms

## Request body

- DepotCiV1ListRunsRequest
  - `status` string[]: Statuses of runs to return. Can be "queued", "running", "finished", "failed", or "cancelled". Multiple values are ORed. Default: ["running", "queued"].
  - `pageSize` integer: Number of runs to return per page. Maximum: 100. Default: 50.
  - `pageToken` string: Token to fetch the next page of runs. Use the `nextPageToken` value from a prior response. Leave empty to fetch the first page.
  - `repo` string: Repository to return runs from, in `owner/name` format. For example, "depot/cli". Required if `pr` is set.
  - `sha` string: Commit SHA prefix to return runs for. Matched against the run's `sha` or `headSha`. 1-40 hex characters.
  - `trigger` string: Trigger event to return runs for. For example, "push", "pull_request", "pull_request_target", "issue_comment", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".
  - `pr` string: Pull request number to return runs for. Requires `repo`.

## Response `200`

Success

- DepotCiV1ListRunsResponse
  - `runs` DepotCiV1ListRunsResponseRun[]: Recent runs matching the request, newest first.
    - `runId` string: Unique identifier for the CI run.
    - `repo` string: GitHub repository in `owner/name` format. For example, "depot/cli".
    - `trigger` string: Event that triggered the run. For example, "push", "pull_request", "pull_request_target", "issue_comment", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".
    - `sha` string: Commit SHA the run executes against. Empty for open pull_request runs.
    - `status` string: Current state of the run. Can be "queued", "running", "finished", "failed", or "cancelled".
    - `createdAt` string: Run creation time, in RFC 3339 format.
    - `ref` string: Git ref the run was triggered against. For example, "refs/heads/main" or "refs/pull/42/merge". Empty when the trigger carries no ref.
    - `headSha` string: Source commit SHA for pull_request and merge_group triggers. Empty for triggers that don't carry a head SHA.
  - `nextPageToken` string: Token to retrieve the next page of results. Empty when no more pages are available.

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/depot/apis/depot-ci-api.md) - [All operations](https://skmtc.dev/depot/apis/depot-ci-api/llms.txt) - [OpenAPI document](https://skmtc.dev/depot/apis/depot-ci-api/revisions/6cf759b535b4?raw)