Depot CI API Reference

RPC-first reference for the Depot CI Connect API. Every method is generated from the OpenAPI artifact and grouped by CI resource. The Depot CI API exposes a four-level resource hierarchy.

Run: Top-level execution unit triggered by an event or workflow dispatch. Contains one or more workflows.
Workflow: Corresponds to a single workflow YAML file. Contains one or more jobs.
Job: Corresponds to one entry in the workflow YAML. Has one or more attempts.
Attempt: One dispatch of a job. Retries create new attempts.

Logs, metrics, artifacts, and failure diagnoses are scoped to attempts but reachable from the parent run, workflow, or job.

RPC basics

Base URL

https://api.depot.dev

Protocol

Connect RPC over HTTP

Auth

Bearer token

Encoding

JSON or Connect JSON

OpenAPI spec

Version

Methods

SourceJSON

Method index

The API includes the following 25 RPC methods, grouped by resource.

Runs6

RunTriggers a CI run. Runs can contain one or more workflows.ListRunsReturns 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.GetRunReturns a CI run's identity, repo, trigger, status, and timestamps. For nested workflow, job, and attempt status, use `GetRunStatus`.GetRunStatusReturns a CI run's status with its nested workflows, jobs, and attempts. For the run's identity, repo, trigger, and timestamps, use `GetRun`.GetRunMetricsReturns workflow, job, and attempt CPU and memory metric summaries for one run.CancelRunCancels a queued or running CI run and any of its unfinished workflows, jobs, and attempts.

Workflows5

ListWorkflowsReturns CI workflows for the authenticated organization, newest first. Filter by name, repository, status, trigger, commit SHA, or pull request number to find relevant workflows. Use page_size to return up to 200 workflows.GetWorkflowReturns curated workflow, run, execution, job, and attempt metadata for single-workflow inspection.DispatchWorkflowTriggers a single workflow via workflow_dispatch, validating inputs against the workflow's schema.RerunWorkflowResets all jobs in a finished workflow and re-runs them.CancelWorkflowCancels a queued or running workflow and all its child jobs.

Jobs6

GetJobReturns curated job metadata, parent run and workflow context, dependency summaries, and attempt history.GetJobSummaryReturns authored step summary markdown for a job, a specific attempt, or both.GetJobMetricsReturns per-attempt CPU and memory metric summaries for one job.RetryJobRetries a failed job within a running workflow.RetryFailedJobsRetries only failed and cancelled jobs (and their skipped dependents) in a finished workflow.CancelJobCancels a queued or running job.

Attempts2

GetAttemptReturns curated attempt metadata with parent job, workflow, and run context.GetJobAttemptMetricsReturns CPU and memory metrics for one job attempt.

Logs3

GetJobAttemptLogsReturns log lines for a job attempt.StreamJobAttemptLogsFollows persisted log lines for a job attempt.stream ExportJobAttemptLogsExports a finite snapshot of persisted log lines.stream

Artifacts2

ListArtifactsReturns CI artifact metadata for one run. Signed download URLs are not included.GetArtifactDownloadURLReturns a signed HTTPS URL for one artifact.

Diagnostics1

GetFailureDiagnosisReturns a bounded deterministic failure diagnosis for a run, workflow, job, or attempt.

Runs

Create, inspect, measure, and cancel CI runs.

RunPOST/depot.ci.v1.CIService/Run ListRunsPOST/depot.ci.v1.CIService/ListRuns GetRunPOST/depot.ci.v1.CIService/GetRun GetRunStatusPOST/depot.ci.v1.CIService/GetRunStatus GetRunMetricsPOST/depot.ci.v1.CIService/GetRunMetrics CancelRunPOST/depot.ci.v1.CIService/CancelRun

RunCIService.Run

Triggers a CI run. Runs can contain one or more workflows.

Parameters

repostring

GitHub repository to run against, in owner/name format, for example "depot/cli". Must be connected to your Depot organization through the Depot GitHub app.

shastring | null

Commit SHA to run against. Use a specific commit to run a particular version of your workflow files (and have that SHA appear in github.sha), or omit to run the latest commit on the default branch. Must be a full 40-character hex SHA. Default: HEAD of the default branch.

workflowstring | null

Path of the workflow file to run, relative to the repo root, for example ".depot/workflows/ci.yml". Mutually exclusive with workflowContent; if neither is provided, runs all workflows in the repo.

workflowContentstring[]

An array of workflow YAMLs to run. Depot reads the YAML from the request instead of the repo. Each entry must be the complete content of a workflow (the same YAML you would commit to .depot/workflows/). Useful for testing workflow YAML changes without committing them. Mutually exclusive with workflow; if neither is provided, runs all workflows in the repo.

jobstring | null

Run a single job from within a workflow. Other jobs in the workflow are skipped. Only valid when a single workflow is specified, either through workflow or a workflowContent entry containing one workflow.

Returns

orgIdstring

Organization that owns this run.

runIdstring

Unique identifier for the created CI run. Use it for methods like GetRun, GetRunStatus, CancelRun, and ListArtifacts to track, cancel, or fetch results from the run.

POST/depot.ci.v1.CIService/Run

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/Run \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "repo": "repo_example",8  "sha": "b2f5ff47436671b6e533d8dc3614845d",9  "workflow": "workflow_example",10  "workflowContent": [11    "workflowContent_example"12  ],13  "job": "job_example"14}15JSON

Response

{  "orgId": "org_123",  "runId": "run_123"}

ListRunsCIService.ListRuns

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.

Parameters

statusstring[]

Statuses of runs to return, for example "queued", "running", "finished", "failed", or "cancelled". Multiple values are ORed. Default: ["running", "queued"].

pageSizeinteger<int32>

Number of runs to return per page. Maximum: 100. Default: 50.

pageTokenstring

Token to fetch the next page of runs. Use the nextPageToken value from a prior response. Leave empty to fetch the first page.

repostring

Repository to return runs from, in owner/name format, for example "depot/cli". Required if pr is set.

shastring

Commit SHA prefix to return runs for. Matched against the run's sha or headSha. 1-40 hex characters.

triggerstring

Trigger event to return runs for, for example "push", "pull_request", "pull_request_target", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".

prstring

Pull request number to return runs for. Requires repo.

Returns

runsListRunsResponseRun[]

Recent runs matching the request, newest first.

+Show child parameters

runIdstring

Unique identifier for the CI run.

repostring

GitHub repository in owner/name format, for example "depot/cli".

triggerstring

Event that triggered the run, for example "push", "pull_request", "pull_request_target", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".

shastring

Commit SHA the run executes against. Empty for open pull_request runs.

statusstring

Current state of the run, for example "queued", "running", "finished", "failed", or "cancelled".

createdAtstring

Run creation time, in RFC 3339 format.

refstring

Git ref the run was triggered against, for example "refs/heads/main" or "refs/pull/42/merge". Empty when the trigger carries no ref.

headShastring

Source commit SHA for pull_request and merge_group triggers. Empty for triggers that don't carry a head SHA.

nextPageTokenstring

Token to retrieve the next page of results. Empty when no more pages are available.

POST/depot.ci.v1.CIService/ListRuns

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/ListRuns \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "status": [8    "status_example"9  ],10  "pageSize": 1,11  "pageToken": "pageToken_example",12  "repo": "repo_example",13  "sha": "b2f5ff47436671b6e533d8dc3614845d",14  "trigger": "trigger_example",15  "pr": "pr_example"16}17JSON

Response

{  "runs": [    {      "runId": "run_123",      "repo": "repo_example",      "trigger": "trigger_example",      "sha": "b2f5ff47436671b6e533d8dc3614845d",      "status": "status_example",      "createdAt": "createdAt_example"    }  ],  "nextPageToken": "nextPageToken_example"}

GetRunCIService.GetRun

Returns a CI run's identity, repo, trigger, status, and timestamps. For nested workflow, job, and attempt status, use GetRunStatus.

Parameters

runIdstring

Unique identifier for the CI run. Returned by Run, DispatchWorkflow, and ListRuns.

Returns

orgIdstring

Organization that owns this run.

runIdstring

Unique identifier for the CI run.

repostring

GitHub repository in owner/name format, for example "depot/cli".

refstring

Git ref the run was triggered against, for example "refs/heads/main" or "refs/pull/42/merge". Empty when the trigger carries no ref.

shastring

Commit SHA the run executes against. Empty for open pull_request runs; populated with the merge commit SHA once the PR is closed and merged.

headShastring

Source commit SHA for pull_request and merge_group triggers; matches the PR or merge group head. Empty for triggers that don't carry a head SHA.

triggerstring

Event that triggered the run, for example "push", "pull_request", "pull_request_target", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".

statusstring

Current state of the run, for example "queued", "running", "finished", "failed", or "cancelled".

createdAtstring

Creation time, in RFC 3339 format.

startedAtstring

Start time, in RFC 3339 format. Empty until the run starts.

finishedAtstring

Finish time, in RFC 3339 format. Empty until the run finishes.

POST/depot.ci.v1.CIService/GetRun

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetRun \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "runId": "run_123"8}9JSON

Response

{  "orgId": "org_123",  "runId": "run_123",  "repo": "repo_example",  "ref": "ref_example",  "sha": "b2f5ff47436671b6e533d8dc3614845d",  "headSha": "b2f5ff47436671b6e533d8dc3614845d",  "trigger": "trigger_example",  "status": "status_example"}

GetRunStatusCIService.GetRunStatus

Returns a CI run's status with its nested workflows, jobs, and attempts. For the run's identity, repo, trigger, and timestamps, use GetRun.

Parameters

runIdstring

Unique identifier for the CI run. Returned by Run, DispatchWorkflow, and ListRuns.

Returns

orgIdstring

Organization that owns this run.

runIdstring

Unique identifier for the CI run.

statusstring

Current state of the run, for example "queued", "running", "finished", "failed", or "cancelled".

workflowsWorkflowStatus[]

Workflows in the run with their nested jobs and attempts.

+Show child parameters

workflowIdstring

Unique identifier for the workflow.

statusstring

Current state of the workflow, for example "queued", "running", "finished", "failed", or "cancelled".

workflowPathstring

Workflow file path, for example ".depot/workflows/ci.yml". Empty when the workflow YAML was passed via workflowContent in the Run request.

jobsJobStatus[]

Jobs that make up the workflow.

+Show child parameters

jobIdstring

Unique identifier for the job.

jobKeystring

Job key from the workflow, for example "build" or "test".

statusstring

Current state of the job, for example "queued", "waiting", "running", "finished", "failed", "cancelled", or "skipped". "waiting" means the job is blocked behind another run that holds the same concurrency: group slot.

attemptsAttemptStatus[]

All attempts for this job, including the original and any retries. Each contains the attempt's identifier, number, current status, and sandbox/session IDs (when active). Order is not guaranteed.

namestring

Workflow name from the YAML name: key. Empty when not set.

errorMessagestring

Workflow error or cancellation reason, for example a compilation or validation error. Empty when the workflow is healthy.

POST/depot.ci.v1.CIService/GetRunStatus

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetRunStatus \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "runId": "run_123"8}9JSON

Response

{  "orgId": "org_123",  "runId": "run_123",  "status": "status_example",  "workflows": [    {      "workflowId": "workflow_123",      "status": "status_example",      "workflowPath": "workflowPath_example",      "jobs": [        {          "jobId": "job_123",          "jobKey": "jobKey_example",          "status": "status_example",          "attempts": [            "attempts_example"          ]        }      ],      "name": "name_example",      "errorMessage": "errorMessage_example"    }  ]}

GetRunMetricsCIService.GetRunMetrics

Returns workflow, job, and attempt CPU and memory metric summaries for one run.

Parameters

runIdstring

Unique identifier for the CI run. Returned by Run, DispatchWorkflow, and ListRuns.

Returns

runCIMetricsRunContext

Run context: identifiers, trigger, status, and lifecycle timestamps.

+Show child parameters

runIdstring

Unique identifier for the CI run.

repostring

GitHub repository in owner/name format, for example "depot/cli".

refstring

Git ref the run was triggered against. Empty when the trigger carries no ref.

shastring

Commit SHA the run executes against. Empty for open pull_request runs.

headShastring

Source commit SHA for pull_request and merge_group triggers. Empty for triggers that don't carry a head SHA.

triggerstring

Event that triggered the run, for example "push", "pull_request", "pull_request_target", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".

statusstring

Current state of the run, for example "queued", "running", "finished", "failed", or "cancelled".

createdAtstring

Run creation time, in RFC 3339 format.

startedAtstring

Run start time, in RFC 3339 format. Empty until the run starts.

finishedAtstring

Run finish time, in RFC 3339 format. Empty until the run finishes.

workflowsCIMetricsWorkflowMetrics[]

Per-workflow rollups containing each workflow's jobs and per-attempt metric summaries.

+Show child parameters

workflowCIMetricsWorkflowContext

Workflow context: identifiers, status, and lifecycle timestamps.

+Show child parameters

workflowIdstring

Unique identifier for the workflow.

workflowPathstring

Workflow file path, for example ".depot/workflows/ci.yml". Empty when the workflow YAML was passed via workflowContent in the Run request.

namestring

Workflow name from the YAML name: key, falling back to the file path stem. Empty when not available.

statusstring

Current state of the workflow, for example "queued", "running", "finished", "failed", or "cancelled".

createdAtstring

Workflow creation time, in RFC 3339 format.

startedAtstring

Workflow start time, in RFC 3339 format. Empty until the workflow starts.

finishedAtstring

Workflow finish time, in RFC 3339 format. Empty until the workflow finishes.

jobsCIMetricsJobMetrics[]

Jobs in the workflow and their per-attempt metric summaries.

+Show child parameters

jobCIMetricsJobContext

Job context: identifiers, status, conclusion, and lifecycle timestamps.

attemptsCIMetricsAttemptSummary[]

Per-attempt metric summaries for this job, ordered by attempt number ascending.

snapshotAtstring

Server time at which this metrics snapshot was captured, in RFC 3339 format. For attempts that haven't finished yet, CPU and memory data is collected up to this time, so a running attempt's metrics grow on successive calls.

POST/depot.ci.v1.CIService/GetRunMetrics

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetRunMetrics \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "runId": "run_123"8}9JSON

Response

{  "run": {    "runId": "run_123",    "repo": "repo_example",    "ref": "ref_example",    "sha": "b2f5ff47436671b6e533d8dc3614845d",    "headSha": "b2f5ff47436671b6e533d8dc3614845d",    "trigger": "trigger_example"  },  "workflows": [    {      "workflow": {        "workflowId": "workflow_123",        "workflowPath": "workflowPath_example",        "name": "name_example",        "status": "status_example",        "createdAt": "createdAt_example",        "startedAt": "startedAt_example"      },      "jobs": [        {          "job": "job_example",          "attempts": [            "attempts_example"          ]        }      ]    }  ],  "snapshotAt": "snapshotAt_example"}

CancelRunCIService.CancelRun

Cancels a queued or running CI run and any of its unfinished workflows, jobs, and attempts.

Parameters

runIdstring

Unique identifier for the CI run. Returned by Run, DispatchWorkflow, and ListRuns.

Returns

runIdstring

Unique identifier for the CI run. Matches the request runId.

statusstring

New run status, should be "cancelled".

POST/depot.ci.v1.CIService/CancelRun

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/CancelRun \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "runId": "run_123"8}9JSON

Response

{  "runId": "run_123",  "status": "status_example"}

Workflows

List, inspect, dispatch, rerun, and cancel CI workflows.

ListWorkflowsPOST/depot.ci.v1.CIService/ListWorkflows GetWorkflowPOST/depot.ci.v1.CIService/GetWorkflow DispatchWorkflowPOST/depot.ci.v1.CIService/DispatchWorkflow RerunWorkflowPOST/depot.ci.v1.CIService/RerunWorkflow CancelWorkflowPOST/depot.ci.v1.CIService/CancelWorkflow

ListWorkflowsCIService.ListWorkflows

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

Parameters

pageSizeinteger<int32>

Number of workflows to return per page. Maximum: 200. Default: 50.

namestring

Filters recent workflows by substring match on the workflow name or path fallback.

repostring

Filters recent workflows by repo in {owner}/{repo} format.

statusstring[]

Filters recent workflows by workflow status. Multiple values are ORed.

triggerstring

Filters recent workflows by the parent run trigger, for example "push", "pull_request", "pull_request_target", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".

shastring

Filters recent workflows by parent run head SHA prefix.

prstring

Filters recent workflows by pull request number.

Returns

workflowsListWorkflowsResponseWorkflow[]

Recent workflows matching the request, newest first.

+Show child parameters

workflowIdstring

Unique identifier for the workflow.

namestring

Workflow name from the YAML name: key, falling back to the file path stem. Empty when neither is available.

workflowPathstring

Workflow file path, for example ".depot/workflows/ci.yml". Empty when the workflow YAML was passed via workflowContent in the Run request.

repostring

GitHub repository in owner/name format, for example "depot/cli".

statusstring

Current state of the workflow, for example "queued", "running", "finished", "failed", or "cancelled".

triggerstring

Event that triggered the parent run, for example "push", "pull_request", "pull_request_target", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".

runIdstring

Unique identifier for the parent CI run.

shastring

Commit SHA the parent run executes against. Empty for open pull_request runs.

headShastring

Source commit SHA for pull_request and merge_group triggers. Empty for triggers that don't carry a head SHA.

createdAtstring

Workflow creation time, in RFC 3339 format.

jobCountsListWorkflowsResponseJobCounts

Counts of jobs in the workflow broken down by status.

+Show child parameters

totalinteger<int32>

Total number of jobs in the workflow.

queuedinteger<int32>

Number of jobs currently queued.

waitinginteger<int32>

Number of jobs waiting on dependencies.

runninginteger<int32>

Number of jobs currently running.

finishedinteger<int32>

Number of jobs that finished successfully.

failedinteger<int32>

Number of jobs that failed.

cancelledinteger<int32>

Number of jobs that were cancelled.

skippedinteger<int32>

Number of jobs that were skipped.

POST/depot.ci.v1.CIService/ListWorkflows

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/ListWorkflows \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "pageSize": 1,8  "name": "name_example",9  "repo": "repo_example",10  "status": [11    "status_example"12  ],13  "trigger": "trigger_example",14  "sha": "b2f5ff47436671b6e533d8dc3614845d",15  "pr": "pr_example"16}17JSON

Response

{  "workflows": [    {      "workflowId": "workflow_123",      "name": "name_example",      "workflowPath": "workflowPath_example",      "repo": "repo_example",      "status": "status_example",      "trigger": "trigger_example"    }  ]}

GetWorkflowCIService.GetWorkflow

Returns curated workflow, run, execution, job, and attempt metadata for single-workflow inspection.

Parameters

workflowIdstring

Unique identifier for the workflow.

Returns

orgIdstring

Organization that owns this workflow.

runIdstring

Unique identifier for the parent CI run.

repostring

GitHub repository in owner/name format, for example "depot/cli".

refstring

Git ref the parent run was triggered against. Empty when the trigger carries no ref.

shastring

Commit SHA the parent run executes against. For pull_request triggers, the merge commit SHA.

headShastring

Source commit SHA for pull_request and merge_group triggers. Empty for triggers that don't carry a head SHA.

triggerstring

Event that triggered the parent run, for example "push", "pull_request", "pull_request_target", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".

runStatusstring

Current state of the parent run, for example "queued", "running", "finished", "failed", or "cancelled".

runCreatedAtstring

Parent run creation time, in RFC 3339 format.

runStartedAtstring

Parent run start time, in RFC 3339 format. Empty until the run starts.

runFinishedAtstring

Parent run finish time, in RFC 3339 format. Empty until the run finishes.

workflowIdstring

Unique identifier for the workflow.

workflowNamestring

Workflow name from the YAML name: key, falling back to the file path stem. Empty when neither is available.

workflowPathstring

Workflow file path, for example ".depot/workflows/ci.yml". Empty when the workflow YAML was passed via workflowContent in the Run request.

workflowStatusstring

Current state of the workflow, for example "queued", "running", "finished", "failed", or "cancelled".

workflowErrorMessagestring

Workflow error or cancellation reason, for example a compilation or validation error. Empty when the workflow is healthy.

workflowCreatedAtstring

Workflow creation time, in RFC 3339 format.

workflowStartedAtstring

Workflow start time, in RFC 3339 format. Empty until the workflow starts.

workflowFinishedAtstring

Workflow finish time, in RFC 3339 format. Empty until the workflow finishes.

executionsGetWorkflowExecution[]

Workflow-level execution records; each re-run creates another execution.

+Show child parameters

executionIdstring

Unique identifier for the workflow execution.

executioninteger<int32>

Execution number, starting at 1 for the first execution.

statusstring

Current state of the execution, for example "queued", "running", "finished", "failed", or "cancelled".

createdAtstring

Execution creation time, in RFC 3339 format.

startedAtstring

Execution start time, in RFC 3339 format. Empty until the execution starts.

finishedAtstring

Execution finish time, in RFC 3339 format. Empty until the execution finishes.

jobsGetWorkflowJob[]

Workflow jobs and their per-job attempts.

+Show child parameters

jobIdstring

Unique identifier for the job.

jobKeystring

Job key from the workflow, for example "build" or "test".

statusstring

startedAtstring

Job start time, in RFC 3339 format. Empty until the job starts.

finishedAtstring

Job finish time, in RFC 3339 format. Empty until the job finishes.

attemptsGetWorkflowJobAttempt[]

Per-job attempts, not workflow execution records.

+Show child parameters

attemptIdstring

Unique identifier for the job attempt.

attemptinteger<int32>

Attempt number, starting at 1 for the first run.

statusstring

Current state of the attempt, for example "running", "finished", "failed", or "cancelled".

sandboxIdstring

Unique identifier for the sandbox currently running this attempt, when one exists.

sessionIdstring

Unique identifier for the interactive session attached to that sandbox, when one is available.

startedAtstring

Attempt start time, in RFC 3339 format. Empty until the attempt starts.

finishedAtstring

Attempt finish time, in RFC 3339 format. Empty until the attempt finishes.

POST/depot.ci.v1.CIService/GetWorkflow

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetWorkflow \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "workflowId": "workflow_123"8}9JSON

Response

{  "orgId": "org_123",  "runId": "run_123",  "repo": "repo_example",  "ref": "ref_example",  "sha": "b2f5ff47436671b6e533d8dc3614845d",  "headSha": "b2f5ff47436671b6e533d8dc3614845d",  "trigger": "trigger_example",  "runStatus": "runStatus_example"}

DispatchWorkflowCIService.DispatchWorkflow

Triggers a single workflow via workflow_dispatch, validating inputs against the workflow's schema.

Parameters

repostring

GitHub repository to run against, in owner/name format, for example "depot/cli". Must be connected to your Depot organization through the Depot GitHub app.

workflowstring

Workflow file path, for example ".depot/workflows/deploy.yml".

refstring

Branch or tag name to run the workflow on, for example "main".

inputsobject<string, string>

Key-value pairs matching the workflow's input definitions. All values are strings; the server coerces each value to the input's declared type.

Returns

orgIdstring

Organization that owns this run.

runIdstring

Unique identifier for the created CI run. Use it for run-scoped methods like GetRun, GetRunStatus, CancelRun, and ListArtifacts to track, cancel, or fetch results from the run.

POST/depot.ci.v1.CIService/DispatchWorkflow

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/DispatchWorkflow \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "repo": "repo_example",8  "workflow": "workflow_example",9  "ref": "ref_example",10  "inputs": "inputs_example"11}12JSON

Response

{  "orgId": "org_123",  "runId": "run_123"}

RerunWorkflowCIService.RerunWorkflow

Resets all jobs in a finished workflow and re-runs them.

Parameters

workflowIdstring

Unique identifier for the workflow to re-run.

Returns

workflowIdstring

Unique identifier for the workflow. Matches the request workflow_id; a re-run creates a new workflow execution rather than a new workflow.

jobCountinteger<int32>

Number of jobs reset to queued.

POST/depot.ci.v1.CIService/RerunWorkflow

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/RerunWorkflow \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "workflowId": "workflow_123"8}9JSON

Response

{  "workflowId": "workflow_123",  "jobCount": 1}

CancelWorkflowCIService.CancelWorkflow

Cancels a queued or running workflow and all its child jobs.

Parameters

workflowIdstring

Unique identifier for the workflow to cancel.

Returns

workflowIdstring

Unique identifier for the workflow. Matches the request workflow_id.

statusstring

New workflow status, typically "cancelled".

POST/depot.ci.v1.CIService/CancelWorkflow

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/CancelWorkflow \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "workflowId": "workflow_123"8}9JSON

Response

{  "workflowId": "workflow_123",  "status": "status_example"}

Jobs

Inspect, summarize, measure, retry, and cancel CI jobs.

GetJobPOST/depot.ci.v1.CIService/GetJob GetJobSummaryPOST/depot.ci.v1.CIService/GetJobSummary GetJobMetricsPOST/depot.ci.v1.CIService/GetJobMetrics RetryJobPOST/depot.ci.v1.CIService/RetryJob RetryFailedJobsPOST/depot.ci.v1.CIService/RetryFailedJobs CancelJobPOST/depot.ci.v1.CIService/CancelJob

GetJobCIService.GetJob

Returns curated job metadata, parent run and workflow context, dependency summaries, and attempt history.

Parameters

jobIdstring

Unique identifier for the job.

Returns

orgIdstring

Organization that owns this job.

runIdstring

Unique identifier for the parent CI run.

repostring

GitHub repository in owner/name format, for example "depot/cli".

refstring

Git ref the parent run was triggered against. Empty when the trigger carries no ref.

shastring

Commit SHA the parent run executes against. For pull_request triggers, the merge commit SHA.

headShastring

Source commit SHA for pull_request and merge_group triggers. Empty for triggers that don't carry a head SHA.

triggerstring

Event that triggered the parent run, for example "push", "pull_request", "pull_request_target", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".

runStatusstring

Current state of the parent run, for example "queued", "running", "finished", "failed", or "cancelled".

runCreatedAtstring

Parent run creation time, in RFC 3339 format.

runStartedAtstring

Parent run start time, in RFC 3339 format. Empty until the run starts.

runFinishedAtstring

Parent run finish time, in RFC 3339 format. Empty until the run finishes.

workflowIdstring

Unique identifier for the parent workflow.

workflowNamestring

Parent workflow name from the YAML name: key, falling back to the file path stem. Empty when neither is available.

workflowPathstring

Parent workflow file path, for example ".depot/workflows/ci.yml". Empty when the workflow YAML was passed via workflowContent in the Run request.

workflowStatusstring

Current state of the parent workflow, for example "queued", "running", "finished", "failed", or "cancelled".

workflowErrorMessagestring

Parent workflow error or cancellation reason, for example a compilation or validation error. Empty when the workflow is healthy.

workflowCreatedAtstring

Parent workflow creation time, in RFC 3339 format.

workflowStartedAtstring

Parent workflow start time, in RFC 3339 format. Empty until the workflow starts.

workflowFinishedAtstring

Parent workflow finish time, in RFC 3339 format. Empty until the workflow finishes.

jobIdstring

Unique identifier for the job.

jobKeystring

Job key from the workflow, for example "build" or "test".

jobDisplayNamestring

Human-readable display name from the workflow, falling back to jobKey when no display name is set.

jobStatusstring

jobConclusionstring

Conclusion of the job, for example "success", "failure", "cancelled", "skipped", or "timed_out". Empty until the job concludes.

jobErrorMessagestring

Job error message populated for orchestration or worker failures. Empty when the job has no error.

jobCreatedAtstring

Job creation time, in RFC 3339 format.

jobDispatchedAtstring

Job dispatch time, in RFC 3339 format. Empty until the job is dispatched to a worker.

jobStartedAtstring

Job start time, in RFC 3339 format. Empty until the job starts.

jobFinishedAtstring

Job finish time, in RFC 3339 format. Empty until the job finishes.

currentAttemptIdstring

Unique identifier for the most recent attempt for this job. Empty until the first attempt is dispatched.

currentAttemptinteger<int32>

Most recent attempt number for this job. Zero until the first attempt is dispatched.

matrixJobDetailMatrixValue[]

Matrix key/value pairs for this job instance. Empty when the job is not part of a matrix strategy.

+Show child parameters

keystring

Matrix dimension name, for example "os" or "node-version".

valuestring

Matrix dimension value for this job instance, serialized as a string.

strategyJobDetailStrategy

Strategy context exposing this job's index within its matrix expansion. Unset when no strategy context is available.

+Show child parameters

jobIndexinteger<int32>

Zero-based index of this job within the matrix expansion.

jobTotalinteger<int32>

Total number of jobs produced by the matrix expansion.

runsOnJobDetailRunsOn

Resolved runner configuration: labels, image, CPU, memory, and size. Unset when no runner could be resolved for the job.

+Show child parameters

labelsstring[]

Runner labels declared on the job's runs-on.

imagestring

Container image used for the job, when one is configured. Empty otherwise.

cpusinteger<int32>

CPU count allocated to the runner. Zero when unset.

memoryGbinteger<int32>

Memory allocated to the runner, in gigabytes. Zero when unset.

sizestring

Resolved runner size string, for example "small" or "large". Empty when unset.

dependenciesJobDetailDependency[]

Every dependency for small jobs. For jobs with many dependencies, the list is a prioritized preview.

+Show child parameters

jobIdstring

Unique identifier for the dependency job.

jobKeystring

Job key from the workflow, for example "build" or "test".

jobDisplayNamestring

Human-readable display name from the workflow, falling back to jobKey when no display name is set.

statusstring

Current state of the dependency job, for example "queued", "waiting", "running", "finished", "failed", "cancelled", or "skipped". "waiting" means the job is blocked behind another run that holds the same concurrency: group slot.

conclusionstring

Conclusion of the dependency job, for example "success", "failure", "cancelled", "skipped", or "timed_out". Empty until the job concludes.

errorMessagestring

Dependency job error message populated for orchestration or worker failures. Empty when the job has no error.

createdAtstring

Dependency job creation time, in RFC 3339 format.

dispatchedAtstring

Dependency job dispatch time, in RFC 3339 format. Empty until the job is dispatched to a worker.

startedAtstring

Dependency job start time, in RFC 3339 format. Empty until the job starts.

finishedAtstring

Dependency job finish time, in RFC 3339 format. Empty until the job finishes.

attemptsJobDetailAttempt[]

Attempt history for this job, ordered by attempt number ascending.

+Show child parameters

attemptIdstring

Unique identifier for the job attempt.

attemptinteger<int32>

Attempt number, starting at 1 for the first run.

statusstring

Current state of the attempt, for example "running", "finished", "failed", or "cancelled".

conclusionstring

Conclusion of the attempt, for example "success", "failure", "cancelled", "skipped", or "timed_out". Empty until the attempt concludes.

errorMessagestring

Attempt error message populated for orchestration or worker failures. Empty when the attempt has no error.

sandboxIdstring

Unique identifier for the sandbox that ran this attempt, when one exists.

sessionIdstring

Unique identifier for the interactive session attached to that sandbox, when one is available.

createdAtstring

Attempt creation time, in RFC 3339 format.

dispatchedAtstring

Attempt dispatch time, in RFC 3339 format. Empty until the attempt is dispatched to a worker.

startedAtstring

Attempt start time, in RFC 3339 format. Empty until the attempt starts.

finishedAtstring

Attempt finish time, in RFC 3339 format. Empty until the attempt finishes.

isCurrentboolean

True when this attempt is the job's current attempt.

dependencyCountinteger | null

Total dependency count, set only when dependencies is a capped preview.

dependencyPreviewLimitinteger | null

Preview cap on dependencies, set only when dependencies is a capped preview.

POST/depot.ci.v1.CIService/GetJob

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetJob \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "jobId": "job_123"8}9JSON

Response

{  "orgId": "org_123",  "runId": "run_123",  "repo": "repo_example",  "ref": "ref_example",  "sha": "b2f5ff47436671b6e533d8dc3614845d",  "headSha": "b2f5ff47436671b6e533d8dc3614845d",  "trigger": "trigger_example",  "runStatus": "runStatus_example"}

GetJobSummaryCIService.GetJobSummary

Returns authored step summary markdown for a job, a specific attempt, or both.

Parameters

jobIdstring

Unique identifier for the job whose current attempt should be summarized. Required unless attempt_id is set.

attemptIdstring

Unique identifier for a specific job attempt to summarize. Required unless job_id is set. When sent alongside job_id, the attempt must belong to that job.

Returns

orgIdstring

Organization that owns this job.

runIdstring

Unique identifier for the parent CI run.

workflowIdstring

Unique identifier for the parent workflow.

jobIdstring

Unique identifier for the job.

attemptIdstring

Unique identifier for the job attempt. Empty when no attempt exists yet.

attemptinteger<int32>

Attempt number, starting at 1. Zero when no attempt exists yet.

jobStatusstring

attemptStatusstring

Current state of the attempt, for example "running", "finished", "failed", or "cancelled". Empty when no attempt exists yet.

hasSummaryboolean

True when authored step summary markdown is available for the selected attempt.

emptyReasonstring

Set when has_summary is false, for example "no_summary" or "no_attempt".

stepCountinteger

Count of non-empty step summaries included in markdown.

markdownstring

Authored step summary markdown joined in step order.

POST/depot.ci.v1.CIService/GetJobSummary

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetJobSummary \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "jobId": "job_123",8  "attemptId": "attempt_123"9}10JSON

Response

{  "orgId": "org_123",  "runId": "run_123",  "workflowId": "workflow_123",  "jobId": "job_123",  "attemptId": "attempt_123",  "attempt": 1,  "jobStatus": "jobStatus_example",  "attemptStatus": "attemptStatus_example"}

GetJobMetricsCIService.GetJobMetrics

Returns per-attempt CPU and memory metric summaries for one job.

Parameters

jobIdstring

Unique identifier for the job.

Returns

runCIMetricsRunContext

Parent run context: identifiers, trigger, status, and lifecycle timestamps.

+Show child parameters

runIdstring

Unique identifier for the CI run.

repostring

GitHub repository in owner/name format, for example "depot/cli".

refstring

Git ref the run was triggered against. Empty when the trigger carries no ref.

shastring

Commit SHA the run executes against. Empty for open pull_request runs.

headShastring

Source commit SHA for pull_request and merge_group triggers. Empty for triggers that don't carry a head SHA.

triggerstring

Event that triggered the run, for example "push", "pull_request", "pull_request_target", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".

statusstring

Current state of the run, for example "queued", "running", "finished", "failed", or "cancelled".

createdAtstring

Run creation time, in RFC 3339 format.

startedAtstring

Run start time, in RFC 3339 format. Empty until the run starts.

finishedAtstring

Run finish time, in RFC 3339 format. Empty until the run finishes.

workflowCIMetricsWorkflowContext

Parent workflow context: identifiers, status, and lifecycle timestamps.

+Show child parameters

workflowIdstring

Unique identifier for the workflow.

workflowPathstring

Workflow file path, for example ".depot/workflows/ci.yml". Empty when the workflow YAML was passed via workflowContent in the Run request.

namestring

Workflow name from the YAML name: key, falling back to the file path stem. Empty when not available.

statusstring

Current state of the workflow, for example "queued", "running", "finished", "failed", or "cancelled".

createdAtstring

Workflow creation time, in RFC 3339 format.

startedAtstring

Workflow start time, in RFC 3339 format. Empty until the workflow starts.

finishedAtstring

Workflow finish time, in RFC 3339 format. Empty until the workflow finishes.

jobCIMetricsJobContext

Job context: identifiers, status, conclusion, and lifecycle timestamps.

+Show child parameters

jobIdstring

Unique identifier for the job.

jobKeystring

Job key from the workflow, for example "build" or "test".

statusstring

conclusionstring

Conclusion of the job, for example "success", "failure", "cancelled", "skipped", or "timed_out". Empty until the job concludes.

currentAttemptinteger<int32>

Most recent attempt number for this job. Zero until the first attempt is dispatched.

createdAtstring

Job creation time, in RFC 3339 format.

startedAtstring

Job start time, in RFC 3339 format. Empty until the job starts.

finishedAtstring

Job finish time, in RFC 3339 format. Empty until the job finishes.

attemptsCIMetricsAttemptSummary[]

Per-attempt metric summaries for this job, ordered by attempt number ascending.

+Show child parameters

attemptCIMetricsAttemptContext

Attempt context: identifiers, status, conclusion, and lifecycle timestamps.

+Show child parameters

attemptIdstring

Unique identifier for the job attempt.

attemptinteger<int32>

Attempt number, starting at 1 for the first run.

statusstring

Current state of the attempt, for example "running", "finished", "failed", or "cancelled".

conclusionstring

Conclusion of the attempt, for example "success", "failure", "cancelled", "skipped", or "timed_out". Empty until the attempt concludes.

sandboxIdstring

Unique identifier for the sandbox that ran this attempt, when one exists.

sessionIdstring

Unique identifier for the interactive session attached to that sandbox, when one is available.

createdAtstring

Attempt creation time, in RFC 3339 format.

startedAtstring

Attempt start time, in RFC 3339 format. Empty until the attempt starts.

finishedAtstring

Attempt finish time, in RFC 3339 format. Empty until the attempt finishes.

availabilityCIMetricsAvailability

Availability code and reason explaining why metrics are or are not present.

+Show child parameters

codeCIMetricsAvailabilityCode

Availability code.

AVAILABLE: metrics samples were observed for the attempt.
NO_SANDBOX: the attempt never ran on a sandbox, so no metrics could be collected.
NO_TIME_RANGE: the attempt has no resolvable start and finish time, so no metric window could be queried.
NO_SAMPLES: the attempt ran on a sandbox but no samples were recorded in its time range.

Possible enum values

CI_METRICS_AVAILABILITY_CODE_UNSPECIFIEDCI_METRICS_AVAILABILITY_CODE_AVAILABLECI_METRICS_AVAILABILITY_CODE_NO_SANDBOXCI_METRICS_AVAILABILITY_CODE_NO_TIME_RANGECI_METRICS_AVAILABILITY_CODE_NO_SAMPLES

reasonstring

Short reason string matching the code, for example "available", "no_sandbox", "no_time_range", or "no_samples".

statsCIMetricsStats

Aggregate CPU and memory statistics computed across the raw samples.

+Show child parameters

sampleCountinteger

Total number of merged samples observed for the attempt.

cpuSampleCountinteger

Number of samples that included a CPU utilization value.

memorySampleCountinteger

Number of samples that included a memory utilization value.

peakCpuUtilizationnumber | null

Peak observed CPU utilization as a fraction from 0 to 1. Unset when no CPU samples were observed.

averageCpuUtilizationnumber | null

Average observed CPU utilization as a fraction from 0 to 1. Unset when no CPU samples were observed.

peakMemoryUtilizationnumber | null

Peak observed memory utilization as a fraction from 0 to 1. Unset when no memory samples were observed.

averageMemoryUtilizationnumber | null

Average observed memory utilization as a fraction from 0 to 1. Unset when no memory samples were observed.

observedStartedAtstring

Timestamp of the first observed sample, in RFC 3339 format. Empty when no samples were observed.

observedFinishedAtstring

Timestamp of the last observed sample, in RFC 3339 format. Empty when no samples were observed.

peakMemoryUsageBytesinteger | string | null

Peak observed memory usage in bytes. Unset when no memory samples were observed.

averageMemoryUsageBytesnumber | null

Average observed memory usage in bytes. Unset when no memory samples were observed.

capCIMetricsCapMetadata

Downsampling metadata describing how raw samples were reduced for transport.

+Show child parameters

rawSampleCountinteger

Raw sample count observed before downsampling.

returnedSampleCountinteger

Number of samples returned in the response.

maxReturnedSampleCountinteger

Hard cap on the number of samples a single response will return.

downsampledboolean

True when the raw samples were downsampled to fit max_returned_sample_count.

downsampleStrategystring

Identifier for the downsampling strategy used, for example "peak_preserving_even". Empty when no downsampling was applied.

snapshotAtstring

POST/depot.ci.v1.CIService/GetJobMetrics

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetJobMetrics \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "jobId": "job_123"8}9JSON

Response

{  "run": {    "runId": "run_123",    "repo": "repo_example",    "ref": "ref_example",    "sha": "b2f5ff47436671b6e533d8dc3614845d",    "headSha": "b2f5ff47436671b6e533d8dc3614845d",    "trigger": "trigger_example"  },  "workflow": {    "workflowId": "workflow_123",    "workflowPath": "workflowPath_example",    "name": "name_example",    "status": "status_example",    "createdAt": "createdAt_example",    "startedAt": "startedAt_example"  },  "job": {    "jobId": "job_123",    "jobKey": "jobKey_example",    "status": "status_example",    "conclusion": "conclusion_example",    "currentAttempt": 1,    "createdAt": "createdAt_example"  },  "attempts": [    {      "attempt": {        "attemptId": "attempt_123",        "attempt": 1,        "status": "status_example",        "conclusion": "conclusion_example",        "sandboxId": "sandbox_123",        "sessionId": "session_123"      },      "availability": {        "code": "CI_METRICS_AVAILABILITY_CODE_UNSPECIFIED",        "reason": "reason_example"      },      "stats": {        "sampleCount": 1,        "cpuSampleCount": 1,        "memorySampleCount": 1,        "peakCpuUtilization": 1,        "averageCpuUtilization": 1,        "peakMemoryUtilization": 1      },      "cap": {        "rawSampleCount": 1,        "returnedSampleCount": 1,        "maxReturnedSampleCount": 1,        "downsampled": false,        "downsampleStrategy": "downsampleStrategy_example"      }    }  ],  "snapshotAt": "snapshotAt_example"}

RetryJobCIService.RetryJob

Retries a failed job within a running workflow.

Parameters

workflowIdstring

Unique identifier for the workflow containing the job.

jobIdstring

Unique identifier for the job to retry.

Returns

jobIdstring

Unique identifier for the job. Matches the request job_id; a retry creates a new attempt rather than a new job.

attemptIdstring

Empty in the response. The new attempt is created once the job runs again and is visible through GetJob.attempts.

attemptinteger<int32>

Attempt number the next attempt will use, one greater than the prior attempt.

statusstring

New job status, typically "queued".

POST/depot.ci.v1.CIService/RetryJob

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/RetryJob \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "workflowId": "workflow_123",8  "jobId": "job_123"9}10JSON

Response

{  "jobId": "job_123",  "attemptId": "attempt_123",  "attempt": 1,  "status": "status_example"}

RetryFailedJobsCIService.RetryFailedJobs

Retries only failed and cancelled jobs (and their skipped dependents) in a finished workflow.

Parameters

workflowIdstring

Unique identifier for the workflow containing failed jobs.

Returns

workflowIdstring

Unique identifier for the workflow. Matches the request workflow_id; a retry creates a new workflow execution rather than a new workflow.

jobIdsstring[]

Unique identifiers for jobs that were set back to queued. A new attempt is created for each job when it runs again.

jobCountinteger<int32>

Number of jobs reset to queued.

POST/depot.ci.v1.CIService/RetryFailedJobs

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/RetryFailedJobs \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "workflowId": "workflow_123"8}9JSON

Response

{  "workflowId": "workflow_123",  "jobIds": [    "job_123"  ],  "jobCount": 1}

CancelJobCIService.CancelJob

Cancels a queued or running job.

Parameters

workflowIdstring

Unique identifier for the workflow containing the job.

jobIdstring

Unique identifier for the job to cancel.

Returns

jobIdstring

Unique identifier for the job. Matches the request job_id.

statusstring

New job status, typically "cancelled".

POST/depot.ci.v1.CIService/CancelJob

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/CancelJob \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "workflowId": "workflow_123",8  "jobId": "job_123"9}10JSON

Response

{  "jobId": "job_123",  "status": "status_example"}

Attempts

Inspect job attempts and their execution metrics.

GetAttemptPOST/depot.ci.v1.CIService/GetAttempt GetJobAttemptMetricsPOST/depot.ci.v1.CIService/GetJobAttemptMetrics

GetAttemptCIService.GetAttempt

Returns curated attempt metadata with parent job, workflow, and run context.

Parameters

attemptIdstring

Unique identifier for the job attempt.

Returns

orgIdstring

Organization that owns this attempt.

runIdstring

Unique identifier for the parent CI run.

repostring

GitHub repository in owner/name format, for example "depot/cli".

refstring

Git ref the parent run was triggered against. Empty when the trigger carries no ref.

shastring

Commit SHA the parent run executes against. For pull_request triggers, the merge commit SHA.

headShastring

Source commit SHA for pull_request and merge_group triggers. Empty for triggers that don't carry a head SHA.

triggerstring

Event that triggered the parent run, for example "push", "pull_request", "pull_request_target", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".

runStatusstring

Current state of the parent run, for example "queued", "running", "finished", "failed", or "cancelled".

runCreatedAtstring

Parent run creation time, in RFC 3339 format.

runStartedAtstring

Parent run start time, in RFC 3339 format. Empty until the run starts.

runFinishedAtstring

Parent run finish time, in RFC 3339 format. Empty until the run finishes.

workflowIdstring

Unique identifier for the parent workflow.

workflowNamestring

Parent workflow name from the YAML name: key, falling back to the file path stem. Empty when neither is available.

workflowPathstring

Parent workflow file path, for example ".depot/workflows/ci.yml". Empty when the workflow YAML was passed via workflowContent in the Run request.

workflowStatusstring

Current state of the parent workflow, for example "queued", "running", "finished", "failed", or "cancelled".

workflowErrorMessagestring

Parent workflow error or cancellation reason, for example a compilation or validation error. Empty when the workflow is healthy.

workflowCreatedAtstring

Parent workflow creation time, in RFC 3339 format.

workflowStartedAtstring

Parent workflow start time, in RFC 3339 format. Empty until the workflow starts.

workflowFinishedAtstring

Parent workflow finish time, in RFC 3339 format. Empty until the workflow finishes.

jobIdstring

Unique identifier for the parent job.

jobKeystring

Parent job key from the workflow, for example "build" or "test".

jobDisplayNamestring

Human-readable display name for the parent job, falling back to jobKey when no display name is set.

jobStatusstring

Current state of the parent job, for example "queued", "waiting", "running", "finished", "failed", "cancelled", or "skipped". "waiting" means the job is blocked behind another run that holds the same concurrency: group slot.

jobConclusionstring

Conclusion of the parent job, for example "success", "failure", "cancelled", "skipped", or "timed_out". Empty until the job concludes.

jobErrorMessagestring

Parent job error message populated for orchestration or worker failures. Empty when the job has no error.

jobCreatedAtstring

Parent job creation time, in RFC 3339 format.

jobDispatchedAtstring

Parent job dispatch time, in RFC 3339 format. Empty until the job is dispatched to a worker.

jobStartedAtstring

Parent job start time, in RFC 3339 format. Empty until the job starts.

jobFinishedAtstring

Parent job finish time, in RFC 3339 format. Empty until the job finishes.

currentAttemptIdstring

Unique identifier for the parent job's most recent attempt. Equals attempt.attempt_id when this is the current attempt.

currentAttemptinteger<int32>

Most recent attempt number for the parent job. Equals attempt.attempt when this is the current attempt.

matrixJobDetailMatrixValue[]

Matrix key/value pairs for the parent job instance. Empty when the job is not part of a matrix strategy.

+Show child parameters

keystring

Matrix dimension name, for example "os" or "node-version".

valuestring

Matrix dimension value for this job instance, serialized as a string.

strategyJobDetailStrategy

Strategy context exposing the parent job's index within its matrix expansion. Unset when no strategy context is available.

+Show child parameters

jobIndexinteger<int32>

Zero-based index of this job within the matrix expansion.

jobTotalinteger<int32>

Total number of jobs produced by the matrix expansion.

runsOnJobDetailRunsOn

Resolved runner configuration for the parent job: labels, image, CPU, memory, and size. Unset when no runner could be resolved for the parent job.

+Show child parameters

labelsstring[]

Runner labels declared on the job's runs-on.

imagestring

Container image used for the job, when one is configured. Empty otherwise.

cpusinteger<int32>

CPU count allocated to the runner. Zero when unset.

memoryGbinteger<int32>

Memory allocated to the runner, in gigabytes. Zero when unset.

sizestring

Resolved runner size string, for example "small" or "large". Empty when unset.

attemptJobDetailAttempt

The requested attempt's identifiers, lifecycle timestamps, conclusion, and sandbox/session linkage.

+Show child parameters

attemptIdstring

Unique identifier for the job attempt.

attemptinteger<int32>

Attempt number, starting at 1 for the first run.

statusstring

Current state of the attempt, for example "running", "finished", "failed", or "cancelled".

conclusionstring

Conclusion of the attempt, for example "success", "failure", "cancelled", "skipped", or "timed_out". Empty until the attempt concludes.

errorMessagestring

Attempt error message populated for orchestration or worker failures. Empty when the attempt has no error.

sandboxIdstring

Unique identifier for the sandbox that ran this attempt, when one exists.

sessionIdstring

Unique identifier for the interactive session attached to that sandbox, when one is available.

createdAtstring

Attempt creation time, in RFC 3339 format.

dispatchedAtstring

Attempt dispatch time, in RFC 3339 format. Empty until the attempt is dispatched to a worker.

startedAtstring

Attempt start time, in RFC 3339 format. Empty until the attempt starts.

finishedAtstring

Attempt finish time, in RFC 3339 format. Empty until the attempt finishes.

isCurrentboolean

True when this attempt is the job's current attempt.

POST/depot.ci.v1.CIService/GetAttempt

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetAttempt \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "attemptId": "attempt_123"8}9JSON

Response

{  "orgId": "org_123",  "runId": "run_123",  "repo": "repo_example",  "ref": "ref_example",  "sha": "b2f5ff47436671b6e533d8dc3614845d",  "headSha": "b2f5ff47436671b6e533d8dc3614845d",  "trigger": "trigger_example",  "runStatus": "runStatus_example"}

GetJobAttemptMetricsCIService.GetJobAttemptMetrics

Returns CPU and memory metrics for one job attempt.

Parameters

attemptIdstring

Unique identifier for the job attempt.

Returns

runCIMetricsRunContext

Parent run context: identifiers, trigger, status, and lifecycle timestamps.

+Show child parameters

runIdstring

Unique identifier for the CI run.

repostring

GitHub repository in owner/name format, for example "depot/cli".

refstring

Git ref the run was triggered against. Empty when the trigger carries no ref.

shastring

Commit SHA the run executes against. Empty for open pull_request runs.

headShastring

Source commit SHA for pull_request and merge_group triggers. Empty for triggers that don't carry a head SHA.

triggerstring

Event that triggered the run, for example "push", "pull_request", "pull_request_target", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".

statusstring

Current state of the run, for example "queued", "running", "finished", "failed", or "cancelled".

createdAtstring

Run creation time, in RFC 3339 format.

startedAtstring

Run start time, in RFC 3339 format. Empty until the run starts.

finishedAtstring

Run finish time, in RFC 3339 format. Empty until the run finishes.

workflowCIMetricsWorkflowContext

Parent workflow context: identifiers, status, and lifecycle timestamps.

+Show child parameters

workflowIdstring

Unique identifier for the workflow.

workflowPathstring

Workflow file path, for example ".depot/workflows/ci.yml". Empty when the workflow YAML was passed via workflowContent in the Run request.

namestring

Workflow name from the YAML name: key, falling back to the file path stem. Empty when not available.

statusstring

Current state of the workflow, for example "queued", "running", "finished", "failed", or "cancelled".

createdAtstring

Workflow creation time, in RFC 3339 format.

startedAtstring

Workflow start time, in RFC 3339 format. Empty until the workflow starts.

finishedAtstring

Workflow finish time, in RFC 3339 format. Empty until the workflow finishes.

jobCIMetricsJobContext

Parent job context: identifiers, status, conclusion, and lifecycle timestamps.

+Show child parameters

jobIdstring

Unique identifier for the job.

jobKeystring

Job key from the workflow, for example "build" or "test".

statusstring

conclusionstring

Conclusion of the job, for example "success", "failure", "cancelled", "skipped", or "timed_out". Empty until the job concludes.

currentAttemptinteger<int32>

Most recent attempt number for this job. Zero until the first attempt is dispatched.

createdAtstring

Job creation time, in RFC 3339 format.

startedAtstring

Job start time, in RFC 3339 format. Empty until the job starts.

finishedAtstring

Job finish time, in RFC 3339 format. Empty until the job finishes.

attemptCIMetricsAttemptMetrics

Attempt-level metrics: attempt context, availability, summary stats, downsampling metadata, and raw samples.

+Show child parameters

attemptCIMetricsAttemptContext

Attempt context: identifiers, status, conclusion, and lifecycle timestamps.

+Show child parameters

attemptIdstring

Unique identifier for the job attempt.

attemptinteger<int32>

Attempt number, starting at 1 for the first run.

statusstring

Current state of the attempt, for example "running", "finished", "failed", or "cancelled".

conclusionstring

Conclusion of the attempt, for example "success", "failure", "cancelled", "skipped", or "timed_out". Empty until the attempt concludes.

sandboxIdstring

Unique identifier for the sandbox that ran this attempt, when one exists.

sessionIdstring

Unique identifier for the interactive session attached to that sandbox, when one is available.

createdAtstring

Attempt creation time, in RFC 3339 format.

startedAtstring

Attempt start time, in RFC 3339 format. Empty until the attempt starts.

finishedAtstring

Attempt finish time, in RFC 3339 format. Empty until the attempt finishes.

availabilityCIMetricsAvailability

Availability code and reason explaining why metrics are or are not present.

+Show child parameters

codeCIMetricsAvailabilityCode

Availability code.

AVAILABLE: metrics samples were observed for the attempt.
NO_SANDBOX: the attempt never ran on a sandbox, so no metrics could be collected.
NO_TIME_RANGE: the attempt has no resolvable start and finish time, so no metric window could be queried.
NO_SAMPLES: the attempt ran on a sandbox but no samples were recorded in its time range.

Possible enum values

reasonstring

Short reason string matching the code, for example "available", "no_sandbox", "no_time_range", or "no_samples".

statsCIMetricsStats

Aggregate CPU and memory statistics computed across the raw samples.

+Show child parameters

sampleCountinteger

Total number of merged samples observed for the attempt.

cpuSampleCountinteger

Number of samples that included a CPU utilization value.

memorySampleCountinteger

Number of samples that included a memory utilization value.

peakCpuUtilizationnumber | null

Peak observed CPU utilization as a fraction from 0 to 1. Unset when no CPU samples were observed.

averageCpuUtilizationnumber | null

Average observed CPU utilization as a fraction from 0 to 1. Unset when no CPU samples were observed.

peakMemoryUtilizationnumber | null

Peak observed memory utilization as a fraction from 0 to 1. Unset when no memory samples were observed.

averageMemoryUtilizationnumber | null

Average observed memory utilization as a fraction from 0 to 1. Unset when no memory samples were observed.

observedStartedAtstring

Timestamp of the first observed sample, in RFC 3339 format. Empty when no samples were observed.

observedFinishedAtstring

Timestamp of the last observed sample, in RFC 3339 format. Empty when no samples were observed.

peakMemoryUsageBytesinteger | string | null

Peak observed memory usage in bytes. Unset when no memory samples were observed.

averageMemoryUsageBytesnumber | null

Average observed memory usage in bytes. Unset when no memory samples were observed.

capCIMetricsCapMetadata

Downsampling metadata describing how raw samples were reduced for transport.

+Show child parameters

rawSampleCountinteger

Raw sample count observed before downsampling.

returnedSampleCountinteger

Number of samples returned in the response.

maxReturnedSampleCountinteger

Hard cap on the number of samples a single response will return.

downsampledboolean

True when the raw samples were downsampled to fit max_returned_sample_count.

downsampleStrategystring

Identifier for the downsampling strategy used, for example "peak_preserving_even". Empty when no downsampling was applied.

samplesCIMetricSample[]

Time-ordered CPU and memory samples for the attempt, possibly downsampled.

+Show child parameters

timestampstring

Sample timestamp, in RFC 3339 format.

cpuUtilizationnumber | null

CPU utilization as a fraction from 0 to 1. Unset when no CPU sample was recorded at this timestamp.

memoryUtilizationnumber | null

Memory utilization as a fraction from 0 to 1. Unset when no memory sample was recorded at this timestamp.

memoryUsageBytesinteger | string | null

Memory usage in bytes. Unset when no memory sample was recorded at this timestamp.

snapshotAtstring

POST/depot.ci.v1.CIService/GetJobAttemptMetrics

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetJobAttemptMetrics \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "attemptId": "attempt_123"8}9JSON

Response

{  "run": {    "runId": "run_123",    "repo": "repo_example",    "ref": "ref_example",    "sha": "b2f5ff47436671b6e533d8dc3614845d",    "headSha": "b2f5ff47436671b6e533d8dc3614845d",    "trigger": "trigger_example"  },  "workflow": {    "workflowId": "workflow_123",    "workflowPath": "workflowPath_example",    "name": "name_example",    "status": "status_example",    "createdAt": "createdAt_example",    "startedAt": "startedAt_example"  },  "job": {    "jobId": "job_123",    "jobKey": "jobKey_example",    "status": "status_example",    "conclusion": "conclusion_example",    "currentAttempt": 1,    "createdAt": "createdAt_example"  },  "attempt": {    "attempt": {      "attemptId": "attempt_123",      "attempt": 1,      "status": "status_example",      "conclusion": "conclusion_example",      "sandboxId": "sandbox_123",      "sessionId": "session_123"    },    "availability": {      "code": "CI_METRICS_AVAILABILITY_CODE_UNSPECIFIED",      "reason": "reason_example"    },    "stats": {      "sampleCount": 1,      "cpuSampleCount": 1,      "memorySampleCount": 1,      "peakCpuUtilization": 1,      "averageCpuUtilization": 1,      "peakMemoryUtilization": 1    },    "cap": {      "rawSampleCount": 1,      "returnedSampleCount": 1,      "maxReturnedSampleCount": 1,      "downsampled": false,      "downsampleStrategy": "downsampleStrategy_example"    },    "samples": [      {        "timestamp": "2026-05-18T18:00:00Z",        "cpuUtilization": 1,        "memoryUtilization": 1,        "memoryUsageBytes": 1      }    ]  },  "snapshotAt": "snapshotAt_example"}

Logs

Read, stream, and export job attempt logs.

GetJobAttemptLogsPOST/depot.ci.v1.CIService/GetJobAttemptLogs StreamJobAttemptLogsPOST/depot.ci.v1.CIService/StreamJobAttemptLogs ExportJobAttemptLogsPOST/depot.ci.v1.CIService/ExportJobAttemptLogs

GetJobAttemptLogsCIService.GetJobAttemptLogs

Returns log lines for a job attempt.

Parameters

attemptIdstring

Unique identifier for the job attempt.

pageTokenstring

Resumes cursor pagination from a previous response.

jobIdstring | null

Unique identifier for a CI job. Resolves to the job's latest attempt.

Returns

linesLogLine[]

Persisted log lines for the attempt, in stream order.

+Show child parameters

stepKeystring

Stable Depot log/step correlation key.

timestampMsinteger | string

Log timestamp as Unix epoch milliseconds.

lineNumberinteger

Persisted line number within the emitting stream.

streaminteger

0 for stdout, 1 for stderr.

bodystring

Log line content without transport framing.

stepIdstring

User-authored workflow step ID, when available.

stepNamestring

User-authored workflow step name, when available.

nextPageTokenstring

Token to retrieve the next page of results; empty if no more pages.

POST/depot.ci.v1.CIService/GetJobAttemptLogs

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetJobAttemptLogs \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "attemptId": "attempt_123",8  "pageToken": "pageToken_example",9  "jobId": "job_123"10}11JSON

Response

{  "lines": [    {      "stepKey": "stepKey_example",      "timestampMs": 1,      "lineNumber": 1,      "stream": 1,      "body": "body_example",      "stepId": "step_123"    }  ],  "nextPageToken": "nextPageToken_example"}

StreamJobAttemptLogsCIService.StreamJobAttemptLogsstream

Follows persisted log lines for a job attempt.

A framed Connect/gRPC server stream (not a raw text response). Clients should consume response messages with a generated client or protocol-aware decoder. Each response includes the current attempt_status. Responses that carry a line also include next_cursor; persist that cursor and send it on a later request to resume after the emitted line.

Parameters

attemptIdstring

Unique identifier for the job attempt. Set exactly one of attempt_id or job_id.

cursorstring

Opaque cursor returned by a previous stream response for the same target. Omit it to stream from the first persisted line.

jobIdstring

Unique identifier for a CI job. The stream resolves it to that job's latest attempt. Set exactly one of attempt_id or job_id.

Returns

lineLogLine

Set when this response carries a persisted log line. Status-only responses can omit it while the stream is waiting for rows.

+Show child parameters

stepKeystring

Stable Depot log/step correlation key.

timestampMsinteger | string

Log timestamp as Unix epoch milliseconds.

lineNumberinteger

Persisted line number within the emitting stream.

streaminteger

0 for stdout, 1 for stderr.

bodystring

Log line content without transport framing.

stepIdstring

User-authored workflow step ID, when available.

stepNamestring

User-authored workflow step name, when available.

nextCursorstring

Opaque cursor to resume after the emitted line.

attemptStatusstring

Current state of the attempt, for example "running", "finished", "failed", or "cancelled".

Server-streaming RPC. The examples show decoded message payloads; the raw HTTP response is Connect-framed and should be read with a generated client or protocol-aware decoder.

POST/depot.ci.v1.CIService/StreamJobAttemptLogs

1# Server-streaming RPC2# Use a generated Connect client or protocol-aware decoder.3# Raw curl cannot send or decode this framed stream as shown.4# Protocol spec: https://connectrpc.com/docs/protocol/#streaming-rpcs5# RPC: CIService.StreamJobAttemptLogs6# Path: /depot.ci.v1.CIService/StreamJobAttemptLogs

Stream messages

{  "line": {    "stepKey": "stepKey_example",    "timestampMs": 1,    "lineNumber": 1,    "stream": 1,    "body": "body_example",    "stepId": "step_123"  },  "nextCursor": "nextCursor_example",  "attemptStatus": "attemptStatus_example"}

ExportJobAttemptLogsCIService.ExportJobAttemptLogsstream

Exports a finite snapshot of persisted log lines.

A framed Connect/gRPC server stream (not a raw HTTP file download). Agents and API clients should call it with a generated client or protocol-aware decoder, read the first metadata response, then append each following chunk response to a file or writer in order. Use the Depot CLI depot ci logs --output-file when a shell-native file download is needed.

Parameters

attemptIdstring

Unique identifier for the job attempt. Set exactly one of attempt_id or job_id.

jobIdstring

Unique identifier for a CI job. Export resolves it to that job's latest attempt at stream start. Set exactly one of attempt_id or job_id.

formatJobAttemptLogExportFormat

Selects the export byte format. Default: text.

Possible enum values

JOB_ATTEMPT_LOG_EXPORT_FORMAT_UNSPECIFIEDJOB_ATTEMPT_LOG_EXPORT_FORMAT_TEXTJOB_ATTEMPT_LOG_EXPORT_FORMAT_JSONL

Returns

chunkobject

chunkstring<byte>required

Export file bytes. Append chunks in stream order to reconstruct the text or JSONL export. In JSON-encoded Connect/grpc-web protocols, bytes are represented using the protocol's base64 encoding.

metadataobject

metadataJobAttemptLogExportMetadatarequired

First response in every successful export stream. Describes the byte format and advisory filename for following chunks.

+Show child parameters

filenamestring

Advisory, non-stable basename hint for generated clients. Not a destination path; clients must not depend on the stem staying stable across calls. The filename is basename-only ASCII and ends in .txt for text or .jsonl for JSONL.

contentTypestring

Exact media type for chunk bytes: text/plain; charset=utf-8 for text or application/x-ndjson; charset=utf-8 for JSONL.

formatJobAttemptLogExportFormat

Selected byte format for following chunk responses.

Possible enum values

JOB_ATTEMPT_LOG_EXPORT_FORMAT_UNSPECIFIEDJOB_ATTEMPT_LOG_EXPORT_FORMAT_TEXTJOB_ATTEMPT_LOG_EXPORT_FORMAT_JSONL

Server-streaming RPC. The examples show decoded message payloads; the raw HTTP response is Connect-framed and should be read with a generated client or protocol-aware decoder.

POST/depot.ci.v1.CIService/ExportJobAttemptLogs

1# Server-streaming RPC2# Use a generated Connect client or protocol-aware decoder.3# Raw curl cannot send or decode this framed stream as shown.4# Protocol spec: https://connectrpc.com/docs/protocol/#streaming-rpcs5# RPC: CIService.ExportJobAttemptLogs6# Path: /depot.ci.v1.CIService/ExportJobAttemptLogs

Stream messages

{  "metadata": {    "filename": "filename_example",    "contentType": "contentType_example",    "format": "JOB_ATTEMPT_LOG_EXPORT_FORMAT_UNSPECIFIED"  }} {  "chunk": "chunk_example"}

Artifacts

List artifacts and create signed artifact download URLs.

ListArtifactsPOST/depot.ci.v1.CIService/ListArtifacts GetArtifactDownloadURLPOST/depot.ci.v1.CIService/GetArtifactDownloadURL

ListArtifactsCIService.ListArtifacts

Returns CI artifact metadata for one run. Signed download URLs are not included.

Parameters

runIdstring

Unique identifier for the CI run. Returned by Run, DispatchWorkflow, and ListRuns.

workflowIdstring | null

Optionally narrows the list to artifacts from one workflow in the run.

jobIdstring | null

Optionally narrows the list to artifacts from one job in the run.

attemptIdstring | null

Optionally narrows the list to artifacts from one job attempt in the run.

pageSizeinteger<int32>

Maximum number of artifacts to return. Capped at 500. Default: 100.

pageTokenstring

Resumes cursor pagination from a previous response.

Returns

artifactsArtifact[]

Artifacts matching the request, up to page_size entries.

+Show child parameters

artifactIdstring

Unique identifier for the artifact. Used to request a download URL.

runIdstring

Unique identifier for the parent CI run.

workflowIdstring

Unique identifier for the parent workflow.

workflowPathstring

Parent workflow file path, for example ".depot/workflows/ci.yml". Empty when the workflow YAML was passed via workflowContent in the Run request.

jobIdstring

Unique identifier for the parent job.

jobKeystring

Parent job key from the workflow, for example "build" or "test".

attemptIdstring

Unique identifier for the job attempt that produced the artifact.

attemptinteger<int32>

Attempt number that produced the artifact, starting at 1.

namestring

Artifact name as authored by the workflow.

sizeBytesinteger | string

Artifact size in bytes.

createdAtstring

Artifact creation time, in RFC 3339 format.

nextPageTokenstring | null

Token to retrieve the next page of results. Unset when no more pages are available.

POST/depot.ci.v1.CIService/ListArtifacts

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/ListArtifacts \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "runId": "run_123",8  "workflowId": "workflow_123",9  "jobId": "job_123",10  "attemptId": "attempt_123",11  "pageSize": 1,12  "pageToken": "pageToken_example"13}14JSON

Response

{  "artifacts": [    {      "artifactId": "artifact_123",      "runId": "run_123",      "workflowId": "workflow_123",      "workflowPath": "workflowPath_example",      "jobId": "job_123",      "jobKey": "jobKey_example"    }  ],  "nextPageToken": "nextPageToken_example"}

GetArtifactDownloadURLCIService.GetArtifactDownloadURL

Returns a signed HTTPS URL for one artifact.

Parameters

artifactIdstring

Unique identifier for the artifact, as returned by ListArtifacts.

Returns

artifactArtifact

Artifact metadata matching the requested artifact_id.

+Show child parameters

artifactIdstring

Unique identifier for the artifact. Used to request a download URL.

runIdstring

Unique identifier for the parent CI run.

workflowIdstring

Unique identifier for the parent workflow.

workflowPathstring

Parent workflow file path, for example ".depot/workflows/ci.yml". Empty when the workflow YAML was passed via workflowContent in the Run request.

jobIdstring

Unique identifier for the parent job.

jobKeystring

Parent job key from the workflow, for example "build" or "test".

attemptIdstring

Unique identifier for the job attempt that produced the artifact.

attemptinteger<int32>

Attempt number that produced the artifact, starting at 1.

namestring

Artifact name as authored by the workflow.

sizeBytesinteger | string

Artifact size in bytes.

createdAtstring

Artifact creation time, in RFC 3339 format.

urlstring

Short-lived signed HTTPS bearer URL for the artifact object. Clients can use it with any standard HTTPS client while the object remains available.

expiresAtstring

Signed URL expiration time (not artifact retention).

POST/depot.ci.v1.CIService/GetArtifactDownloadURL

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetArtifactDownloadURL \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "artifactId": "artifact_123"8}9JSON

Response

{  "artifact": {    "artifactId": "artifact_123",    "runId": "run_123",    "workflowId": "workflow_123",    "workflowPath": "workflowPath_example",    "jobId": "job_123",    "jobKey": "jobKey_example"  },  "url": "https://example.com",  "expiresAt": "expiresAt_example"}

Diagnostics

Fetch deterministic failure diagnosis for CI resources.

GetFailureDiagnosisPOST/depot.ci.v1.CIService/GetFailureDiagnosis

GetFailureDiagnosisCIService.GetFailureDiagnosis

Returns a bounded deterministic failure diagnosis for a run, workflow, job, or attempt.

Parameters

targetIdstring

Unique identifier for the requested CI run, workflow, job, or attempt.

targetTypeFailureDiagnosisTargetType

Resource type for target_id: run, workflow, job, or attempt.

Possible enum values

FAILURE_DIAGNOSIS_TARGET_TYPE_UNSPECIFIEDFAILURE_DIAGNOSIS_TARGET_TYPE_RUNFAILURE_DIAGNOSIS_TARGET_TYPE_WORKFLOWFAILURE_DIAGNOSIS_TARGET_TYPE_JOBFAILURE_DIAGNOSIS_TARGET_TYPE_ATTEMPT

Returns

orgIdstring

Organization that owns the diagnosed resource.

targetFailureDiagnosisTarget

The resource the diagnosis was requested for: run, workflow, job, or attempt.

+Show child parameters

targetIdstring

Unique identifier for the diagnosed resource.

targetTypeFailureDiagnosisTargetType

Resource type for target_id: run, workflow, job, or attempt.

Possible enum values

FAILURE_DIAGNOSIS_TARGET_TYPE_UNSPECIFIEDFAILURE_DIAGNOSIS_TARGET_TYPE_RUNFAILURE_DIAGNOSIS_TARGET_TYPE_WORKFLOWFAILURE_DIAGNOSIS_TARGET_TYPE_JOBFAILURE_DIAGNOSIS_TARGET_TYPE_ATTEMPT

statusFailureDiagnosisResourceStatus

Current state of the target resource.

Possible enum values

FAILURE_DIAGNOSIS_RESOURCE_STATUS_UNSPECIFIEDFAILURE_DIAGNOSIS_RESOURCE_STATUS_QUEUEDFAILURE_DIAGNOSIS_RESOURCE_STATUS_WAITINGFAILURE_DIAGNOSIS_RESOURCE_STATUS_RUNNINGFAILURE_DIAGNOSIS_RESOURCE_STATUS_FINISHEDFAILURE_DIAGNOSIS_RESOURCE_STATUS_FAILEDFAILURE_DIAGNOSIS_RESOURCE_STATUS_CANCELLEDFAILURE_DIAGNOSIS_RESOURCE_STATUS_SKIPPED

contextFailureDiagnosisContext

Resolved parent context for the target, with identifiers, statuses, and conclusions.

+Show child parameters

runIdstring

Unique identifier for the parent CI run.

repostring

GitHub repository in owner/name format, for example "depot/cli".

refstring

Git ref the run was triggered against. Empty when the trigger carries no ref.

shastring

Commit SHA the run executes against. Empty for open pull_request runs.

headShastring

Source commit SHA for pull_request and merge_group triggers. Empty for triggers that don't carry a head SHA.

triggerstring

Event that triggered the run, for example "push", "pull_request", "pull_request_target", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".

runStatusFailureDiagnosisResourceStatus

Current state of the parent run.

Possible enum values

workflowIdstring

Unique identifier for the parent workflow. Empty when the target is a run.

workflowNamestring

Parent workflow name from the YAML name: key, falling back to the file path stem. Empty when not available.

workflowPathstring

Parent workflow file path, for example ".depot/workflows/ci.yml". Empty when the workflow YAML was passed via workflowContent in the Run request, or when the target is a run.

workflowStatusFailureDiagnosisResourceStatus

Current state of the parent workflow.

Possible enum values

jobIdstring

Unique identifier for the parent job. Empty when the target is a run or workflow.

jobKeystring

Parent job key from the workflow. Empty when the target is a run or workflow.

jobDisplayNamestring

Human-readable display name for the parent job, falling back to jobKey when no display name is set.

jobStatusFailureDiagnosisResourceStatus

Current state of the parent job.

Possible enum values

jobConclusionFailureDiagnosisConclusion

Conclusion of the parent job. Unspecified until the job concludes.

Possible enum values

FAILURE_DIAGNOSIS_CONCLUSION_UNSPECIFIEDFAILURE_DIAGNOSIS_CONCLUSION_SUCCESSFAILURE_DIAGNOSIS_CONCLUSION_FAILUREFAILURE_DIAGNOSIS_CONCLUSION_CANCELLEDFAILURE_DIAGNOSIS_CONCLUSION_SKIPPEDFAILURE_DIAGNOSIS_CONCLUSION_TIMED_OUT

attemptIdstring

Unique identifier for the parent attempt. Empty unless the target is an attempt.

attemptinteger<int32>

Attempt number for the parent attempt. Zero unless the target is an attempt.

attemptStatusFailureDiagnosisResourceStatus

Current state of the parent attempt.

Possible enum values

attemptConclusionFailureDiagnosisConclusion

Conclusion of the parent attempt. Unspecified until the attempt concludes.

Possible enum values

truncatedContextFieldsstring[]

Names of context fields that were truncated to fit the response limits.

stateFailureDiagnosisState

Overall diagnosis state.

EMPTY: no failure evidence was found; failure_groups and representative_attempts are empty.
GROUPED_FAILURES: failures bucketed by fingerprint into failure_groups. Returned for run and workflow targets.
FOCUSED_FAILURE: diagnosis focuses on a single job or attempt. Returned for job and attempt targets.
OVER_LIMIT: too many failed candidates to diagnose individually; over_limit_breakdown lists per-workflow and per-job counts instead.

Possible enum values

FAILURE_DIAGNOSIS_STATE_UNSPECIFIEDFAILURE_DIAGNOSIS_STATE_EMPTYFAILURE_DIAGNOSIS_STATE_GROUPED_FAILURESFAILURE_DIAGNOSIS_STATE_FOCUSED_FAILUREFAILURE_DIAGNOSIS_STATE_OVER_LIMIT

emptyReasonFailureDiagnosisEmptyReason

Reason the diagnosis is empty when state is empty. Unspecified otherwise.

Possible enum values

FAILURE_DIAGNOSIS_EMPTY_REASON_UNSPECIFIEDFAILURE_DIAGNOSIS_EMPTY_REASON_NO_FAILURE_EVIDENCE

failureGroupsFailureGroup[]

Failures grouped by deterministic error fingerprint. Empty when state is empty or over limit.

+Show child parameters

fingerprintstring

Stable identifier for this failure group, derived from a normalized fingerprint of the error.

sourcestring

Origin of the error text used to form the fingerprint, for example "attempt_error", "job_error", "workflow_error", or "status".

countinteger

Number of candidate attempts that fell into this group.

errorMessagestring

Representative error message for the group, possibly truncated.

errorMessageTruncatedboolean

True when error_message was truncated to fit the response limit.

errorMessageOriginalLengthinteger

Original length of error_message before truncation.

diagnosisstring

AI-generated diagnosis summarizing the failure. Empty when no diagnosis is available.

possibleFixstring

AI-generated suggested fix. Empty when no suggestion is available.

representativesRepresentativeAttempt[]

Representative attempts for the group, capped by the per-group limit.

+Show child parameters

runIdstring

Unique identifier for the parent CI run.

workflowIdstring

Unique identifier for the parent workflow.

workflowNamestring

Parent workflow name from the YAML name: key, falling back to the file path stem. Empty when not available.

workflowPathstring

Parent workflow file path, for example ".depot/workflows/ci.yml". Empty when the workflow YAML was passed via workflowContent in the Run request.

jobIdstring

Unique identifier for the parent job.

jobKeystring

Parent job key from the workflow.

jobDisplayNamestring

Human-readable display name for the parent job, falling back to jobKey when no display name is set.

jobStatusFailureDiagnosisResourceStatus

Current state of the parent job.

Possible enum values

jobConclusionFailureDiagnosisConclusion

Conclusion of the parent job. Unspecified until the job concludes.

Possible enum values

attemptIdstring

Unique identifier for this attempt.

attemptinteger<int32>

Attempt number, starting at 1 for the first run.

attemptStatusFailureDiagnosisResourceStatus

Current state of the attempt.

Possible enum values

attemptConclusionFailureDiagnosisConclusion

Conclusion of the attempt. Unspecified until the attempt concludes.

Possible enum values

errorMessagestring

Error message captured for this attempt, possibly truncated.

errorMessageTruncatedboolean

True when error_message was truncated to fit the response limit.

errorMessageOriginalLengthinteger

Original length of error_message before truncation.

diagnosisstring

AI-generated diagnosis for this attempt. Empty when no diagnosis is available.

possibleFixstring

AI-generated suggested fix for this attempt. Empty when no suggestion is available.

relevantLinesRelevantErrorLine[]

Selected log lines correlated with the failure.

nextCommandsDrillDownCommand[]

Drill-down commands suggested for this attempt, for example "depot ci logs" or "depot ci summary".

omittedRepresentativeCountinteger

Number of additional candidate attempts omitted from representatives.

representativeAttemptsRepresentativeAttempt[]

Flat list of representative attempts across failure groups, for clients that don't traverse groups.

+Show child parameters

runIdstring

Unique identifier for the parent CI run.

workflowIdstring

Unique identifier for the parent workflow.

workflowNamestring

Parent workflow name from the YAML name: key, falling back to the file path stem. Empty when not available.

workflowPathstring

Parent workflow file path, for example ".depot/workflows/ci.yml". Empty when the workflow YAML was passed via workflowContent in the Run request.

jobIdstring

Unique identifier for the parent job.

jobKeystring

Parent job key from the workflow.

jobDisplayNamestring

Human-readable display name for the parent job, falling back to jobKey when no display name is set.

jobStatusFailureDiagnosisResourceStatus

Current state of the parent job.

Possible enum values

jobConclusionFailureDiagnosisConclusion

Conclusion of the parent job. Unspecified until the job concludes.

Possible enum values

attemptIdstring

Unique identifier for this attempt.

attemptinteger<int32>

Attempt number, starting at 1 for the first run.

attemptStatusFailureDiagnosisResourceStatus

Current state of the attempt.

Possible enum values

attemptConclusionFailureDiagnosisConclusion

Conclusion of the attempt. Unspecified until the attempt concludes.

Possible enum values

errorMessagestring

Error message captured for this attempt, possibly truncated.

errorMessageTruncatedboolean

True when error_message was truncated to fit the response limit.

errorMessageOriginalLengthinteger

Original length of error_message before truncation.

diagnosisstring

AI-generated diagnosis for this attempt. Empty when no diagnosis is available.

possibleFixstring

AI-generated suggested fix for this attempt. Empty when no suggestion is available.

relevantLinesRelevantErrorLine[]

Selected log lines correlated with the failure.

+Show child parameters

stepIdstring

Workflow step identifier the line was emitted from. Empty when not associated with a step.

lineNumberinteger

Persisted line number within the emitting stream.

contentstring

Log line content, possibly truncated.

contentTruncatedboolean

True when content was truncated to fit the per-line limit.

contentOriginalLengthinteger

Original length of content before truncation.

nextCommandsDrillDownCommand[]

Drill-down commands suggested for this attempt, for example "depot ci logs" or "depot ci summary".

+Show child parameters

kindDrillDownCommandKind

Kind of drill-down command.

LOGS: equivalent to depot ci logs <attempt_id>.
SUMMARY: equivalent to depot ci summary <attempt_id>.
DIAGNOSE_WORKFLOW: equivalent to depot ci diagnose --workflow <workflow_id>.
DIAGNOSE_JOB: equivalent to depot ci diagnose --job <job_id>.

Possible enum values

DRILL_DOWN_COMMAND_KIND_UNSPECIFIEDDRILL_DOWN_COMMAND_KIND_LOGSDRILL_DOWN_COMMAND_KIND_SUMMARYDRILL_DOWN_COMMAND_KIND_DIAGNOSE_WORKFLOWDRILL_DOWN_COMMAND_KIND_DIAGNOSE_JOB

argvstring[]

Suggested command and arguments, for example ["depot", "ci", "logs", "<attempt_id>"].

targetIdstring

Unique identifier for the resource the command targets.

labelstring

Human-readable label for the command, for example "Logs" or "Diagnose workflow".

boundsFailureDiagnosisBounds

Limits and counts that describe how the diagnosis was bounded or truncated.

+Show child parameters

failedProblemCandidateCountinteger

Number of failed problem candidates considered for the diagnosis.

failedProblemCandidateCapinteger

Cap on failed problem candidates the diagnosis will examine before switching to over-limit.

totalProblemJobCountinteger

Total number of jobs identified as problem candidates.

skippedDependentCountinteger

Number of jobs skipped because a failed dependency prevented them from running.

totalFailureGroupCountinteger

Total number of distinct failure groups identified, before any cap.

omittedFailureGroupCountinteger

Number of failure groups omitted because the response exceeded the group limit.

failureGroupLimitinteger

Maximum number of failure groups returned in a single response.

representativesPerGroupLimitinteger

Maximum number of representative attempts returned per failure group.

recentAttemptLimitinteger

Maximum number of recent attempts considered for focused diagnoses.

totalAttemptCountinteger

Total number of attempts examined for the target. Populated for focused job diagnoses.

omittedAttemptCountinteger

Number of attempts omitted because the response exceeded the recent attempt limit.

relevantLineLimitinteger

Maximum number of relevant log lines returned per representative attempt.

errorLineBodyCharLimitinteger

Character cap applied to each relevant log line body.

errorMessageCharLimitinteger

Character cap applied to error_message values in the response.

contextLabelCharLimitinteger

Character cap applied to context label strings such as repo, ref, and workflow_name.

overLimitWorkflowBreakdownLimitinteger

Maximum number of workflow breakdown rows returned in an over-limit response.

overLimitJobBreakdownLimitinteger

Maximum number of job breakdown rows returned in an over-limit response.

omittedWorkflowBreakdownCountinteger

Number of workflow breakdown rows omitted because they exceeded the limit.

omittedJobBreakdownCountinteger

Number of job breakdown rows omitted because they exceeded the limit.

truncatedboolean

True when any part of the response was truncated to fit the limits above.

nextCommandsDrillDownCommand[]

Top-level drill-down commands suggested for the target, for example "depot ci logs" or "depot ci diagnose".

+Show child parameters

kindDrillDownCommandKind

Kind of drill-down command.

LOGS: equivalent to depot ci logs <attempt_id>.
SUMMARY: equivalent to depot ci summary <attempt_id>.
DIAGNOSE_WORKFLOW: equivalent to depot ci diagnose --workflow <workflow_id>.
DIAGNOSE_JOB: equivalent to depot ci diagnose --job <job_id>.

Possible enum values

DRILL_DOWN_COMMAND_KIND_UNSPECIFIEDDRILL_DOWN_COMMAND_KIND_LOGSDRILL_DOWN_COMMAND_KIND_SUMMARYDRILL_DOWN_COMMAND_KIND_DIAGNOSE_WORKFLOWDRILL_DOWN_COMMAND_KIND_DIAGNOSE_JOB

argvstring[]

Suggested command and arguments, for example ["depot", "ci", "logs", "<attempt_id>"].

targetIdstring

Unique identifier for the resource the command targets.

labelstring

Human-readable label for the command, for example "Logs" or "Diagnose workflow".

commandCapabilitiesFailureDiagnosisCommandCapabilities

Optional capabilities that gate which drill-down commands clients should surface.

+Show child parameters

summaryCommandAvailableboolean

True when the summary drill-down command is available for this diagnosis.

overLimitBreakdownFailureDiagnosisBreakdownRow[]

Workflow and job breakdown rows returned when the diagnosis exceeds the candidate cap. Empty for other states.

+Show child parameters

targetTypeFailureDiagnosisTargetType

Resource type for target_id, for example workflow or job.

Possible enum values

FAILURE_DIAGNOSIS_TARGET_TYPE_UNSPECIFIEDFAILURE_DIAGNOSIS_TARGET_TYPE_RUNFAILURE_DIAGNOSIS_TARGET_TYPE_WORKFLOWFAILURE_DIAGNOSIS_TARGET_TYPE_JOBFAILURE_DIAGNOSIS_TARGET_TYPE_ATTEMPT

targetIdstring

Unique identifier for the resource this row describes.

labelstring

Human-readable label for the resource, for example a workflow name or job key.

statusFailureDiagnosisResourceStatus

Current state of the resource.

Possible enum values

failedProblemCandidateCountinteger

Number of failed problem candidates attributed to this resource.

nextCommandsDrillDownCommand[]

Drill-down commands suggested for this resource.

+Show child parameters

kindDrillDownCommandKind

Kind of drill-down command.

LOGS: equivalent to depot ci logs <attempt_id>.
SUMMARY: equivalent to depot ci summary <attempt_id>.
DIAGNOSE_WORKFLOW: equivalent to depot ci diagnose --workflow <workflow_id>.
DIAGNOSE_JOB: equivalent to depot ci diagnose --job <job_id>.

Possible enum values

DRILL_DOWN_COMMAND_KIND_UNSPECIFIEDDRILL_DOWN_COMMAND_KIND_LOGSDRILL_DOWN_COMMAND_KIND_SUMMARYDRILL_DOWN_COMMAND_KIND_DIAGNOSE_WORKFLOWDRILL_DOWN_COMMAND_KIND_DIAGNOSE_JOB

argvstring[]

Suggested command and arguments, for example ["depot", "ci", "logs", "<attempt_id>"].

targetIdstring

Unique identifier for the resource the command targets.

labelstring

Human-readable label for the command, for example "Logs" or "Diagnose workflow".

POST/depot.ci.v1.CIService/GetFailureDiagnosis

1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetFailureDiagnosis \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "targetId": "target_123",8  "targetType": "FAILURE_DIAGNOSIS_TARGET_TYPE_UNSPECIFIED"9}10JSON

Response

{  "orgId": "org_123",  "target": {    "targetId": "target_123",    "targetType": "FAILURE_DIAGNOSIS_TARGET_TYPE_UNSPECIFIED",    "status": "FAILURE_DIAGNOSIS_RESOURCE_STATUS_UNSPECIFIED"  },  "context": {    "runId": "run_123",    "repo": "repo_example",    "ref": "ref_example",    "sha": "b2f5ff47436671b6e533d8dc3614845d",    "headSha": "b2f5ff47436671b6e533d8dc3614845d",    "trigger": "trigger_example"  },  "state": "FAILURE_DIAGNOSIS_STATE_UNSPECIFIED",  "emptyReason": "FAILURE_DIAGNOSIS_EMPTY_REASON_UNSPECIFIED",  "failureGroups": [    {      "fingerprint": "fingerprint_example",      "source": "source_example",      "count": 1,      "errorMessage": "errorMessage_example",      "errorMessageTruncated": false,      "errorMessageOriginalLength": 1    }  ],  "representativeAttempts": [    {      "runId": "run_123",      "workflowId": "workflow_123",      "workflowName": "workflowName_example",      "workflowPath": "workflowPath_example",      "jobId": "job_123",      "jobKey": "jobKey_example"    }  ],  "bounds": {    "failedProblemCandidateCount": 1,    "failedProblemCandidateCap": 1,    "totalProblemJobCount": 1,    "skippedDependentCount": 1,    "totalFailureGroupCount": 1,    "omittedFailureGroupCount": 1  }}