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

Errors

Connect status codes

OpenAPI spec

SourceView JSON

API version

OAS

3.1.0

Method index

The Depot CI API provides the following 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. Use `pageSize` to return up to 200 workflows.GetWorkflowReturns a workflow's identity, status, timestamps, parent run context, execution history, and nested jobs and attempts.DispatchWorkflowTriggers a single workflow configured with an `on.workflow_dispatch` trigger and validates inputs against its input schema.RerunWorkflowResets every job in a workflow that's in a terminal state (finished, failed, or cancelled) to queued and runs them all again. Cancel the workflow first if it's still running.CancelWorkflowCancels a queued or running workflow and all its child jobs.

Jobs6

GetJobReturns a job's identity, status, timestamps, runner configuration, parent run and workflow context, dependencies, 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 or cancelled job, along with any skipped jobs that depend on it. Fails when a job that depends on it has already started; use `RetryFailedJobs` to retry related failures together.RetryFailedJobsRetries only the failed and cancelled jobs in a workflow, along with any skipped jobs that depend on them. Jobs that already succeeded are left untouched.CancelJobCancels a queued, waiting, or running job and its active attempt.

Attempts2

GetAttemptReturns an attempt's identity, status, timestamps, and sandbox/session IDs, with parent run, workflow, and job context.GetJobAttemptMetricsReturns CPU and memory metrics for one job attempt.

Logs3

GetJobAttemptLogsReturns persisted log lines for a job attempt, oldest first. Identify the attempt by `attemptId`, or by `jobId` to use the job's latest attempt. Poll with `pageToken` to fetch lines persisted after a previous response.StreamJobAttemptLogsFollows a job attempt's persisted log lines, streaming new lines while the attempt runs.stream ExportJobAttemptLogsExports a finite snapshot of persisted log lines.stream

Artifacts2

ListArtifactsReturns CI artifact metadata for one run, optionally narrowed to a workflow, job, or attempt. Download URLs are not included; request one per artifact with `GetArtifactDownloadURL`.GetArtifactDownloadURLReturns a short-lived signed HTTPS URL for one artifact. The URL expires 5 minutes after issuance.

Diagnostics1

GetFailureDiagnosisReturns a 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

repostringrequired

GitHub repository to run workflows from, 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 (as found in .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

Job key of a single job to run from within a workflow. For example, "build" or "test". When specified, the run skips all other jobs in the workflow. Valid only when a single workflow is specified, either through workflow or a workflowContent entry containing one workflow.

Returns

orgIdstring

Depot 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. Can be "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. Can be "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

runIdstringrequired

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

Returns

orgIdstring

Depot 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. Can be "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

runIdstringrequired

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

Returns

orgIdstring

Depot organization that owns this run.

runIdstring

Unique identifier for the CI run.

statusstring

Current state of the run. Can be "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. Can be "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. Can be "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

runIdstringrequired

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. Falls back to the file path stem when the workflow doesn't set name:. Empty when neither is 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

runIdstringrequired

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

Updated 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. Use pageSize to return up to 200 workflows.

Parameters

pageSizeinteger<int32>

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

namestring

Text to match against the workflow name or file path. Only workflows containing this text are returned.

repostring

Repository to return workflows from, in owner/name format. For example, "depot/cli".

statusstring[]

Statuses of workflows to return. Can be "queued", "running", "finished", "failed", or "cancelled". Multiple values are ORed.

triggerstring

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

shastring

Commit SHA prefix to return workflows for, matched against the parent run's headSha. 1-40 hex characters.

prstring

Pull request number to return workflows for.

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. Falls back to the file path stem when the workflow doesn't set name:. 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. Can be "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 a workflow's identity, status, timestamps, parent run context, execution history, and nested jobs and attempts.

Parameters

workflowIdstringrequired

Unique identifier for the workflow. Returned by GetRunStatus and ListWorkflows.

Returns

orgIdstring

Depot 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. Can be "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. Falls back to the file path stem when the workflow doesn't set name:. 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. Can be "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. Can be "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. Can be "queued", "waiting", "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 configured with an on.workflow_dispatch trigger and validates inputs against its input schema.

Parameters

repostringrequired

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

workflowstringrequired

Path of the workflow file to run, relative to the repo root. For example, ".depot/workflows/deploy.yml". The workflow must be configured with an on.workflow_dispatch trigger. Required.

refstring

Branch or tag to run the workflow on. An unqualified name like "main" is treated as a branch. To use a tag, pass the fully-qualified ref "refs/tags/v1.0". Leave empty to use the repository's default branch. Default: HEAD of the default branch.

inputsobject<string, string>

Inputs to pass to the workflow, as key-value pairs. All values are strings. The server validates each value against the workflow's workflow_dispatch input schema. Boolean inputs must be the string "true" or "false", number inputs must be numeric, and choice inputs must match one of the defined options. Unknown inputs are rejected. A required input must be supplied only if it has no default; one that has a default may be omitted.

Returns

orgIdstring

Depot 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/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 every job in a workflow that's in a terminal state (finished, failed, or cancelled) to queued and runs them all again. Cancel the workflow first if it's still running.

Parameters

workflowIdstringrequired

Unique identifier for the workflow to re-run. Returned by GetRunStatus and ListWorkflows.

Returns

workflowIdstring

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

jobCountinteger<int32>

Number of jobs reset to queued. A re-run resets every job in the workflow, so this is the workflow's total job count.

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

workflowIdstringrequired

Unique identifier for the workflow to cancel. Returned by GetRunStatus and ListWorkflows.

Returns

workflowIdstring

Unique identifier for the workflow. Matches the request workflowId.

statusstring

Updated workflow status. Should be "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 a job's identity, status, timestamps, runner configuration, parent run and workflow context, dependencies, and attempt history.

Parameters

jobIdstringrequired

Unique identifier for the job. Returned by GetRunStatus and GetWorkflow.

Returns

orgIdstring

Depot 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. Can be "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. Falls back to the file path stem when the workflow doesn't set name:. 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. Can be "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. Falls back to jobKey when no display name is set.

jobStatusstring

jobConclusionstring

Conclusion of the job. Can be "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, and cleared while a retried job waits for its next attempt to be 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

Runner configuration from the job's runs-on, such as labels, image, CPU, memory, and size. Unset when no runner configuration is available.

+Show child parameters

labelsstring[]

Runner labels specified 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

Runner size from the job's runs-on, exactly as written in the workflow.

Set whenever the runner config used a ${{ }} expression in its size or image. The value is usually an expression like "${{ vars.RUNNER_SIZE }}", but can be a literal like "4x16" when only the image was the expression. In that case cpus and memoryGb are zero and stay zero for the life of the job, so this is the only runner-size value the API reports for it. Empty when the size was a plain literal with no expressions, in which case cpus and memoryGb carry the resolved values instead.

dependenciesJobDetailDependency[]

Jobs this job depends on. Contains every dependency when the job has 100 or fewer; for jobs with more, a preview of 100 entries that prioritizes failed and cancelled dependencies.

+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. Falls back to jobKey when no display name is set.

statusstring

Current state of the dependency job. Can be "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. Can be "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. Can be "queued", "waiting", "running", "finished", "failed", or "cancelled".

conclusionstring

Conclusion of the attempt. Can be "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 number of dependencies. Set only when dependencies is a capped preview.

dependencyPreviewLimitinteger | null

Maximum number of entries returned in 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 attemptId is set.

attemptIdstring

Unique identifier for a specific job attempt to summarize. Required unless jobId is set. When sent alongside jobId, 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. Can be "queued", "waiting", "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 hasSummary 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

jobIdstringrequired

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. Falls back to the file path stem when the workflow doesn't set name:. Empty when neither is 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. Can be "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. Can be "queued", "waiting", "running", "finished", "failed", or "cancelled".

conclusionstring

Conclusion of the attempt. Can be "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 maxReturnedSampleCount.

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 or cancelled job, along with any skipped jobs that depend on it. Fails when a job that depends on it has already started; use RetryFailedJobs to retry related failures together.

Parameters

workflowIdstringrequired

Unique identifier for the workflow containing the job. Returned by GetRunStatus and ListWorkflows.

jobIdstringrequired

Unique identifier for the job to retry. Returned by GetRunStatus and GetWorkflow.

Returns

jobIdstring

Unique identifier for the job. Matches the request jobId. 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 appears in the attempts array returned by GetJob.

attemptinteger<int32>

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

statusstring

Updated job status. Should be "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 the failed and cancelled jobs in a workflow, along with any skipped jobs that depend on them. Jobs that already succeeded are left untouched.

Parameters

workflowIdstringrequired

Unique identifier for the workflow containing failed jobs. Returned by GetRunStatus and ListWorkflows.

Returns

workflowIdstring

Unique identifier for the workflow. Matches the request workflowId. 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. Includes failed and cancelled jobs, plus any skipped jobs that depend on them. Equal to the number of entries in the jobIds array.

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, waiting, or running job and its active attempt.

Parameters

workflowIdstringrequired

Unique identifier for the workflow containing the job. Returned by GetRunStatus and ListWorkflows.

jobIdstringrequired

Unique identifier for the job to cancel. Returned by GetRunStatus and GetWorkflow.

Returns

jobIdstring

Unique identifier for the job. Matches the request jobId.

statusstring

Updated job status. Should be "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 an attempt's identity, status, timestamps, and sandbox/session IDs, with parent run, workflow, and job context.

Parameters

attemptIdstringrequired

Unique identifier for the job attempt. Returned by GetRunStatus, GetWorkflow, and GetJob.

Returns

orgIdstring

Depot 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. Can be "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. Falls back to the file path stem when the workflow doesn't set name:. 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. Can be "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. Falls back to jobKey when no display name is set.

jobStatusstring

Current state of the parent job. Can be "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. Can be "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.attemptId 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

Runner configuration from the parent job's runs-on: labels, image, CPU, memory, and size. Unset when no runner configuration is available.

+Show child parameters

labelsstring[]

Runner labels specified 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

Runner size from the job's runs-on, exactly as written in the workflow.

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. Can be "queued", "waiting", "running", "finished", "failed", or "cancelled".

conclusionstring

Conclusion of the attempt. Can be "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

attemptIdstringrequired

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. Falls back to the file path stem when the workflow doesn't set name:. Empty when neither is 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. Can be "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. Can be "queued", "waiting", "running", "finished", "failed", or "cancelled".

conclusionstring

Conclusion of the attempt. Can be "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 maxReturnedSampleCount.

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 persisted log lines for a job attempt, oldest first. Identify the attempt by attemptId, or by jobId to use the job's latest attempt. Poll with pageToken to fetch lines persisted after a previous response.

Parameters

attemptIdstring

Unique identifier for the job attempt. Set exactly one of attemptId or jobId.

pageTokenstring

Token to fetch lines after a previous response. Use the nextPageToken value from a prior response. Leave empty to fetch from the first line.

jobIdstring | null

Unique identifier for a CI job. Resolves to the job's latest attempt; the page token pins that attempt, so later pages stay on the same attempt even if a retry creates a newer one. Set exactly one of attemptId or jobId.

Returns

linesLogLine[]

Persisted log lines for the attempt, ordered by timestamp and line number.

+Show child parameters

stepKeystring

Depot-assigned key correlating the line with a workflow step. Stable across responses for the same step.

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 a trailing newline.

stepIdstring

User-authored workflow step ID from the step's id: key. Empty when not set.

stepNamestring

User-authored workflow step name from the step's name: key. Empty when not set.

nextPageTokenstring

Token to fetch lines persisted after this response. Empty when the response contains no lines. While the attempt is running, poll with the newest token to tail new lines.

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 a job attempt's persisted log lines, streaming new lines while the attempt runs.

The response is a Connect/gRPC server stream, not raw text. Consume it with a generated client or a decoder that understands stream framing. Every response reports the attempt's current status. Responses that carry a log line also include nextCursor.

To resume a dropped stream, save the newest nextCursor and send it as cursor on a new request. The new stream picks up after the last line you received. The stream ends on its own once the attempt has finished, failed, or been cancelled and all persisted lines have been sent.

Parameters

attemptIdstring

Unique identifier for the job attempt. Set exactly one of attemptId or jobId.

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 attemptId or jobId.

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

Depot-assigned key correlating the line with a workflow step. Stable across responses for the same step.

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 a trailing newline.

stepIdstring

User-authored workflow step ID from the step's id: key. Empty when not set.

stepNamestring

User-authored workflow step name from the step's name: key. Empty when not set.

nextCursorstring

Opaque cursor to resume after the emitted line. Set on responses that carry a line. Persist the newest value and send it as cursor on a later request.

attemptStatusstring

Current state of the attempt. Can be "queued", "waiting", "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.

The response is a Connect/gRPC server stream, not a raw HTTP file download. Consume it with a generated client or a decoder that understands stream framing. 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 attemptId or jobId.

jobIdstring

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

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, at most 256 KiB per chunk. 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

Suggested filename for saving the export, with the extension matching the format. .txt for text or .jsonl for JSONL. The naming pattern isn't guaranteed and may change, so don't extract the attempt ID or other values from it.

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, optionally narrowed to a workflow, job, or attempt. Download URLs are not included; request one per artifact with GetArtifactDownloadURL.

Parameters

runIdstringrequired

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

workflowIdstring | null

Narrows the list to artifacts from one workflow. Must belong to the run. Leave unset to include all workflows.

jobIdstring | null

Narrows the list to artifacts from one job. Must belong to the run, and to workflowId when both are set. Leave unset to include all jobs.

attemptIdstring | null

Narrows the list to artifacts from one job attempt. Must belong to the run, and to workflowId and jobId when set. Leave unset to include all attempts.

pageSizeinteger<int32>

Number of artifacts to return per page. Maximum: 500. Default: 100.

pageTokenstring

Token to fetch the next page of artifacts. Use the nextPageToken value from a prior response with the same filters. Leave empty to fetch the first page.

Returns

artifactsArtifact[]

Artifacts matching the request, up to pageSize entries.

+Show child parameters

artifactIdstring

Unique identifier for the artifact. Pass it to GetArtifactDownloadURL to download the artifact.

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 short-lived signed HTTPS URL for one artifact. The URL expires 5 minutes after issuance.

Parameters

artifactIdstringrequired

Unique identifier for the artifact. Returned by ListArtifacts.

Returns

artifactArtifact

Artifact metadata for the requested artifactId.

+Show child parameters

artifactIdstring

Unique identifier for the artifact. Pass it to GetArtifactDownloadURL to download the artifact.

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

Signed HTTPS URL for the artifact content. Works with any standard HTTPS client and needs no extra authentication; anyone holding the URL can download the artifact until it expires.

expiresAtstring

Signed URL expiration time, in RFC 3339 format. URLs expire 5 minutes after issuance. Artifact retention is unaffected.

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 failure diagnosis for a run, workflow, job, or attempt.

For run and workflow targets, identical failures are grouped together by error fingerprint. For job and attempt targets, the response is a focused diagnosis of that single job or attempt. When too many jobs failed to diagnose individually, the response is a per-workflow and per-job breakdown instead. When no failure evidence is found, the response is empty. The response is limited to a fixed size and reflects the run's current state. The diagnosis can change while a run is in progress. As more jobs fail, a later call can surface new failures or turn an empty result into a grouped one. As job summaries become available, a later call can also add summary drill-down commands.

Parameters

targetIdstringrequired

Unique identifier for the resource to diagnose: a CI run, workflow, job, or attempt. Must match targetType.

targetTypeFailureDiagnosisTargetTyperequired

Resource type for targetId: 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

Depot 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 targetId: 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. Falls back to the file path stem when the workflow doesn't set name:. 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, 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. Falls 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 found. failureGroups and representativeAttempts are empty.
GROUPED_FAILURES: Failures grouped by fingerprint into failureGroups. 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. overLimitBreakdown 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. Set only when state is EMPTY.

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

Identifier for this failure group, computed from the error text. Two failures share a fingerprint when their errors match after variable details like timestamps, IDs, and file paths are removed, so the same logical error from different attempts falls into the same group.

sourcestring

Origin of the error text used to form the fingerprint. Can be "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 errorMessage was truncated to fit the response limit.

errorMessageOriginalLengthinteger

Length of the full errorMessage, in characters, before any 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[]

Attempts chosen as samples of the group's failure, up to bounds.representativesPerGroupLimit entries. Each job's current attempt is preferred, then more recent attempts.

+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. Falls back to the file path stem when the workflow doesn't set name:. 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.

jobIdstring

Unique identifier for the parent job.

jobKeystring

Parent job key from the workflow.

jobDisplayNamestring

Human-readable display name for the parent job. Falls 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 errorMessage was truncated to fit the response limit.

errorMessageOriginalLengthinteger

Length of the full errorMessage, in characters, before any 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[]

AI-selected log lines correlated with the failure. Empty when no log analysis is available.

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[]

Representative attempts from all failure groups in one list. Contains the same entries as the nested failureGroups[].representatives lists. Empty when state is EMPTY or OVER_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. Falls back to the file path stem when the workflow doesn't set name:. 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.

jobIdstring

Unique identifier for the parent job.

jobKeystring

Parent job key from the workflow.

jobDisplayNamestring

Human-readable display name for the parent job. Falls 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 errorMessage was truncated to fit the response limit.

errorMessageOriginalLengthinteger

Length of the full errorMessage, in characters, before any 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[]

AI-selected log lines correlated with the failure. Empty when no log analysis is available.

+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

Length of the full content, in characters, before any 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, the failed and cancelled jobs the diagnosis examined.

failedProblemCandidateCapinteger

Maximum number of failed problem candidates the diagnosis examines. Above this limit the response switches to the over-limit breakdown.

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 errorMessage values in the response.

contextLabelCharLimitinteger

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

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[]

Drill-down commands from all representative attempts in one list. For example, "depot ci logs" or "depot ci diagnose". Contains the same entries as the nested representativeAttempts[].nextCommands lists. In an OVER_LIMIT response, contains the diagnose commands from overLimitBreakdown[].nextCommands instead. Empty when state is EMPTY.

+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

Availability flags for the suggested drill-down commands. Clients should hide commands whose flag is false. Unset means all commands are available.

+Show child parameters

summaryCommandAvailableboolean

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

overLimitBreakdownFailureDiagnosisBreakdownRow[]

Failure counts by workflow and by job, returned when failed problem candidates exceed bounds.failedProblemCandidateCap. Empty for other states.

+Show child parameters

targetTypeFailureDiagnosisTargetType

Resource type for targetId: 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  }}

Errors

Every method returns errors as a Connect error object with a string code, a developer-facing message, and optional details. The status code maps to an HTTP status for callers using the JSON over HTTP transport. The following codes may be returned by the Depot CI API.

Code

HTTP

When it happens

Common causes

unauthenticatedgRPC 16

401

The request has no valid token.

Missing Authorization header, a non-Bearer scheme, or an invalid or expired token.

permission_deniedgRPC 7

403

The token is valid but not allowed for this resource or action.

Wrong token type, the caller is not a member of the organization, a missing x-depot-org header on an organization token, or the organization has no GitHub Code Connection.

invalid_argumentgRPC 3

400

A request field is missing or malformed.

A repo not in owner/name format, a missing run, workflow, or artifact identifier, an invalid page token, a non-numeric pr, a malformed sha, or an unsupported target_type or log format.

not_foundgRPC 5

404

The referenced resource does not exist or is not visible to the caller.

An unknown run, workflow, job, attempt, or artifact identifier, or a workflow that has no workflow_dispatch trigger.

failed_preconditiongRPC 9

412

The resource exists but is not in a valid state for the action.

Cancelling a run, workflow, or job that is not queued or running, retrying before a workflow finishes, or a status that changed mid-request.

resource_exhaustedgRPC 8

429

A limit was reached.

Too many concurrent log streams for the token, organization, or attempt, a log stream or export that exceeded its maximum duration, or a metrics result that is too large.

unavailablegRPC 14

503

A dependency is temporarily down. The request can be retried.

The log or metrics store is unavailable, or a transient read failure occurred.

internalgRPC 13

500

An unexpected server-side failure occurred.

A download URL could not be generated, a trigger config failed to parse, or a database write failed.