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.
Secret and variable management methods use the depot.ci.v3beta2 package. This API surface is in beta and may change.
RPC basics
Base URL
https://api.depot.devProtocol
Connect RPC over HTTPEncoding
JSON or Connect JSONMethod index
The Depot CI API provides the following methods, grouped by resource.
Runs6RunTriggers 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. Workflows5ListWorkflowsReturns 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. Jobs6GetJobReturns 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. Runs
Create, inspect, measure, and cancel CI runs.
RunCIService.Run
Triggers a CI run. Runs can contain one or more workflows.
Parameters
repostringrequired
GitHub or Origin repository to run workflows from, in owner/name format.
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.
forgeForge
Source-code host containing the repository. Defaults to GitHub for compatibility with older clients.
Possible enum values
FORGE_UNSPECIFIEDFORGE_GITHUBFORGE_ORIGIN
Returns
orgIdstring
Depot organization that owns this 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 "forge": "FORGE_UNSPECIFIED"15}16JSON
{ "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", "issue_comment", "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", "issue_comment", "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
{ "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.
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", "issue_comment", "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
{ "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.
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
{ "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.
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", "issue_comment", "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
{ "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.
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
{ "runId": "run_123", "status": "status_example"}
Workflows
List, inspect, dispatch, rerun, and cancel CI workflows.
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", "issue_comment", "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", "issue_comment", "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
{ "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.
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", "issue_comment", "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
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.
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
{ "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.
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
{ "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.
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
{ "workflowId": "workflow_123", "jobCount": 1}
CancelWorkflowCIService.CancelWorkflow
Cancels a queued or running workflow and all its child jobs.
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
{ "workflowId": "workflow_123", "status": "status_example"}
Jobs
Inspect, summarize, measure, retry, and cancel CI jobs.
GetJobCIService.GetJob
Returns a job's identity, status, timestamps, runner configuration, parent run and workflow context, dependencies, and attempt history.
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", "issue_comment", "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
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.
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.
snapshotRefstring
Immutable snapshot image reference resolved for this job. Empty when the job is not a snapshot producer or the resolved ref is not available.
snapshotCachedboolean | null
True when the snapshot producer used an existing snapshot instead of running setup work. Unset when the job is not a snapshot producer or the resolved ref is not available.
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
{ "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
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.
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
{ "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", "issue_comment", "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
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.
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
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/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
{ "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.
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
{ "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.
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
{ "workflowId": "workflow_123", "jobIds": [ "job_123" ], "jobCount": 1}
CancelJobCIService.CancelJob
Cancels a queued, waiting, or running job and its active attempt.
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
{ "jobId": "job_123", "status": "status_example"}
Attempts
Inspect job attempts and their execution metrics.
GetAttemptCIService.GetAttempt
Returns an attempt's identity, status, timestamps, and sandbox/session IDs, with parent run, workflow, and job context.
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", "issue_comment", "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.
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.
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
{ "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", "issue_comment", "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
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.
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
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.
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
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/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
{ "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.
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
{ "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
{ "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
{ "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.
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
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
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
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
{ "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.
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
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
{ "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"}
Secrets
List and manage CI secrets and their variants.
ListSecretsSecretService.ListSecrets
Parameters
pagePageRequest
+Show child parameters
pageinteger
1-based page number. Defaults to 1.
pageSizeinteger
Number of parent resources per page.
querystring
Optional name search/prefix/filter depending on product behavior.
attributesAttribute[]
Optional filter for variants matching these attributes.
+Show child parameters
keystringrequired
Attribute dimension. Can be "repository", "environment", "branch", or "workflow".
valuestringrequired
Exact value or pattern, depending on key.
contextAttribute[]
Optional job context for variants that could apply to a workflow run.
Variants without a context key match all values for that key.
+Show child parameters
keystringrequired
Attribute dimension. Can be "repository", "environment", "branch", or "workflow".
valuestringrequired
Exact value or pattern, depending on key.
Returns
secretsSecret[]
+Show child parameters
variantsSecretVariant[]
+Show child parameters
attributesAttribute[]
Attributes describe the job context this variant matches against.
A variant with no attributes matches all jobs.
lastModifiedoneOf<google.protobuf.Timestamp | null>
valueGroupIndexinteger | null
Deprecated: value group indicators are no longer displayed.
resolutionVariantResolution
Server-computed for list requests with context. Describes whether this variant is the definite
winner, could still win with more context, or is lower priority than another candidate.
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIEDVARIANT_RESOLUTION_RESOLVEDVARIANT_RESOLUTION_INDETERMINATEVARIANT_RESOLUTION_LOWER_PRIORITY
lastModifiedoneOf<google.protobuf.Timestamp | null>
resolutionVariantResolution
Deprecated: use SecretVariant.resolution for per-row resolution details.
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIEDVARIANT_RESOLUTION_RESOLVEDVARIANT_RESOLUTION_INDETERMINATEVARIANT_RESOLUTION_LOWER_PRIORITY
pagePageResponse
+Show child parameters
POST/depot.ci.v3beta2.SecretService/ListSecrets
1curl -X POST https://api.depot.dev/depot.ci.v3beta2.SecretService/ListSecrets \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "page": {8 "page": 1,9 "pageSize": 110 },11 "query": "query_example",12 "attributes": [13 {14 "key": "key_example",15 "value": "value_example"16 }17 ],18 "context": [19 {20 "key": "key_example",21 "value": "value_example"22 }23 ]24}25JSON
{ "secrets": [ { "id": "id_123", "name": "name_example", "variants": [ { "id": "id_123", "secretId": "secret_123", "name": "name_example", "description": "description_example", "attributes": [ "attributes_example" ], "lastModified": "2026-05-18T18:00:00Z" } ], "variantCount": 1, "lastModified": "2026-05-18T18:00:00Z", "resolution": "VARIANT_RESOLUTION_UNSPECIFIED" } ], "page": { "page": 1, "pageSize": 1, "hasMore": false }}
ListSecretAttributesSecretService.ListSecretAttributes
Parameters
This method does not require request parameters.
Returns
attributesAttributeLinkCount[]
+Show child parameters
attributeAttribute
+Show child parameters
keystringrequired
Attribute dimension. Can be "repository", "environment", "branch", or "workflow".
valuestringrequired
Exact value or pattern, depending on key.
linkCountinteger
Number of variants linked to this attribute.
POST/depot.ci.v3beta2.SecretService/ListSecretAttributes
1curl -X POST https://api.depot.dev/depot.ci.v3beta2.SecretService/ListSecretAttributes \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{}7JSON
{ "attributes": [ { "attribute": { "key": "key_example", "value": "value_example" }, "linkCount": 1 } ]}
GetSecretSecretService.GetSecret
Returns
secretSecret
+Show child parameters
variantsSecretVariant[]
+Show child parameters
attributesAttribute[]
Attributes describe the job context this variant matches against.
A variant with no attributes matches all jobs.
lastModifiedoneOf<google.protobuf.Timestamp | null>
valueGroupIndexinteger | null
Deprecated: value group indicators are no longer displayed.
resolutionVariantResolution
Server-computed for list requests with context. Describes whether this variant is the definite
winner, could still win with more context, or is lower priority than another candidate.
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIEDVARIANT_RESOLUTION_RESOLVEDVARIANT_RESOLUTION_INDETERMINATEVARIANT_RESOLUTION_LOWER_PRIORITY
lastModifiedoneOf<google.protobuf.Timestamp | null>
resolutionVariantResolution
Deprecated: use SecretVariant.resolution for per-row resolution details.
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIEDVARIANT_RESOLUTION_RESOLVEDVARIANT_RESOLUTION_INDETERMINATEVARIANT_RESOLUTION_LOWER_PRIORITY
POST/depot.ci.v3beta2.SecretService/GetSecret
1curl -X POST https://api.depot.dev/depot.ci.v3beta2.SecretService/GetSecret \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "id": "id_123"8}9JSON
{ "secret": { "id": "id_123", "name": "name_example", "variants": [ { "id": "id_123", "secretId": "secret_123", "name": "name_example", "description": "description_example", "attributes": [ "attributes_example" ], "lastModified": "2026-05-18T18:00:00Z" } ], "variantCount": 1, "lastModified": "2026-05-18T18:00:00Z", "resolution": "VARIANT_RESOLUTION_UNSPECIFIED" }}
GetSecretVariantSecretService.GetSecretVariant
Returns
variantSecretVariant
+Show child parameters
attributesAttribute[]
Attributes describe the job context this variant matches against.
A variant with no attributes matches all jobs.
+Show child parameters
keystringrequired
Attribute dimension. Can be "repository", "environment", "branch", or "workflow".
valuestringrequired
Exact value or pattern, depending on key.
lastModifiedoneOf<google.protobuf.Timestamp | null>
valueGroupIndexinteger | null
Deprecated: value group indicators are no longer displayed.
resolutionVariantResolution
Server-computed for list requests with context. Describes whether this variant is the definite
winner, could still win with more context, or is lower priority than another candidate.
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIEDVARIANT_RESOLUTION_RESOLVEDVARIANT_RESOLUTION_INDETERMINATEVARIANT_RESOLUTION_LOWER_PRIORITY
POST/depot.ci.v3beta2.SecretService/GetSecretVariant
1curl -X POST https://api.depot.dev/depot.ci.v3beta2.SecretService/GetSecretVariant \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "id": "id_123"8}9JSON
{ "variant": { "id": "id_123", "secretId": "secret_123", "name": "name_example", "description": "description_example", "attributes": [ { "key": "key_example", "value": "value_example" } ], "lastModified": "2026-05-18T18:00:00Z" }}
CreateSecretVariantSecretService.CreateSecretVariant
Parameters
variantNamestring
Defaults to "default" when empty.
attributesAttribute[]
Attributes describe the job context this variant matches against.
Empty attributes means the variant is available everywhere.
+Show child parameters
keystringrequired
Attribute dimension. Can be "repository", "environment", "branch", or "workflow".
valuestringrequired
Exact value or pattern, depending on key.
Returns
secretSecret
+Show child parameters
variantsSecretVariant[]
+Show child parameters
attributesAttribute[]
Attributes describe the job context this variant matches against.
A variant with no attributes matches all jobs.
lastModifiedoneOf<google.protobuf.Timestamp | null>
valueGroupIndexinteger | null
Deprecated: value group indicators are no longer displayed.
resolutionVariantResolution
Server-computed for list requests with context. Describes whether this variant is the definite
winner, could still win with more context, or is lower priority than another candidate.
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIEDVARIANT_RESOLUTION_RESOLVEDVARIANT_RESOLUTION_INDETERMINATEVARIANT_RESOLUTION_LOWER_PRIORITY
lastModifiedoneOf<google.protobuf.Timestamp | null>
resolutionVariantResolution
Deprecated: use SecretVariant.resolution for per-row resolution details.
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIEDVARIANT_RESOLUTION_RESOLVEDVARIANT_RESOLUTION_INDETERMINATEVARIANT_RESOLUTION_LOWER_PRIORITY
variantSecretVariant
+Show child parameters
attributesAttribute[]
Attributes describe the job context this variant matches against.
A variant with no attributes matches all jobs.
+Show child parameters
keystringrequired
Attribute dimension. Can be "repository", "environment", "branch", or "workflow".
valuestringrequired
Exact value or pattern, depending on key.
lastModifiedoneOf<google.protobuf.Timestamp | null>
valueGroupIndexinteger | null
Deprecated: value group indicators are no longer displayed.
resolutionVariantResolution
Server-computed for list requests with context. Describes whether this variant is the definite
winner, could still win with more context, or is lower priority than another candidate.
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIEDVARIANT_RESOLUTION_RESOLVEDVARIANT_RESOLUTION_INDETERMINATEVARIANT_RESOLUTION_LOWER_PRIORITY
POST/depot.ci.v3beta2.SecretService/CreateSecretVariant
1curl -X POST https://api.depot.dev/depot.ci.v3beta2.SecretService/CreateSecretVariant \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "secretName": "secretName_example",8 "variantName": "variantName_example",9 "value": "value_example",10 "description": "description_example",11 "attributes": [12 {13 "key": "key_example",14 "value": "value_example"15 }16 ]17}18JSON
{ "secret": { "id": "id_123", "name": "name_example", "variants": [ { "id": "id_123", "secretId": "secret_123", "name": "name_example", "description": "description_example", "attributes": [ "attributes_example" ], "lastModified": "2026-05-18T18:00:00Z" } ], "variantCount": 1, "lastModified": "2026-05-18T18:00:00Z", "resolution": "VARIANT_RESOLUTION_UNSPECIFIED" }, "variant": { "id": "id_123", "secretId": "secret_123", "name": "name_example", "description": "description_example", "attributes": [ { "key": "key_example", "value": "value_example" } ], "lastModified": "2026-05-18T18:00:00Z" }, "createdSecret": false, "createdVariant": false}
SetSecretVariantSecretService.SetSecretVariant
Parameters
variantNamestring
Defaults to "default" when empty.
attributesAttribute[]
Attributes describe the job context this variant matches against.
Empty attributes means the variant is available everywhere.
+Show child parameters
keystringrequired
Attribute dimension. Can be "repository", "environment", "branch", or "workflow".
valuestringrequired
Exact value or pattern, depending on key.
Returns
secretSecret
+Show child parameters
variantsSecretVariant[]
+Show child parameters
attributesAttribute[]
Attributes describe the job context this variant matches against.
A variant with no attributes matches all jobs.
lastModifiedoneOf<google.protobuf.Timestamp | null>
valueGroupIndexinteger | null
Deprecated: value group indicators are no longer displayed.
resolutionVariantResolution
Server-computed for list requests with context. Describes whether this variant is the definite
winner, could still win with more context, or is lower priority than another candidate.
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIEDVARIANT_RESOLUTION_RESOLVEDVARIANT_RESOLUTION_INDETERMINATEVARIANT_RESOLUTION_LOWER_PRIORITY
lastModifiedoneOf<google.protobuf.Timestamp | null>
resolutionVariantResolution
Deprecated: use SecretVariant.resolution for per-row resolution details.
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIEDVARIANT_RESOLUTION_RESOLVEDVARIANT_RESOLUTION_INDETERMINATEVARIANT_RESOLUTION_LOWER_PRIORITY
variantSecretVariant
+Show child parameters
attributesAttribute[]
Attributes describe the job context this variant matches against.
A variant with no attributes matches all jobs.
+Show child parameters
keystringrequired
Attribute dimension. Can be "repository", "environment", "branch", or "workflow".
valuestringrequired
Exact value or pattern, depending on key.
lastModifiedoneOf<google.protobuf.Timestamp | null>
valueGroupIndexinteger | null
Deprecated: value group indicators are no longer displayed.
resolutionVariantResolution
Server-computed for list requests with context. Describes whether this variant is the definite
winner, could still win with more context, or is lower priority than another candidate.
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIEDVARIANT_RESOLUTION_RESOLVEDVARIANT_RESOLUTION_INDETERMINATEVARIANT_RESOLUTION_LOWER_PRIORITY
POST/depot.ci.v3beta2.SecretService/SetSecretVariant
1curl -X POST https://api.depot.dev/depot.ci.v3beta2.SecretService/SetSecretVariant \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "secretName": "secretName_example",8 "variantName": "variantName_example",9 "value": "value_example",10 "description": "description_example",11 "attributes": [12 {13 "key": "key_example",14 "value": "value_example"15 }16 ]17}18JSON
{ "secret": { "id": "id_123", "name": "name_example", "variants": [ { "id": "id_123", "secretId": "secret_123", "name": "name_example", "description": "description_example", "attributes": [ "attributes_example" ], "lastModified": "2026-05-18T18:00:00Z" } ], "variantCount": 1, "lastModified": "2026-05-18T18:00:00Z", "resolution": "VARIANT_RESOLUTION_UNSPECIFIED" }, "variant": { "id": "id_123", "secretId": "secret_123", "name": "name_example", "description": "description_example", "attributes": [ { "key": "key_example", "value": "value_example" } ], "lastModified": "2026-05-18T18:00:00Z" }, "createdSecret": false, "createdVariant": false}
UpdateSecretVariantMetadataSecretService.UpdateSecretVariantMetadata
Parameters
namestringrequired
Allows renaming a variant, e.g. default -> production.
attributesAttribute[]
+Show child parameters
keystringrequired
Attribute dimension. Can be "repository", "environment", "branch", or "workflow".
valuestringrequired
Exact value or pattern, depending on key.
Returns
variantSecretVariant
+Show child parameters
attributesAttribute[]
Attributes describe the job context this variant matches against.
A variant with no attributes matches all jobs.
+Show child parameters
keystringrequired
Attribute dimension. Can be "repository", "environment", "branch", or "workflow".
valuestringrequired
Exact value or pattern, depending on key.
lastModifiedoneOf<google.protobuf.Timestamp | null>
valueGroupIndexinteger | null
Deprecated: value group indicators are no longer displayed.
resolutionVariantResolution
Server-computed for list requests with context. Describes whether this variant is the definite
winner, could still win with more context, or is lower priority than another candidate.
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIEDVARIANT_RESOLUTION_RESOLVEDVARIANT_RESOLUTION_INDETERMINATEVARIANT_RESOLUTION_LOWER_PRIORITY
POST/depot.ci.v3beta2.SecretService/UpdateSecretVariantMetadata
1curl -X POST https://api.depot.dev/depot.ci.v3beta2.SecretService/UpdateSecretVariantMetadata \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "variantId": "variant_123",8 "name": "name_example",9 "description": "description_example",10 "attributes": [11 {12 "key": "key_example",13 "value": "value_example"14 }15 ]16}17JSON
{ "variant": { "id": "id_123", "secretId": "secret_123", "name": "name_example", "description": "description_example", "attributes": [ { "key": "key_example", "value": "value_example" } ], "lastModified": "2026-05-18T18:00:00Z" }}
UpdateSecretVariantValueSecretService.UpdateSecretVariantValue
Returns
variantSecretVariant
+Show child parameters
attributesAttribute[]
Attributes describe the job context this variant matches against.
A variant with no attributes matches all jobs.
+Show child parameters
keystringrequired
Attribute dimension. Can be "repository", "environment", "branch", or "workflow".
valuestringrequired
Exact value or pattern, depending on key.
lastModifiedoneOf<google.protobuf.Timestamp | null>
valueGroupIndexinteger | null
Deprecated: value group indicators are no longer displayed.
resolutionVariantResolution
Server-computed for list requests with context. Describes whether this variant is the definite
winner, could still win with more context, or is lower priority than another candidate.
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIEDVARIANT_RESOLUTION_RESOLVEDVARIANT_RESOLUTION_INDETERMINATEVARIANT_RESOLUTION_LOWER_PRIORITY
POST/depot.ci.v3beta2.SecretService/UpdateSecretVariantValue
1curl -X POST https://api.depot.dev/depot.ci.v3beta2.SecretService/UpdateSecretVariantValue \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "variantId": "variant_123",8 "value": "value_example"9}10JSON
{ "variant": { "id": "id_123", "secretId": "secret_123", "name": "name_example", "description": "description_example", "attributes": [ { "key": "key_example", "value": "value_example" } ], "lastModified": "2026-05-18T18:00:00Z" }}
DeleteSecretVariantSecretService.DeleteSecretVariant
POST/depot.ci.v3beta2.SecretService/DeleteSecretVariant
1curl -X POST https://api.depot.dev/depot.ci.v3beta2.SecretService/DeleteSecretVariant \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "variantId": "variant_123"8}9JSON
{ "deletedSecret": false}
DeleteSecretSecretService.DeleteSecret
Returns
This method does not document a success response.
POST/depot.ci.v3beta2.SecretService/DeleteSecret
1curl -X POST https://api.depot.dev/depot.ci.v3beta2.SecretService/DeleteSecret \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "id": "id_123"8}9JSON
Variables
List and manage CI variables and their variants.
ListVariablesVariableService.ListVariables
Parameters
pagePageRequest
+Show child parameters
pageinteger
1-based page number. Defaults to 1.
pageSizeinteger
Number of parent resources per page.
attributesAttribute[]
+Show child parameters
keystringrequired
Attribute dimension. Can be "repository", "environment", "branch", or "workflow".
valuestringrequired
Exact value or pattern, depending on key.
contextAttribute[]
Optional job context for variants that could apply to a workflow run.
Variants without a context key match all values for that key.
+Show child parameters
keystringrequired
Attribute dimension. Can be "repository", "environment", "branch", or "workflow".
valuestringrequired
Exact value or pattern, depending on key.
Returns
variablesVariable[]
+Show child parameters
variantsVariableVariant[]
+Show child parameters
lastModifiedoneOf<google.protobuf.Timestamp | null>
lastModifiedoneOf<google.protobuf.Timestamp | null>
resolutionVariantResolution
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIEDVARIANT_RESOLUTION_RESOLVEDVARIANT_RESOLUTION_INDETERMINATEVARIANT_RESOLUTION_LOWER_PRIORITY
pagePageResponse
+Show child parameters
POST/depot.ci.v3beta2.VariableService/ListVariables
1curl -X POST https://api.depot.dev/depot.ci.v3beta2.VariableService/ListVariables \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "page": {8 "page": 1,9 "pageSize": 110 },11 "query": "query_example",12 "attributes": [13 {14 "key": "key_example",15 "value": "value_example"16 }17 ],18 "context": [19 {20 "key": "key_example",21 "value": "value_example"22 }23 ]24}25JSON
{ "variables": [ { "id": "id_123", "name": "name_example", "variants": [ { "id": "id_123", "variableId": "variable_123", "name": "name_example", "value": "value_example", "description": "description_example", "attributes": [ "attributes_example" ] } ], "variantCount": 1, "lastModified": "2026-05-18T18:00:00Z", "resolution": "VARIANT_RESOLUTION_UNSPECIFIED" } ], "page": { "page": 1, "pageSize": 1, "hasMore": false }}
ListVariableAttributesVariableService.ListVariableAttributes
Parameters
This method does not require request parameters.
Returns
attributesAttributeLinkCount[]
+Show child parameters
attributeAttribute
+Show child parameters
keystringrequired
Attribute dimension. Can be "repository", "environment", "branch", or "workflow".
valuestringrequired
Exact value or pattern, depending on key.
linkCountinteger
Number of variants linked to this attribute.
POST/depot.ci.v3beta2.VariableService/ListVariableAttributes
1curl -X POST https://api.depot.dev/depot.ci.v3beta2.VariableService/ListVariableAttributes \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{}7JSON
{ "attributes": [ { "attribute": { "key": "key_example", "value": "value_example" }, "linkCount": 1 } ]}
GetVariableVariableService.GetVariable
Returns
variableVariable
+Show child parameters
variantsVariableVariant[]
+Show child parameters
lastModifiedoneOf<google.protobuf.Timestamp | null>
lastModifiedoneOf<google.protobuf.Timestamp | null>
resolutionVariantResolution
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIEDVARIANT_RESOLUTION_RESOLVEDVARIANT_RESOLUTION_INDETERMINATEVARIANT_RESOLUTION_LOWER_PRIORITY
POST/depot.ci.v3beta2.VariableService/GetVariable
1curl -X POST https://api.depot.dev/depot.ci.v3beta2.VariableService/GetVariable \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "id": "id_123"8}9JSON
{ "variable": { "id": "id_123", "name": "name_example", "variants": [ { "id": "id_123", "variableId": "variable_123", "name": "name_example", "value": "value_example", "description": "description_example", "attributes": [ "attributes_example" ] } ], "variantCount": 1, "lastModified": "2026-05-18T18:00:00Z", "resolution": "VARIANT_RESOLUTION_UNSPECIFIED" }}
GetVariableVariantVariableService.GetVariableVariant
Returns
variantVariableVariant
+Show child parameters
attributesAttribute[]
+Show child parameters
keystringrequired
Attribute dimension. Can be "repository", "environment", "branch", or "workflow".
valuestringrequired
Exact value or pattern, depending on key.
lastModifiedoneOf<google.protobuf.Timestamp | null>
POST/depot.ci.v3beta2.VariableService/GetVariableVariant
1curl -X POST https://api.depot.dev/depot.ci.v3beta2.VariableService/GetVariableVariant \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "id": "id_123"8}9JSON
{ "variant": { "id": "id_123", "variableId": "variable_123", "name": "name_example", "value": "value_example", "description": "description_example", "attributes": [ { "key": "key_example", "value": "value_example" } ] }}
CreateVariableVariantVariableService.CreateVariableVariant
Parameters
variableNamestringrequired
variantNamestring
Defaults to "default" when empty.
attributesAttribute[]
+Show child parameters
keystringrequired
Attribute dimension. Can be "repository", "environment", "branch", or "workflow".
valuestringrequired
Exact value or pattern, depending on key.
Returns
variableVariable
+Show child parameters
variantsVariableVariant[]
+Show child parameters
lastModifiedoneOf<google.protobuf.Timestamp | null>
lastModifiedoneOf<google.protobuf.Timestamp | null>
resolutionVariantResolution
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIEDVARIANT_RESOLUTION_RESOLVEDVARIANT_RESOLUTION_INDETERMINATEVARIANT_RESOLUTION_LOWER_PRIORITY
variantVariableVariant
+Show child parameters
attributesAttribute[]
+Show child parameters
keystringrequired
Attribute dimension. Can be "repository", "environment", "branch", or "workflow".
valuestringrequired
Exact value or pattern, depending on key.
lastModifiedoneOf<google.protobuf.Timestamp | null>
POST/depot.ci.v3beta2.VariableService/CreateVariableVariant
1curl -X POST https://api.depot.dev/depot.ci.v3beta2.VariableService/CreateVariableVariant \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "variableName": "variableName_example",8 "variantName": "variantName_example",9 "value": "value_example",10 "description": "description_example",11 "attributes": [12 {13 "key": "key_example",14 "value": "value_example"15 }16 ]17}18JSON
{ "variable": { "id": "id_123", "name": "name_example", "variants": [ { "id": "id_123", "variableId": "variable_123", "name": "name_example", "value": "value_example", "description": "description_example", "attributes": [ "attributes_example" ] } ], "variantCount": 1, "lastModified": "2026-05-18T18:00:00Z", "resolution": "VARIANT_RESOLUTION_UNSPECIFIED" }, "variant": { "id": "id_123", "variableId": "variable_123", "name": "name_example", "value": "value_example", "description": "description_example", "attributes": [ { "key": "key_example", "value": "value_example" } ] }, "createdVariable": false, "createdVariant": false}
SetVariableVariantVariableService.SetVariableVariant
Parameters
variableNamestringrequired
variantNamestring
Defaults to "default" when empty.
attributesAttribute[]
+Show child parameters
keystringrequired
Attribute dimension. Can be "repository", "environment", "branch", or "workflow".
valuestringrequired
Exact value or pattern, depending on key.
Returns
variableVariable
+Show child parameters
variantsVariableVariant[]
+Show child parameters
lastModifiedoneOf<google.protobuf.Timestamp | null>
lastModifiedoneOf<google.protobuf.Timestamp | null>
resolutionVariantResolution
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIEDVARIANT_RESOLUTION_RESOLVEDVARIANT_RESOLUTION_INDETERMINATEVARIANT_RESOLUTION_LOWER_PRIORITY
variantVariableVariant
+Show child parameters
attributesAttribute[]
+Show child parameters
keystringrequired
Attribute dimension. Can be "repository", "environment", "branch", or "workflow".
valuestringrequired
Exact value or pattern, depending on key.
lastModifiedoneOf<google.protobuf.Timestamp | null>
POST/depot.ci.v3beta2.VariableService/SetVariableVariant
1curl -X POST https://api.depot.dev/depot.ci.v3beta2.VariableService/SetVariableVariant \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "variableName": "variableName_example",8 "variantName": "variantName_example",9 "value": "value_example",10 "description": "description_example",11 "attributes": [12 {13 "key": "key_example",14 "value": "value_example"15 }16 ]17}18JSON
{ "variable": { "id": "id_123", "name": "name_example", "variants": [ { "id": "id_123", "variableId": "variable_123", "name": "name_example", "value": "value_example", "description": "description_example", "attributes": [ "attributes_example" ] } ], "variantCount": 1, "lastModified": "2026-05-18T18:00:00Z", "resolution": "VARIANT_RESOLUTION_UNSPECIFIED" }, "variant": { "id": "id_123", "variableId": "variable_123", "name": "name_example", "value": "value_example", "description": "description_example", "attributes": [ { "key": "key_example", "value": "value_example" } ] }, "createdVariable": false, "createdVariant": false}
UpdateVariableVariantMetadataVariableService.UpdateVariableVariantMetadata
Parameters
attributesAttribute[]
+Show child parameters
keystringrequired
Attribute dimension. Can be "repository", "environment", "branch", or "workflow".
valuestringrequired
Exact value or pattern, depending on key.
Returns
variantVariableVariant
+Show child parameters
attributesAttribute[]
+Show child parameters
keystringrequired
Attribute dimension. Can be "repository", "environment", "branch", or "workflow".
valuestringrequired
Exact value or pattern, depending on key.
lastModifiedoneOf<google.protobuf.Timestamp | null>
POST/depot.ci.v3beta2.VariableService/UpdateVariableVariantMetadata
1curl -X POST https://api.depot.dev/depot.ci.v3beta2.VariableService/UpdateVariableVariantMetadata \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "variantId": "variant_123",8 "name": "name_example",9 "description": "description_example",10 "attributes": [11 {12 "key": "key_example",13 "value": "value_example"14 }15 ]16}17JSON
{ "variant": { "id": "id_123", "variableId": "variable_123", "name": "name_example", "value": "value_example", "description": "description_example", "attributes": [ { "key": "key_example", "value": "value_example" } ] }}
UpdateVariableVariantValueVariableService.UpdateVariableVariantValue
Returns
variantVariableVariant
+Show child parameters
attributesAttribute[]
+Show child parameters
keystringrequired
Attribute dimension. Can be "repository", "environment", "branch", or "workflow".
valuestringrequired
Exact value or pattern, depending on key.
lastModifiedoneOf<google.protobuf.Timestamp | null>
POST/depot.ci.v3beta2.VariableService/UpdateVariableVariantValue
1curl -X POST https://api.depot.dev/depot.ci.v3beta2.VariableService/UpdateVariableVariantValue \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "variantId": "variant_123",8 "value": "value_example"9}10JSON
{ "variant": { "id": "id_123", "variableId": "variable_123", "name": "name_example", "value": "value_example", "description": "description_example", "attributes": [ { "key": "key_example", "value": "value_example" } ] }}
DeleteVariableVariantVariableService.DeleteVariableVariant
POST/depot.ci.v3beta2.VariableService/DeleteVariableVariant
1curl -X POST https://api.depot.dev/depot.ci.v3beta2.VariableService/DeleteVariableVariant \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "variantId": "variant_123"8}9JSON
{ "deletedVariable": false}
DeleteVariableVariableService.DeleteVariable
Returns
This method does not document a success response.
POST/depot.ci.v3beta2.VariableService/DeleteVariable
1curl -X POST https://api.depot.dev/depot.ci.v3beta2.VariableService/DeleteVariable \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "id": "id_123"8}9JSON
Diagnostics
Fetch deterministic failure diagnosis for CI resources.
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", "issue_comment", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".
runStatusFailureDiagnosisResourceStatus
Current state of the parent run.
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
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
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
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
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
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
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
attemptConclusionFailureDiagnosisConclusion
Conclusion of the parent attempt. Unspecified until the attempt concludes.
Possible enum values
FAILURE_DIAGNOSIS_CONCLUSION_UNSPECIFIEDFAILURE_DIAGNOSIS_CONCLUSION_SUCCESSFAILURE_DIAGNOSIS_CONCLUSION_FAILUREFAILURE_DIAGNOSIS_CONCLUSION_CANCELLEDFAILURE_DIAGNOSIS_CONCLUSION_SKIPPEDFAILURE_DIAGNOSIS_CONCLUSION_TIMED_OUT
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
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
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 this attempt.
attemptinteger<int32>
Attempt number, starting at 1 for the first run.
attemptStatusFailureDiagnosisResourceStatus
Current state of the attempt.
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
attemptConclusionFailureDiagnosisConclusion
Conclusion of the attempt. Unspecified until the attempt concludes.
Possible enum values
FAILURE_DIAGNOSIS_CONCLUSION_UNSPECIFIEDFAILURE_DIAGNOSIS_CONCLUSION_SUCCESSFAILURE_DIAGNOSIS_CONCLUSION_FAILUREFAILURE_DIAGNOSIS_CONCLUSION_CANCELLEDFAILURE_DIAGNOSIS_CONCLUSION_SKIPPEDFAILURE_DIAGNOSIS_CONCLUSION_TIMED_OUT
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
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
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 this attempt.
attemptinteger<int32>
Attempt number, starting at 1 for the first run.
attemptStatusFailureDiagnosisResourceStatus
Current state of the attempt.
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
attemptConclusionFailureDiagnosisConclusion
Conclusion of the attempt. Unspecified until the attempt concludes.
Possible enum values
FAILURE_DIAGNOSIS_CONCLUSION_UNSPECIFIEDFAILURE_DIAGNOSIS_CONCLUSION_SUCCESSFAILURE_DIAGNOSIS_CONCLUSION_FAILUREFAILURE_DIAGNOSIS_CONCLUSION_CANCELLEDFAILURE_DIAGNOSIS_CONCLUSION_SKIPPEDFAILURE_DIAGNOSIS_CONCLUSION_TIMED_OUT
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
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
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
{ "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.