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

# ListWorkflows

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

## Request

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

Returns CI workflows for the authenticated organization, newest first. Filter by name, repository, status, trigger, commit SHA, or pull request number. Use `pageSize` to return up to 200 workflows.

## Headers

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

## Request body

- DepotCiV1ListWorkflowsRequest
  - `pageSize` integer: Number of workflows to return per page. Maximum: 200. Default: 50.
  - `name` string: Text to match against the workflow name or file path. Only workflows containing this text are returned.
  - `repo` string: Repository to return workflows from, in `owner/name` format. For example, "depot/cli".
  - `status` string[]: Statuses of workflows to return. Can be "queued", "running", "finished", "failed", or "cancelled". Multiple values are ORed.
  - `trigger` string: Trigger event to return workflows for. For example, "push", "pull_request", "pull_request_target", "issue_comment", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".
  - `sha` string: Commit SHA prefix to return workflows for, matched against the parent run's `headSha`. 1-40 hex characters.
  - `pr` string: Pull request number to return workflows for.

## Response `200`

Success

- DepotCiV1ListWorkflowsResponse
  - `workflows` DepotCiV1ListWorkflowsResponseWorkflow[]: Recent workflows matching the request, newest first.
    - `workflowId` string: Unique identifier for the workflow.
    - `name` string: Workflow name from the YAML `name:` key. Falls back to the file path stem when the workflow doesn't set `name:`. Empty when neither is available.
    - `workflowPath` string: Workflow file path. For example, ".depot/workflows/ci.yml". Empty when the workflow YAML was passed via `workflowContent` in the `Run` request.
    - `repo` string: GitHub repository in `owner/name` format. For example, "depot/cli".
    - `status` string: Current state of the workflow. Can be "queued", "running", "finished", "failed", or "cancelled".
    - `trigger` string: Event that triggered the parent run. For example, "push", "pull_request", "pull_request_target", "issue_comment", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".
    - `runId` string: Unique identifier for the parent CI run.
    - `sha` string: Commit SHA the parent run executes against. Empty for open pull_request runs.
    - `headSha` string: Source commit SHA for pull_request and merge_group triggers. Empty for triggers that don't carry a head SHA.
    - `createdAt` string: Workflow creation time, in RFC 3339 format.
    - `jobCounts` DepotCiV1ListWorkflowsResponseJobCounts
      - `total` integer: Total number of jobs in the workflow.
      - `queued` integer: Number of jobs currently queued.
      - `waiting` integer: Number of jobs waiting on dependencies.
      - `running` integer: Number of jobs currently running.
      - `finished` integer: Number of jobs that finished successfully.
      - `failed` integer: Number of jobs that failed.
      - `cancelled` integer: Number of jobs that were cancelled.
      - `skipped` integer: Number of jobs that were skipped.

## 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)