Depot CI API reference | API | Depot Docs
Cookies
We use cookies to understand how people use Depot. Learn more
RejectAccept
Depot API
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.dev
Protocol
Connect RPC over HTTP
Auth
Encoding
JSON or Connect JSON
Errors
OpenAPI spec
API version
v1
OAS
3.1.0
Method index
The Depot CI API provides the following methods, grouped by resource.
RunTriggers a CI run. Runs can contain one or more workflows. ListRunsReturns CI runs for the authenticated organization, newest first. Filter by status, repository, commit SHA, trigger, or pull request number. Use `pageSize` and `pageToken` to page through additional results. GetRunReturns a CI run's identity, repo, trigger, status, and timestamps. For nested workflow, job, and attempt status, use `GetRunStatus`. GetRunStatusReturns a CI run's status with its nested workflows, jobs, and attempts. For the run's identity, repo, trigger, and timestamps, use `GetRun`. GetRunMetricsReturns workflow, job, and attempt CPU and memory metric summaries for one run. CancelRunCancels a queued or running CI run and any of its unfinished workflows, jobs, and attempts.
ListWorkflowsReturns CI workflows for the authenticated organization, newest first. Filter by name, repository, status, trigger, commit SHA, or pull request number. Use `pageSize` to return up to 200 workflows. GetWorkflowReturns a workflow's identity, status, timestamps, parent run context, execution history, and nested jobs and attempts. DispatchWorkflowTriggers a single workflow configured with an `on.workflow_dispatch` trigger and validates inputs against its input schema. RerunWorkflowResets every job in a workflow that's in a terminal state (finished, failed, or cancelled) to queued and runs them all again. Cancel the workflow first if it's still running. CancelWorkflowCancels a queued or running workflow and all its child jobs.
GetJobReturns a job's identity, status, timestamps, runner configuration, parent run and workflow context, dependencies, and attempt history. SubmitJobInputSubmit an answer to a running input job. 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 the failed and cancelled jobs in a workflow, along with every job that depends on them. A dependent that already succeeded or was skipped runs again too, because a job it consumed is running again. Queued dependents are left untouched, since they re-check their dependencies before starting. Fails without resetting anything when a waiting or running job depends on the retried set; wait for that job to finish, or cancel the workflow and use `RerunWorkflow`. CancelJobCancels a queued, waiting, or running job and its active attempt.
GetAttemptReturns an attempt's identity, status, timestamps, and sandbox/session IDs, with parent run, workflow, and job context. GetJobAttemptMetricsReturns CPU and memory metrics for one job attempt.
GetJobAttemptLogsReturns persisted log lines for a job attempt, oldest first. Identify the attempt by `attemptId`, or by `jobId` to use the job's latest attempt. Poll with `pageToken` to fetch lines persisted after a previous response. StreamJobAttemptLogsFollows a job attempt's persisted log lines, streaming new lines while the attempt runs.stream ExportJobAttemptLogsExports a finite snapshot of persisted log lines.stream
ListArtifactsReturns CI artifact metadata for one run, optionally narrowed to a workflow, job, or attempt. Download URLs are not included; request one per artifact with `GetArtifactDownloadURL`. GetArtifactDownloadURLReturns a short-lived signed HTTPS URL for one artifact. The URL expires 5 minutes after issuance.
ListSecrets ListSecretAttributes GetSecret GetSecretVariant CreateSecretVariant SetSecretVariant UpdateSecretVariantMetadata UpdateSecretVariantValue DeleteSecretVariant DeleteSecret
ListVariables ListVariableAttributes GetVariable GetVariableVariant CreateVariableVariant SetVariableVariant UpdateVariableVariantMetadata UpdateVariableVariantValue DeleteVariableVariant DeleteVariable
GetFailureDiagnosisReturns a failure diagnosis for a run, workflow, job, or attempt.
Runs
Create, inspect, measure, and cancel CI runs.
RunPOST/depot.ci.v1.CIService/Run ListRunsPOST/depot.ci.v1.CIService/ListRuns GetRunPOST/depot.ci.v1.CIService/GetRun GetRunStatusPOST/depot.ci.v1.CIService/GetRunStatus GetRunMetricsPOST/depot.ci.v1.CIService/GetRunMetrics CancelRunPOST/depot.ci.v1.CIService/CancelRun
RunCIService.Run
Triggers a CI run. Runs can contain one or more workflows.
Parameters
repostringrequired
Repository to run workflows from. GitHub, Origin, and Entire repositories use owner/name format. For example, "depot/cli". For Entire, use the owner/name in the repository's clone URL. Depot Code repositories use the repository name. For example, "widgets".
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. Depot Code is supported only for repositories that do not mirror a GitHub repository. Entire requires the Depot plugin installed on the repository's project. Default: FORGE_GITHUB.
Possible enum values
FORGE_UNSPECIFIED``FORGE_GITHUB``FORGE_ORIGIN``FORGE_DEPOT_CODE``FORGE_ENTIRE
refstring | null
Branch or tag the sha was checked out from, used to attribute test results. For example, "refs/heads/feature".
An unqualified name like "feature" is treated as a branch. To use a tag, pass the fully-qualified ref "refs/tags/v1.0".
It does not change what is checked out. Only valid when sha is set.
Returns
orgIdstring
Depot organization that owns this run.
runIdstring
Unique identifier for the created CI run. Use it for methods like GetRun, GetRunStatus, CancelRun, and ListArtifacts to track, cancel, or fetch results from the run.
POST/depot.ci.v1.CIService/Run
cURLNode.jsGo
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 "ref": "ref_example"16}17JSON
Response
{ "orgId": "org_123", "runId": "run_123"}
ListRunsCIService.ListRuns
Returns CI runs for the authenticated organization, newest first. Filter by status, repository, commit SHA, trigger, or pull request number. Use pageSize and pageToken to page through additional results.
Parameters
statusstring[]
Statuses of runs to return. Can be "queued", "running", "finished", "failed", or "cancelled". Multiple values are ORed. Default: ["running", "queued"].
pageSizeinteger
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
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/ListRuns \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "status": [8 "status_example"9 ],10 "pageSize": 1,11 "pageToken": "pageToken_example",12 "repo": "repo_example",13 "sha": "b2f5ff47436671b6e533d8dc3614845d",14 "trigger": "trigger_example",15 "pr": "pr_example"16}17JSON
Response
{ "runs": [ { "runId": "run_123", "repo": "repo_example", "trigger": "trigger_example", "sha": "b2f5ff47436671b6e533d8dc3614845d", "status": "status_example", "createdAt": "createdAt_example" } ], "nextPageToken": "nextPageToken_example"}
GetRunCIService.GetRun
Returns a CI run's identity, repo, trigger, status, and timestamps. For nested workflow, job, and attempt status, use GetRunStatus.
Parameters
runIdstringrequired
Unique identifier for the CI run. Returned by Run, DispatchWorkflow, and ListRuns.
Returns
orgIdstring
Depot organization that owns this run.
runIdstring
Unique identifier for the CI run.
repostring
GitHub repository in owner/name format. For example, "depot/cli".
refstring
Git ref the run was triggered against. For example, "refs/heads/main" or "refs/pull/42/merge". Empty when the trigger carries no ref.
shastring
Commit SHA the run executes against. Empty for open pull_request runs; populated with the merge commit SHA once the PR is closed and merged.
headShastring
Source commit SHA for pull_request and merge_group triggers; matches the PR or merge group head. Empty for triggers that don't carry a head SHA.
triggerstring
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
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetRun \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "runId": "run_123"8}9JSON
Response
{ "orgId": "org_123", "runId": "run_123", "repo": "repo_example", "ref": "ref_example", "sha": "b2f5ff47436671b6e533d8dc3614845d", "headSha": "b2f5ff47436671b6e533d8dc3614845d", "trigger": "trigger_example", "status": "status_example"}
GetRunStatusCIService.GetRunStatus
Returns a CI run's status with its nested workflows, jobs, and attempts. For the run's identity, repo, trigger, and timestamps, use GetRun.
Parameters
runIdstringrequired
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.
jobDisplayNamestring
Resolved job name for display. Falls back to the leaf job name, then jobKey, when unavailable. Use jobId or jobKey to identify the job.
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
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetRunStatus \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "runId": "run_123"8}9JSON
Response
{ "orgId": "org_123", "runId": "run_123", "status": "status_example", "workflows": [ { "workflowId": "workflow_123", "status": "status_example", "workflowPath": "workflowPath_example", "jobs": [ { "jobId": "job_123", "jobKey": "jobKey_example", "status": "status_example", "attempts": [ "attempts_example" ], "jobDisplayName": "jobDisplayName_example" } ], "name": "name_example", "errorMessage": "errorMessage_example" } ]}
GetRunMetricsCIService.GetRunMetrics
Returns workflow, job, and attempt CPU and memory metric summaries for one run.
Parameters
runIdstringrequired
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
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
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetRunMetrics \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "runId": "run_123"8}9JSON
Response
{ "run": { "runId": "run_123", "repo": "repo_example", "ref": "ref_example", "sha": "b2f5ff47436671b6e533d8dc3614845d", "headSha": "b2f5ff47436671b6e533d8dc3614845d", "trigger": "trigger_example" }, "workflows": [ { "workflow": { "workflowId": "workflow_123", "workflowPath": "workflowPath_example", "name": "name_example", "status": "status_example", "createdAt": "createdAt_example", "startedAt": "startedAt_example" }, "jobs": [ { "job": "job_example", "attempts": [ "attempts_example" ] } ] } ], "snapshotAt": "snapshotAt_example"}
CancelRunCIService.CancelRun
Cancels a queued or running CI run and any of its unfinished workflows, jobs, and attempts.
Parameters
runIdstringrequired
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
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/CancelRun \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "runId": "run_123"8}9JSON
Response
{ "runId": "run_123", "status": "status_example"}
Workflows
List, inspect, dispatch, rerun, and cancel CI workflows.
ListWorkflowsPOST/depot.ci.v1.CIService/ListWorkflows GetWorkflowPOST/depot.ci.v1.CIService/GetWorkflow DispatchWorkflowPOST/depot.ci.v1.CIService/DispatchWorkflow RerunWorkflowPOST/depot.ci.v1.CIService/RerunWorkflow CancelWorkflowPOST/depot.ci.v1.CIService/CancelWorkflow
ListWorkflowsCIService.ListWorkflows
Returns CI workflows for the authenticated organization, newest first. Filter by name, repository, status, trigger, commit SHA, or pull request number. Use pageSize to return up to 200 workflows.
Parameters
pageSizeinteger
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
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
Total number of jobs in the workflow.
queuedinteger
Number of jobs currently queued.
waitinginteger
Number of jobs waiting on dependencies.
runninginteger
Number of jobs currently running.
finishedinteger
Number of jobs that finished successfully.
failedinteger
Number of jobs that failed.
cancelledinteger
Number of jobs that were cancelled.
skippedinteger
Number of jobs that were skipped.
POST/depot.ci.v1.CIService/ListWorkflows
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/ListWorkflows \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "pageSize": 1,8 "name": "name_example",9 "repo": "repo_example",10 "status": [11 "status_example"12 ],13 "trigger": "trigger_example",14 "sha": "b2f5ff47436671b6e533d8dc3614845d",15 "pr": "pr_example"16}17JSON
Response
{ "workflows": [ { "workflowId": "workflow_123", "name": "name_example", "workflowPath": "workflowPath_example", "repo": "repo_example", "status": "status_example", "trigger": "trigger_example" } ]}
GetWorkflowCIService.GetWorkflow
Returns a workflow's identity, status, timestamps, parent run context, execution history, and nested jobs and attempts.
Parameters
workflowIdstringrequired
Unique identifier for the workflow. Returned by GetRunStatus and ListWorkflows.
Returns
orgIdstring
Depot organization that owns this workflow.
runIdstring
Unique identifier for the parent CI run.
repostring
GitHub repository in owner/name format. For example, "depot/cli".
refstring
Git ref the parent run was triggered against. Empty when the trigger carries no ref.
shastring
Commit SHA the parent run executes against. For pull_request triggers, the merge commit SHA.
headShastring
Source commit SHA for pull_request and merge_group triggers. Empty for triggers that don't carry a head SHA.
triggerstring
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
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
Execution number, starting at 1 for the first execution.
statusstring
Current state of the execution. Can be "queued", "running", "finished", "failed", or "cancelled".
createdAtstring
Execution creation time, in RFC 3339 format.
startedAtstring
Execution start time, in RFC 3339 format. Empty until the execution starts.
finishedAtstring
Execution finish time, in RFC 3339 format. Empty until the execution finishes.
jobsGetWorkflowJob[]
Workflow jobs and their per-job attempts.
+Show child parameters
jobIdstring
Unique identifier for the job.
jobKeystring
Job key from the workflow. For example, "build" or "test".
statusstring
startedAtstring
Job start time, in RFC 3339 format. Empty until the job starts.
finishedAtstring
Job finish time, in RFC 3339 format. Empty until the job finishes.
attemptsGetWorkflowJobAttempt[]
Per-job attempts, not workflow execution records.
+Show child parameters
attemptIdstring
Unique identifier for the job attempt.
attemptinteger
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.
jobDisplayNamestring
Resolved job name for display. Falls back to the leaf job name, then jobKey, when unavailable. Use jobId or jobKey to identify the job.
waitingReasonstring
Reason a queued job is waiting. "timer" means it will become eligible at waitUntil. Empty otherwise.
waitUntilstring
Time the job's configured delay ends, in RFC 3339 format. Empty when the job is not waiting on a timer.
POST/depot.ci.v1.CIService/GetWorkflow
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetWorkflow \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "workflowId": "workflow_123"8}9JSON
Response
{ "orgId": "org_123", "runId": "run_123", "repo": "repo_example", "ref": "ref_example", "sha": "b2f5ff47436671b6e533d8dc3614845d", "headSha": "b2f5ff47436671b6e533d8dc3614845d", "trigger": "trigger_example", "runStatus": "runStatus_example"}
DispatchWorkflowCIService.DispatchWorkflow
Triggers a single workflow configured with an on.workflow_dispatch trigger and validates inputs against its input schema.
Parameters
repostringrequired
GitHub repository to run workflows from, in owner/name format. For example, "depot/cli". Must be connected to your Depot organization through the Depot GitHub app.
workflowstringrequired
Path of the workflow file to run, relative to the repo root. For example, ".depot/workflows/deploy.yml". The workflow must be configured with an on.workflow_dispatch trigger. Required.
refstring
Branch or tag to run the workflow on. An unqualified name like "main" is treated as a branch. To use a tag, pass the fully-qualified ref "refs/tags/v1.0". Leave empty to use the repository's default branch. Default: HEAD of the default branch.
inputsobject<string, string>
Inputs to pass to the workflow, as key-value pairs. All values are strings. The server validates each value against the workflow's workflow_dispatch input schema. Boolean inputs must be the string "true" or "false", number inputs must be numeric, and choice inputs must match one of the defined options. Unknown inputs are rejected. A required input must be supplied only if it has no default; one that has a default may be omitted.
Returns
orgIdstring
Depot organization that owns this run.
runIdstring
POST/depot.ci.v1.CIService/DispatchWorkflow
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/DispatchWorkflow \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "repo": "repo_example",8 "workflow": "workflow_example",9 "ref": "ref_example",10 "inputs": "inputs_example"11}12JSON
Response
{ "orgId": "org_123", "runId": "run_123"}
RerunWorkflowCIService.RerunWorkflow
Resets every job in a workflow that's in a terminal state (finished, failed, or cancelled) to queued and runs them all again. Cancel the workflow first if it's still running.
Parameters
workflowIdstringrequired
Unique identifier for the workflow to re-run. Returned by GetRunStatus and ListWorkflows.
Returns
workflowIdstring
Unique identifier for the workflow. Matches the request workflowId. A re-run creates a new workflow execution rather than a new workflow.
jobCountinteger
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
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/RerunWorkflow \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "workflowId": "workflow_123"8}9JSON
Response
{ "workflowId": "workflow_123", "jobCount": 1}
CancelWorkflowCIService.CancelWorkflow
Cancels a queued or running workflow and all its child jobs.
Parameters
workflowIdstringrequired
Unique identifier for the workflow to cancel. Returned by GetRunStatus and ListWorkflows.
Returns
workflowIdstring
Unique identifier for the workflow. Matches the request workflowId.
statusstring
Updated workflow status. Should be "cancelled".
POST/depot.ci.v1.CIService/CancelWorkflow
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/CancelWorkflow \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "workflowId": "workflow_123"8}9JSON
Response
{ "workflowId": "workflow_123", "status": "status_example"}
Jobs
Inspect, summarize, measure, retry, and cancel CI jobs.
GetJobPOST/depot.ci.v1.CIService/GetJob SubmitJobInputPOST/depot.ci.v1.CIService/SubmitJobInput GetJobSummaryPOST/depot.ci.v1.CIService/GetJobSummary GetJobMetricsPOST/depot.ci.v1.CIService/GetJobMetrics RetryJobPOST/depot.ci.v1.CIService/RetryJob RetryFailedJobsPOST/depot.ci.v1.CIService/RetryFailedJobs CancelJobPOST/depot.ci.v1.CIService/CancelJob
GetJobCIService.GetJob
Returns a job's identity, status, timestamps, runner configuration, parent run and workflow context, dependencies, and attempt history.
Parameters
jobIdstringrequired
Unique identifier for the job. Returned by GetRunStatus and GetWorkflow.
Returns
orgIdstring
Depot organization that owns this job.
runIdstring
Unique identifier for the parent CI run.
repostring
GitHub repository in owner/name format. For example, "depot/cli".
refstring
Git ref the parent run was triggered against. Empty when the trigger carries no ref.
shastring
Commit SHA the parent run executes against. For pull_request triggers, the merge commit SHA.
headShastring
Source commit SHA for pull_request and merge_group triggers. Empty for triggers that don't carry a head SHA.
triggerstring
runStatusstring
Current state of the parent run. Can be "queued", "running", "finished", "failed", or "cancelled".
runCreatedAtstring
Parent run creation time, in RFC 3339 format.
runStartedAtstring
Parent run start time, in RFC 3339 format. Empty until the run starts.
runFinishedAtstring
Parent run finish time, in RFC 3339 format. Empty until the run finishes.
workflowIdstring
Unique identifier for the parent workflow.
workflowNamestring
Parent workflow name from the YAML name: key. Falls back to the file path stem when the workflow doesn't set name:. Empty when neither is available.
workflowPathstring
Parent workflow file path. For example, ".depot/workflows/ci.yml". Empty when the workflow YAML was passed via workflowContent in the Run request.
workflowStatusstring
Current state of the parent workflow. Can be "queued", "running", "finished", "failed", or "cancelled".
workflowErrorMessagestring
Parent workflow error or cancellation reason. For example, a compilation or validation error. Empty when the workflow is healthy.
workflowCreatedAtstring
Parent workflow creation time, in RFC 3339 format.
workflowStartedAtstring
Parent workflow start time, in RFC 3339 format. Empty until the workflow starts.
workflowFinishedAtstring
Parent workflow finish time, in RFC 3339 format. Empty until the workflow finishes.
jobIdstring
Unique identifier for the job.
jobKeystring
Job key from the workflow. For example, "build" or "test".
jobDisplayNamestring
Human-readable display name from the workflow. Falls back to jobKey when no display name is set.
jobStatusstring
jobConclusionstring
Conclusion of the job. Can be "success", "failure", "cancelled", "skipped", or "timed_out". Empty until the job concludes.
jobErrorMessagestring
Job error message populated for orchestration or worker failures. Empty when the job has no error.
jobCreatedAtstring
Job creation time, in RFC 3339 format.
jobDispatchedAtstring
Job dispatch time, in RFC 3339 format. Empty until the job is dispatched to a worker.
jobStartedAtstring
Job start time, in RFC 3339 format. Empty until the job starts.
jobFinishedAtstring
Job finish time, in RFC 3339 format. Empty until the job finishes.
currentAttemptIdstring
Unique identifier for the most recent attempt for this job. Empty until the first attempt is dispatched, and cleared while a retried job waits for its next attempt to be dispatched.
currentAttemptinteger
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
Zero-based index of this job within the matrix expansion.
jobTotalinteger
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
CPU count allocated to the runner. Zero when unset.
memoryGbinteger
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
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.
waitingReasonstring
Reason a queued job is waiting. "timer" means it will become eligible at waitUntil. Empty otherwise.
waitUntilstring
Time the job's configured delay ends, in RFC 3339 format. Empty when the job is not waiting on a timer.
inputRequestJobInputRequest
Resolved input controls and accepted response. Unset for jobs without a dispatched input request.
+Show child parameters
textstring
Resolved question presented to the responder.
fieldsJobInputField[]
Controls in presentation order.
+Show child parameters
idstring
Identifier used as the key in the submitted answer.
typestring
Control type. Can be "select" or "buttons".
labelstring
Display label. Empty when the control has no label.
optionsJobInputOption[]
Available choices in presentation order.
answerJobInputAnswer
Accepted response. Unset until someone answers.
+Show child parameters
fieldsobject<string, string>
Submitted values keyed by control identifier.
userIdstring
Identifier of the authenticated responder in the source channel.
answeredAtstring
Acceptance time, in RFC 3339 format. Empty for older responses.
channelstring
Channel through which the answer was submitted. Can be "web" or "slack".
deadlinestring
Response deadline, in RFC 3339 format.
attemptIdstring
Unique identifier for the attempt that requested input.
POST/depot.ci.v1.CIService/GetJob
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetJob \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "jobId": "job_123"8}9JSON
Response
SubmitJobInputCIService.SubmitJobInput
Submit an answer to a running input job.
Parameters
jobIdstring
Unique identifier for the job. Returned by GetJob.
attemptIdstring
Unique identifier for the current attempt. Returned by GetJob.
fieldsobject<string, string>
Selected values keyed by the declared control identifiers, including the clicked button.
Returns
This method does not document a success response.
POST/depot.ci.v1.CIService/SubmitJobInput
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/SubmitJobInput \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 "fields": "fields_example"10}11JSON
Response
{}
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
Attempt number, starting at 1. Zero when no attempt exists yet.
jobStatusstring
attemptStatusstring
Current state of the attempt. Can be "queued", "waiting", "running", "finished", "failed", or "cancelled". Empty when no attempt exists yet.
hasSummaryboolean
True when authored step summary markdown is available for the selected attempt.
emptyReasonstring
Set when hasSummary is false, for example "no_summary" or "no_attempt".
stepCountinteger
Count of non-empty step summaries included in markdown.
markdownstring
Authored step summary markdown joined in step order.
POST/depot.ci.v1.CIService/GetJobSummary
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetJobSummary \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "jobId": "job_123",8 "attemptId": "attempt_123"9}10JSON
Response
{ "orgId": "org_123", "runId": "run_123", "workflowId": "workflow_123", "jobId": "job_123", "attemptId": "attempt_123", "attempt": 1, "jobStatus": "jobStatus_example", "attemptStatus": "attemptStatus_example"}
GetJobMetricsCIService.GetJobMetrics
Returns per-attempt CPU and memory metric summaries for one job.
Parameters
jobIdstringrequired
Unique identifier for the job.
Returns
runCIMetricsRunContext
Parent run context: identifiers, trigger, status, and lifecycle timestamps.
+Show child parameters
runIdstring
Unique identifier for the CI run.
repostring
GitHub repository in owner/name format. For example, "depot/cli".
refstring
Git ref the run was triggered against. Empty when the trigger carries no ref.
shastring
Commit SHA the run executes against. Empty for open pull_request runs.
headShastring
Source commit SHA for pull_request and merge_group triggers. Empty for triggers that don't carry a head SHA.
triggerstring
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
namestring
Workflow name from the YAML name: key. Falls back to the file path stem when the workflow doesn't set name:. Empty when neither is available.
statusstring
Current state of the workflow, for example "queued", "running", "finished", "failed", or "cancelled".
createdAtstring
Workflow creation time, in RFC 3339 format.
startedAtstring
Workflow start time, in RFC 3339 format. Empty until the workflow starts.
finishedAtstring
Workflow finish time, in RFC 3339 format. Empty until the workflow finishes.
jobCIMetricsJobContext
Job context: identifiers, status, conclusion, and lifecycle timestamps.
+Show child parameters
jobIdstring
Unique identifier for the job.
jobKeystring
Job key from the workflow. For example, "build" or "test".
statusstring
conclusionstring
Conclusion of the job. Can be "success", "failure", "cancelled", "skipped", or "timed_out". Empty until the job concludes.
currentAttemptinteger
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
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_UNSPECIFIED``CI_METRICS_AVAILABILITY_CODE_AVAILABLE``CI_METRICS_AVAILABILITY_CODE_NO_SANDBOX``CI_METRICS_AVAILABILITY_CODE_NO_TIME_RANGE``CI_METRICS_AVAILABILITY_CODE_NO_SAMPLES
reasonstring
Short reason string matching the code, for example "available", "no_sandbox", "no_time_range", or "no_samples".
statsCIMetricsStats
Aggregate CPU and memory statistics computed across the raw samples.
+Show child parameters
sampleCountinteger
Total number of merged samples observed for the attempt.
cpuSampleCountinteger
Number of samples that included a CPU utilization value.
memorySampleCountinteger
Number of samples that included a memory utilization value.
peakCpuUtilizationnumber | null
Peak observed CPU utilization as a fraction from 0 to 1. Unset when no CPU samples were observed.
averageCpuUtilizationnumber | null
Average observed CPU utilization as a fraction from 0 to 1. Unset when no CPU samples were observed.
peakMemoryUtilizationnumber | null
Peak observed memory utilization as a fraction from 0 to 1. Unset when no memory samples were observed.
averageMemoryUtilizationnumber | null
Average observed memory utilization as a fraction from 0 to 1. Unset when no memory samples were observed.
observedStartedAtstring
Timestamp of the first observed sample, in RFC 3339 format. Empty when no samples were observed.
observedFinishedAtstring
Timestamp of the last observed sample, in RFC 3339 format. Empty when no samples were observed.
peakMemoryUsageBytesinteger | string | null
Peak observed memory usage in bytes. Unset when no memory samples were observed.
averageMemoryUsageBytesnumber | null
Average observed memory usage in bytes. Unset when no memory samples were observed.
capCIMetricsCapMetadata
Downsampling metadata describing how raw samples were reduced for transport.
+Show child parameters
rawSampleCountinteger
Raw sample count observed before downsampling.
returnedSampleCountinteger
Number of samples returned in the response.
maxReturnedSampleCountinteger
Hard cap on the number of samples a single response will return.
downsampledboolean
True when the raw samples were downsampled to fit maxReturnedSampleCount.
downsampleStrategystring
Identifier for the downsampling strategy used, for example "peak_preserving_even". Empty when no downsampling was applied.
snapshotAtstring
POST/depot.ci.v1.CIService/GetJobMetrics
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetJobMetrics \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "jobId": "job_123"8}9JSON
Response
{ "run": { "runId": "run_123", "repo": "repo_example", "ref": "ref_example", "sha": "b2f5ff47436671b6e533d8dc3614845d", "headSha": "b2f5ff47436671b6e533d8dc3614845d", "trigger": "trigger_example" }, "workflow": { "workflowId": "workflow_123", "workflowPath": "workflowPath_example", "name": "name_example", "status": "status_example", "createdAt": "createdAt_example", "startedAt": "startedAt_example" }, "job": { "jobId": "job_123", "jobKey": "jobKey_example", "status": "status_example", "conclusion": "conclusion_example", "currentAttempt": 1, "createdAt": "createdAt_example" }, "attempts": [ { "attempt": { "attemptId": "attempt_123", "attempt": 1, "status": "status_example", "conclusion": "conclusion_example", "sandboxId": "sandbox_123", "sessionId": "session_123" }, "availability": { "code": "CI_METRICS_AVAILABILITY_CODE_UNSPECIFIED", "reason": "reason_example" }, "stats": { "sampleCount": 1, "cpuSampleCount": 1, "memorySampleCount": 1, "peakCpuUtilization": 1, "averageCpuUtilization": 1, "peakMemoryUtilization": 1 }, "cap": { "rawSampleCount": 1, "returnedSampleCount": 1, "maxReturnedSampleCount": 1, "downsampled": false, "downsampleStrategy": "downsampleStrategy_example" } } ], "snapshotAt": "snapshotAt_example"}
RetryJobCIService.RetryJob
Retries a failed or cancelled job, along with any skipped jobs that depend on it. Fails when a job that depends on it has already started; use RetryFailedJobs to retry related failures together.
Parameters
workflowIdstringrequired
Unique identifier for the workflow containing the job. Returned by GetRunStatus and ListWorkflows.
jobIdstringrequired
Unique identifier for the job to retry. Returned by GetRunStatus and GetWorkflow.
Returns
jobIdstring
Unique identifier for the job. Matches the request jobId. A retry creates a new attempt rather than a new job.
attemptIdstring
Empty in the response. The new attempt is created once the job runs again and appears in the attempts array returned by GetJob.
attemptinteger
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
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/RetryJob \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "workflowId": "workflow_123",8 "jobId": "job_123"9}10JSON
Response
{ "jobId": "job_123", "attemptId": "attempt_123", "attempt": 1, "status": "status_example"}
RetryFailedJobsCIService.RetryFailedJobs
Retries the failed and cancelled jobs in a workflow, along with every job that depends on them. A dependent that already succeeded or was skipped runs again too, because a job it consumed is running again. Queued dependents are left untouched, since they re-check their dependencies before starting. Fails without resetting anything when a waiting or running job depends on the retried set; wait for that job to finish, or cancel the workflow and use RerunWorkflow.
Parameters
workflowIdstringrequired
Unique identifier for the workflow containing failed jobs. Returned by GetRunStatus and ListWorkflows.
Returns
workflowIdstring
Unique identifier for the workflow. Matches the request workflowId. A retry creates a new workflow execution rather than a new workflow.
jobIdsstring[]
Unique identifiers for jobs that were set back to queued. A new attempt is created for each job when it runs again.
jobCountinteger
Number of jobs reset to queued. Includes the failed and cancelled jobs, plus every job that depends on them, whether it previously succeeded or was skipped. Equal to the number of entries in the jobIds array.
POST/depot.ci.v1.CIService/RetryFailedJobs
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/RetryFailedJobs \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "workflowId": "workflow_123"8}9JSON
Response
{ "workflowId": "workflow_123", "jobIds": [ "job_123" ], "jobCount": 1}
CancelJobCIService.CancelJob
Cancels a queued, waiting, or running job and its active attempt.
Parameters
workflowIdstringrequired
jobIdstringrequired
Unique identifier for the job to cancel. Returned by GetRunStatus and GetWorkflow.
Returns
jobIdstring
Unique identifier for the job. Matches the request jobId.
statusstring
Updated job status. Should be "cancelled".
POST/depot.ci.v1.CIService/CancelJob
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/CancelJob \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "workflowId": "workflow_123",8 "jobId": "job_123"9}10JSON
Response
{ "jobId": "job_123", "status": "status_example"}
Attempts
Inspect job attempts and their execution metrics.
GetAttemptPOST/depot.ci.v1.CIService/GetAttempt GetJobAttemptMetricsPOST/depot.ci.v1.CIService/GetJobAttemptMetrics
GetAttemptCIService.GetAttempt
Returns an attempt's identity, status, timestamps, and sandbox/session IDs, with parent run, workflow, and job context.
Parameters
attemptIdstringrequired
Unique identifier for the job attempt. Returned by GetRunStatus, GetWorkflow, and GetJob.
Returns
orgIdstring
Depot organization that owns this attempt.
runIdstring
Unique identifier for the parent CI run.
repostring
GitHub repository in owner/name format. For example, "depot/cli".
refstring
Git ref the parent run was triggered against. Empty when the trigger carries no ref.
shastring
Commit SHA the parent run executes against. For pull_request triggers, the merge commit SHA.
headShastring
Source commit SHA for pull_request and merge_group triggers. Empty for triggers that don't carry a head SHA.
triggerstring
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
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
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
Zero-based index of this job within the matrix expansion.
jobTotalinteger
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
CPU count allocated to the runner. Zero when unset.
memoryGbinteger
Memory allocated to the runner, in gigabytes. Zero when unset.
sizestring
Runner size from the job's runs-on, exactly as written in the workflow.
attemptJobDetailAttempt
The requested attempt's identifiers, lifecycle timestamps, conclusion, and sandbox/session linkage.
+Show child parameters
attemptIdstring
Unique identifier for the job attempt.
attemptinteger
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
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetAttempt \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "attemptId": "attempt_123"8}9JSON
Response
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
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
namestring
Workflow name from the YAML name: key. Falls back to the file path stem when the workflow doesn't set name:. Empty when neither is available.
statusstring
Current state of the workflow, for example "queued", "running", "finished", "failed", or "cancelled".
createdAtstring
Workflow creation time, in RFC 3339 format.
startedAtstring
Workflow start time, in RFC 3339 format. Empty until the workflow starts.
finishedAtstring
Workflow finish time, in RFC 3339 format. Empty until the workflow finishes.
jobCIMetricsJobContext
Parent job context: identifiers, status, conclusion, and lifecycle timestamps.
+Show child parameters
jobIdstring
Unique identifier for the job.
jobKeystring
Job key from the workflow. For example, "build" or "test".
statusstring
conclusionstring
Conclusion of the job. Can be "success", "failure", "cancelled", "skipped", or "timed_out". Empty until the job concludes.
currentAttemptinteger
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
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.
Possible enum values
reasonstring
Short reason string matching the code, for example "available", "no_sandbox", "no_time_range", or "no_samples".
statsCIMetricsStats
Aggregate CPU and memory statistics computed across the raw samples.
+Show child parameters
sampleCountinteger
Total number of merged samples observed for the attempt.
cpuSampleCountinteger
Number of samples that included a CPU utilization value.
memorySampleCountinteger
Number of samples that included a memory utilization value.
peakCpuUtilizationnumber | null
Peak observed CPU utilization as a fraction from 0 to 1. Unset when no CPU samples were observed.
averageCpuUtilizationnumber | null
Average observed CPU utilization as a fraction from 0 to 1. Unset when no CPU samples were observed.
peakMemoryUtilizationnumber | null
Peak observed memory utilization as a fraction from 0 to 1. Unset when no memory samples were observed.
averageMemoryUtilizationnumber | null
Average observed memory utilization as a fraction from 0 to 1. Unset when no memory samples were observed.
observedStartedAtstring
Timestamp of the first observed sample, in RFC 3339 format. Empty when no samples were observed.
observedFinishedAtstring
Timestamp of the last observed sample, in RFC 3339 format. Empty when no samples were observed.
peakMemoryUsageBytesinteger | string | null
Peak observed memory usage in bytes. Unset when no memory samples were observed.
averageMemoryUsageBytesnumber | null
Average observed memory usage in bytes. Unset when no memory samples were observed.
capCIMetricsCapMetadata
Downsampling metadata describing how raw samples were reduced for transport.
+Show child parameters
rawSampleCountinteger
Raw sample count observed before downsampling.
returnedSampleCountinteger
Number of samples returned in the response.
maxReturnedSampleCountinteger
Hard cap on the number of samples a single response will return.
downsampledboolean
True when the raw samples were downsampled to fit maxReturnedSampleCount.
downsampleStrategystring
Identifier for the downsampling strategy used, for example "peak_preserving_even". Empty when no downsampling was applied.
samplesCIMetricSample[]
Time-ordered CPU and memory samples for the attempt, possibly downsampled.
+Show child parameters
timestampstring
Sample timestamp, in RFC 3339 format.
cpuUtilizationnumber | null
CPU utilization as a fraction from 0 to 1. Unset when no CPU sample was recorded at this timestamp.
memoryUtilizationnumber | null
Memory utilization as a fraction from 0 to 1. Unset when no memory sample was recorded at this timestamp.
memoryUsageBytesinteger | string | null
Memory usage in bytes. Unset when no memory sample was recorded at this timestamp.
snapshotAtstring
POST/depot.ci.v1.CIService/GetJobAttemptMetrics
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetJobAttemptMetrics \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "attemptId": "attempt_123"8}9JSON
Response
Logs
Read, stream, and export job attempt logs.
GetJobAttemptLogsPOST/depot.ci.v1.CIService/GetJobAttemptLogs StreamJobAttemptLogsPOST/depot.ci.v1.CIService/StreamJobAttemptLogs ExportJobAttemptLogsPOST/depot.ci.v1.CIService/ExportJobAttemptLogs
GetJobAttemptLogsCIService.GetJobAttemptLogs
Returns persisted log lines for a job attempt, oldest first. Identify the attempt by attemptId, or by jobId to use the job's latest attempt. Poll with pageToken to fetch lines persisted after a previous response.
Parameters
attemptIdstring
Unique identifier for the job attempt. Set exactly one of attemptId or jobId.
pageTokenstring
Token to fetch lines after a previous response. Use the nextPageToken value from a prior response. Leave empty to fetch from the first line.
jobIdstring | null
Unique identifier for a CI job. Resolves to the job's latest attempt; the page token pins that attempt, so later pages stay on the same attempt even if a retry creates a newer one. Set exactly one of attemptId or jobId.
Returns
linesLogLine[]
Persisted log lines for the attempt, ordered by timestamp and line number.
+Show child parameters
stepKeystring
Depot-assigned key correlating the line with a workflow step. Stable across responses for the same step.
timestampMsinteger | string
Log timestamp as Unix epoch milliseconds.
lineNumberinteger
Persisted line number within the emitting stream.
streaminteger
0 for stdout, 1 for stderr.
bodystring
Log line content, without a trailing newline.
stepIdstring
User-authored workflow step ID from the step's id: key. Empty when not set.
stepNamestring
User-authored workflow step name from the step's name: key. Empty when not set.
nextPageTokenstring
Token to fetch lines persisted after this response. Empty when the response contains no lines. While the attempt is running, poll with the newest token to tail new lines.
POST/depot.ci.v1.CIService/GetJobAttemptLogs
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetJobAttemptLogs \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "attemptId": "attempt_123",8 "pageToken": "pageToken_example",9 "jobId": "job_123"10}11JSON
Response
{ "lines": [ { "stepKey": "stepKey_example", "timestampMs": 1, "lineNumber": 1, "stream": 1, "body": "body_example", "stepId": "step_123" } ], "nextPageToken": "nextPageToken_example"}
StreamJobAttemptLogsCIService.StreamJobAttemptLogsstream
Follows a job attempt's persisted log lines, streaming new lines while the attempt runs.
The response is a Connect/gRPC server stream, not raw text. Consume it with a generated client or a decoder that understands stream framing. Every response reports the attempt's current status. Responses that carry a log line also include nextCursor.
To resume a dropped stream, save the newest nextCursor and send it as cursor on a new request. The new stream picks up after the last line you received. The stream ends on its own once the attempt has finished, failed, or been cancelled and all persisted lines have been sent.
Parameters
attemptIdstring
Unique identifier for the job attempt. Set exactly one of attemptId or jobId.
cursorstring
Opaque cursor returned by a previous stream response for the same target. Omit it to stream from the first persisted line.
jobIdstring
Unique identifier for a CI job. The stream resolves it to that job's latest attempt. Set exactly one of attemptId or jobId.
Returns
lineLogLine
Set when this response carries a persisted log line. Status-only responses can omit it while the stream is waiting for rows.
+Show child parameters
stepKeystring
Depot-assigned key correlating the line with a workflow step. Stable across responses for the same step.
timestampMsinteger | string
Log timestamp as Unix epoch milliseconds.
lineNumberinteger
Persisted line number within the emitting stream.
streaminteger
0 for stdout, 1 for stderr.
bodystring
Log line content, without a trailing newline.
stepIdstring
User-authored workflow step ID from the step's id: key. Empty when not set.
stepNamestring
User-authored workflow step name from the step's name: key. Empty when not set.
nextCursorstring
Opaque cursor to resume after the emitted line. Set on responses that carry a line. Persist the newest value and send it as cursor on a later request.
attemptStatusstring
Current state of the attempt. Can be "queued", "waiting", "running", "finished", "failed", or "cancelled".
Server-streaming RPC. The examples show decoded message payloads; the raw HTTP response is Connect-framed and should be read with a generated client or protocol-aware decoder.
POST/depot.ci.v1.CIService/StreamJobAttemptLogs
cURLNode.jsGo
1# Server-streaming RPC2# Use a generated Connect client or protocol-aware decoder.3# Raw curl cannot send or decode this framed stream as shown.4# Protocol spec: https://connectrpc.com/docs/protocol/#streaming-rpcs5# RPC: CIService.StreamJobAttemptLogs6# Path: /depot.ci.v1.CIService/StreamJobAttemptLogs
Stream messages
{ "line": { "stepKey": "stepKey_example", "timestampMs": 1, "lineNumber": 1, "stream": 1, "body": "body_example", "stepId": "step_123" }, "nextCursor": "nextCursor_example", "attemptStatus": "attemptStatus_example"}
ExportJobAttemptLogsCIService.ExportJobAttemptLogsstream
Exports a finite snapshot of persisted log lines.
The response is a Connect/gRPC server stream, not a raw HTTP file download. Consume it with a generated client or a decoder that understands stream framing. Read the first metadata response, then append each following chunk response to a file or writer in order. Use the Depot CLI depot ci logs --output-file when a shell-native file download is needed.
Parameters
attemptIdstring
Unique identifier for the job attempt. Set exactly one of attemptId or jobId.
jobIdstring
Unique identifier for a CI job. Export resolves it to that job's latest attempt at stream start. Set exactly one of attemptId or jobId.
formatJobAttemptLogExportFormat
Selects the export byte format. Default: text.
Possible enum values
JOB_ATTEMPT_LOG_EXPORT_FORMAT_UNSPECIFIED``JOB_ATTEMPT_LOG_EXPORT_FORMAT_TEXT``JOB_ATTEMPT_LOG_EXPORT_FORMAT_JSONL
Returns
chunkobject
chunkstring
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_UNSPECIFIED``JOB_ATTEMPT_LOG_EXPORT_FORMAT_TEXT``JOB_ATTEMPT_LOG_EXPORT_FORMAT_JSONL
POST/depot.ci.v1.CIService/ExportJobAttemptLogs
cURLNode.jsGo
1# Server-streaming RPC2# Use a generated Connect client or protocol-aware decoder.3# Raw curl cannot send or decode this framed stream as shown.4# Protocol spec: https://connectrpc.com/docs/protocol/#streaming-rpcs5# RPC: CIService.ExportJobAttemptLogs6# Path: /depot.ci.v1.CIService/ExportJobAttemptLogs
Stream messages
{ "metadata": { "filename": "filename_example", "contentType": "contentType_example", "format": "JOB_ATTEMPT_LOG_EXPORT_FORMAT_UNSPECIFIED" }} { "chunk": "chunk_example"}
Artifacts
List artifacts and create signed artifact download URLs.
ListArtifactsPOST/depot.ci.v1.CIService/ListArtifacts GetArtifactDownloadURLPOST/depot.ci.v1.CIService/GetArtifactDownloadURL
ListArtifactsCIService.ListArtifacts
Returns CI artifact metadata for one run, optionally narrowed to a workflow, job, or attempt. Download URLs are not included; request one per artifact with GetArtifactDownloadURL.
Parameters
runIdstringrequired
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
Number of artifacts to return per page. Maximum: 500. Default: 100.
pageTokenstring
Token to fetch the next page of artifacts. Use the nextPageToken value from a prior response with the same filters. Leave empty to fetch the first page.
Returns
artifactsArtifact[]
Artifacts matching the request, up to pageSize entries.
+Show child parameters
artifactIdstring
Unique identifier for the artifact. Pass it to GetArtifactDownloadURL to download the artifact.
runIdstring
Unique identifier for the parent CI run.
workflowIdstring
Unique identifier for the parent workflow.
workflowPathstring
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
Attempt number that produced the artifact, starting at 1.
namestring
Artifact name as authored by the workflow.
sizeBytesinteger | string
Artifact size in bytes.
createdAtstring
Artifact creation time, in RFC 3339 format.
nextPageTokenstring | null
Token to retrieve the next page of results. Unset when no more pages are available.
POST/depot.ci.v1.CIService/ListArtifacts
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/ListArtifacts \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "runId": "run_123",8 "workflowId": "workflow_123",9 "jobId": "job_123",10 "attemptId": "attempt_123",11 "pageSize": 1,12 "pageToken": "pageToken_example"13}14JSON
Response
{ "artifacts": [ { "artifactId": "artifact_123", "runId": "run_123", "workflowId": "workflow_123", "workflowPath": "workflowPath_example", "jobId": "job_123", "jobKey": "jobKey_example" } ], "nextPageToken": "nextPageToken_example"}
GetArtifactDownloadURLCIService.GetArtifactDownloadURL
Returns a short-lived signed HTTPS URL for one artifact. The URL expires 5 minutes after issuance.
Parameters
artifactIdstringrequired
Unique identifier for the artifact. Returned by ListArtifacts.
Returns
artifactArtifact
Artifact metadata for the requested artifactId.
+Show child parameters
artifactIdstring
Unique identifier for the artifact. Pass it to GetArtifactDownloadURL to download the artifact.
runIdstring
Unique identifier for the parent CI run.
workflowIdstring
Unique identifier for the parent workflow.
workflowPathstring
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
Attempt number that produced the artifact, starting at 1.
namestring
Artifact name as authored by the workflow.
sizeBytesinteger | string
Artifact size in bytes.
createdAtstring
Artifact creation time, in RFC 3339 format.
urlstring
Signed HTTPS URL for the artifact content. Works with any standard HTTPS client and needs no extra authentication; anyone holding the URL can download the artifact until it expires.
expiresAtstring
Signed URL expiration time, in RFC 3339 format. URLs expire 5 minutes after issuance. Artifact retention is unaffected.
POST/depot.ci.v1.CIService/GetArtifactDownloadURL
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetArtifactDownloadURL \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "artifactId": "artifact_123"8}9JSON
Response
{ "artifact": { "artifactId": "artifact_123", "runId": "run_123", "workflowId": "workflow_123", "workflowPath": "workflowPath_example", "jobId": "job_123", "jobKey": "jobKey_example" }, "url": "https://example.com", "expiresAt": "expiresAt_example"}
Secrets
List and manage CI secrets and their variants.
ListSecretsPOST/depot.ci.v3beta2.SecretService/ListSecrets ListSecretAttributesPOST/depot.ci.v3beta2.SecretService/ListSecretAttributes GetSecretPOST/depot.ci.v3beta2.SecretService/GetSecret GetSecretVariantPOST/depot.ci.v3beta2.SecretService/GetSecretVariant CreateSecretVariantPOST/depot.ci.v3beta2.SecretService/CreateSecretVariant SetSecretVariantPOST/depot.ci.v3beta2.SecretService/SetSecretVariant UpdateSecretVariantMetadataPOST/depot.ci.v3beta2.SecretService/UpdateSecretVariantMetadata UpdateSecretVariantValuePOST/depot.ci.v3beta2.SecretService/UpdateSecretVariantValue DeleteSecretVariantPOST/depot.ci.v3beta2.SecretService/DeleteSecretVariant DeleteSecretPOST/depot.ci.v3beta2.SecretService/DeleteSecret
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
idstring
namestring
variantsSecretVariant[]
+Show child parameters
idstring
secretIdstring
namestring
descriptionstring | null
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_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY
variantCountinteger
lastModifiedoneOf<google.protobuf.Timestamp | null>
resolutionVariantResolution
Deprecated: use SecretVariant.resolution for per-row resolution details.
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY
pagePageResponse
+Show child parameters
pageinteger
pageSizeinteger
hasMoreboolean
POST/depot.ci.v3beta2.SecretService/ListSecrets
cURLNode.jsGo
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
Response
{ "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
cURLNode.jsGo
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
Response
{ "attributes": [ { "attribute": { "key": "key_example", "value": "value_example" }, "linkCount": 1 } ]}
GetSecretSecretService.GetSecret
Parameters
idobject
idstringrequired
nameobject
namestringrequired
Returns
secretSecret
+Show child parameters
idstring
namestring
variantsSecretVariant[]
+Show child parameters
idstring
secretIdstring
namestring
descriptionstring | null
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
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY
variantCountinteger
lastModifiedoneOf<google.protobuf.Timestamp | null>
resolutionVariantResolution
Deprecated: use SecretVariant.resolution for per-row resolution details.
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY
POST/depot.ci.v3beta2.SecretService/GetSecret
cURLNode.jsGo
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
Response
{ "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
Parameters
idstringrequired
Returns
variantSecretVariant
+Show child parameters
idstring
secretIdstring
namestring
descriptionstring | null
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
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY
POST/depot.ci.v3beta2.SecretService/GetSecretVariant
cURLNode.jsGo
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
Response
{ "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
secretNamestringrequired
variantNamestring
Name of the variant to create. Leave empty to name it after its attributes: after the repository for a
repository attribute, or "default" with no attributes, suffixed "-2", "-3", and so on when that name is taken.
For example, a variant for "acme/api" is named "acme-api". Fails when a variant with exactly these attributes
already exists.
valuestringrequired
descriptionstring | null
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
idstring
namestring
variantsSecretVariant[]
+Show child parameters
idstring
secretIdstring
namestring
descriptionstring | null
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
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY
variantCountinteger
lastModifiedoneOf<google.protobuf.Timestamp | null>
resolutionVariantResolution
Deprecated: use SecretVariant.resolution for per-row resolution details.
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY
variantSecretVariant
+Show child parameters
idstring
secretIdstring
namestring
descriptionstring | null
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
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY
createdSecretboolean
createdVariantboolean
POST/depot.ci.v3beta2.SecretService/CreateSecretVariant
cURLNode.jsGo
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
Response
{ "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
secretNamestringrequired
variantNamestring
Name of the variant to write. Leave empty, or pass "default", to write the variant whose attributes match
exactly, or else create one named after them: after the repository for a repository attribute, or "default"
with no attributes, suffixed "-2", "-3", and so on when that name is taken. For example, a new variant for
"acme/api" is named "acme-api".
valuestringrequired
descriptionstring | null
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
idstring
namestring
variantsSecretVariant[]
+Show child parameters
idstring
secretIdstring
namestring
descriptionstring | null
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
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY
variantCountinteger
lastModifiedoneOf<google.protobuf.Timestamp | null>
resolutionVariantResolution
Deprecated: use SecretVariant.resolution for per-row resolution details.
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY
variantSecretVariant
+Show child parameters
idstring
secretIdstring
namestring
descriptionstring | null
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
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY
createdSecretboolean
createdVariantboolean
POST/depot.ci.v3beta2.SecretService/SetSecretVariant
cURLNode.jsGo
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
Response
UpdateSecretVariantMetadataSecretService.UpdateSecretVariantMetadata
Parameters
variantIdstringrequired
namestringrequired
Allows renaming a variant, e.g. default -> production.
descriptionstring
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
idstring
secretIdstring
namestring
descriptionstring | null
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
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY
POST/depot.ci.v3beta2.SecretService/UpdateSecretVariantMetadata
cURLNode.jsGo
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
Response
UpdateSecretVariantValueSecretService.UpdateSecretVariantValue
Parameters
variantIdstringrequired
valuestringrequired
Returns
variantSecretVariant
+Show child parameters
idstring
secretIdstring
namestring
descriptionstring | null
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
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY
POST/depot.ci.v3beta2.SecretService/UpdateSecretVariantValue
cURLNode.jsGo
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
Response
DeleteSecretVariantSecretService.DeleteSecretVariant
Parameters
variantIdstringrequired
Returns
deletedSecretboolean
POST/depot.ci.v3beta2.SecretService/DeleteSecretVariant
cURLNode.jsGo
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
Response
{ "deletedSecret": false}
DeleteSecretSecretService.DeleteSecret
Parameters
idobject
idstringrequired
nameobject
namestringrequired
Returns
This method does not document a success response.
POST/depot.ci.v3beta2.SecretService/DeleteSecret
cURLNode.jsGo
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
Response
{}
Variables
List and manage CI variables and their variants.
ListVariablesPOST/depot.ci.v3beta2.VariableService/ListVariables ListVariableAttributesPOST/depot.ci.v3beta2.VariableService/ListVariableAttributes GetVariablePOST/depot.ci.v3beta2.VariableService/GetVariable GetVariableVariantPOST/depot.ci.v3beta2.VariableService/GetVariableVariant CreateVariableVariantPOST/depot.ci.v3beta2.VariableService/CreateVariableVariant SetVariableVariantPOST/depot.ci.v3beta2.VariableService/SetVariableVariant UpdateVariableVariantMetadataPOST/depot.ci.v3beta2.VariableService/UpdateVariableVariantMetadata UpdateVariableVariantValuePOST/depot.ci.v3beta2.VariableService/UpdateVariableVariantValue DeleteVariableVariantPOST/depot.ci.v3beta2.VariableService/DeleteVariableVariant DeleteVariablePOST/depot.ci.v3beta2.VariableService/DeleteVariable
ListVariablesVariableService.ListVariables
Parameters
pagePageRequest
+Show child parameters
pageinteger
1-based page number. Defaults to 1.
pageSizeinteger
Number of parent resources per page.
querystring
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
idstring
namestring
variantsVariableVariant[]
+Show child parameters
idstring
variableIdstring
namestring
valuestring
descriptionstring | null
attributesAttribute[]
lastModifiedoneOf<google.protobuf.Timestamp | null>
variantCountinteger
lastModifiedoneOf<google.protobuf.Timestamp | null>
resolutionVariantResolution
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY
pagePageResponse
+Show child parameters
pageinteger
pageSizeinteger
hasMoreboolean
POST/depot.ci.v3beta2.VariableService/ListVariables
cURLNode.jsGo
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
Response
{ "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
cURLNode.jsGo
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
Response
{ "attributes": [ { "attribute": { "key": "key_example", "value": "value_example" }, "linkCount": 1 } ]}
GetVariableVariableService.GetVariable
Parameters
idobject
idstringrequired
nameobject
namestringrequired
Returns
variableVariable
+Show child parameters
idstring
namestring
variantsVariableVariant[]
+Show child parameters
idstring
variableIdstring
namestring
valuestring
descriptionstring | null
attributesAttribute[]
lastModifiedoneOf<google.protobuf.Timestamp | null>
variantCountinteger
lastModifiedoneOf<google.protobuf.Timestamp | null>
resolutionVariantResolution
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY
POST/depot.ci.v3beta2.VariableService/GetVariable
cURLNode.jsGo
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
Response
{ "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
Parameters
idstringrequired
Returns
variantVariableVariant
+Show child parameters
idstring
variableIdstring
namestring
valuestring
descriptionstring | null
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
cURLNode.jsGo
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
Response
{ "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
valuestringrequired
descriptionstring | null
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
idstring
namestring
variantsVariableVariant[]
+Show child parameters
idstring
variableIdstring
namestring
valuestring
descriptionstring | null
attributesAttribute[]
lastModifiedoneOf<google.protobuf.Timestamp | null>
variantCountinteger
lastModifiedoneOf<google.protobuf.Timestamp | null>
resolutionVariantResolution
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY
variantVariableVariant
+Show child parameters
idstring
variableIdstring
namestring
valuestring
descriptionstring | null
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>
createdVariableboolean
createdVariantboolean
POST/depot.ci.v3beta2.VariableService/CreateVariableVariant
cURLNode.jsGo
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
Response
{ "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
valuestringrequired
descriptionstring | null
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
idstring
namestring
variantsVariableVariant[]
+Show child parameters
idstring
variableIdstring
namestring
valuestring
descriptionstring | null
attributesAttribute[]
lastModifiedoneOf<google.protobuf.Timestamp | null>
variantCountinteger
lastModifiedoneOf<google.protobuf.Timestamp | null>
resolutionVariantResolution
Possible enum values
VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY
variantVariableVariant
+Show child parameters
idstring
variableIdstring
namestring
valuestring
descriptionstring | null
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>
createdVariableboolean
createdVariantboolean
POST/depot.ci.v3beta2.VariableService/SetVariableVariant
cURLNode.jsGo
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
Response
UpdateVariableVariantMetadataVariableService.UpdateVariableVariantMetadata
Parameters
variantIdstringrequired
namestringrequired
descriptionstring
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
idstring
variableIdstring
namestring
valuestring
descriptionstring | null
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
cURLNode.jsGo
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
Response
UpdateVariableVariantValueVariableService.UpdateVariableVariantValue
Parameters
variantIdstringrequired
valuestringrequired
Returns
variantVariableVariant
+Show child parameters
idstring
variableIdstring
namestring
valuestring
descriptionstring | null
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
cURLNode.jsGo
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
Response
DeleteVariableVariantVariableService.DeleteVariableVariant
Parameters
variantIdstringrequired
Returns
deletedVariableboolean
POST/depot.ci.v3beta2.VariableService/DeleteVariableVariant
cURLNode.jsGo
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
Response
{ "deletedVariable": false}
DeleteVariableVariableService.DeleteVariable
Parameters
idobject
idstringrequired
nameobject
namestringrequired
Returns
This method does not document a success response.
POST/depot.ci.v3beta2.VariableService/DeleteVariable
cURLNode.jsGo
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
Response
{}
Diagnostics
Fetch deterministic failure diagnosis for CI resources.
GetFailureDiagnosisPOST/depot.ci.v1.CIService/GetFailureDiagnosis
GetFailureDiagnosisCIService.GetFailureDiagnosis
Returns a failure diagnosis for a run, workflow, job, or attempt.
For run and workflow targets, identical failures are grouped together by error fingerprint. For job and attempt targets, the response is a focused diagnosis of that single job or attempt. When too many jobs failed to diagnose individually, the response is a per-workflow and per-job breakdown instead. When no failure evidence is found, the response is empty. The response is limited to a fixed size and reflects the run's current state. The diagnosis can change while a run is in progress. As more jobs fail, a later call can surface new failures or turn an empty result into a grouped one. As job summaries become available, a later call can also add summary drill-down commands.
Parameters
targetIdstringrequired
Unique identifier for the resource to diagnose: a CI run, workflow, job, or attempt. Must match targetType.
targetTypeFailureDiagnosisTargetTyperequired
Resource type for targetId: run, workflow, job, or attempt.
Possible enum values
FAILURE_DIAGNOSIS_TARGET_TYPE_UNSPECIFIED``FAILURE_DIAGNOSIS_TARGET_TYPE_RUN``FAILURE_DIAGNOSIS_TARGET_TYPE_WORKFLOW``FAILURE_DIAGNOSIS_TARGET_TYPE_JOB``FAILURE_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
statusFailureDiagnosisResourceStatus
Current state of the target resource.
Possible enum values
FAILURE_DIAGNOSIS_RESOURCE_STATUS_UNSPECIFIED``FAILURE_DIAGNOSIS_RESOURCE_STATUS_QUEUED``FAILURE_DIAGNOSIS_RESOURCE_STATUS_WAITING``FAILURE_DIAGNOSIS_RESOURCE_STATUS_RUNNING``FAILURE_DIAGNOSIS_RESOURCE_STATUS_FINISHED``FAILURE_DIAGNOSIS_RESOURCE_STATUS_FAILED``FAILURE_DIAGNOSIS_RESOURCE_STATUS_CANCELLED``FAILURE_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
runStatusFailureDiagnosisResourceStatus
Current state of the parent run.
Possible enum values
workflowIdstring
Unique identifier for the parent workflow. Empty when the target is a run.
workflowNamestring
Parent workflow name from the YAML name: key. Falls back to the file path stem when the workflow doesn't set name:. Empty when neither is available.
workflowPathstring
Parent workflow file path. For example, ".depot/workflows/ci.yml". Empty when the workflow YAML was passed via workflowContent in the Run request, or when the target is a run.
workflowStatusFailureDiagnosisResourceStatus
Current state of the parent workflow.
Possible enum values
jobIdstring
Unique identifier for the parent job. Empty when the target is a run or workflow.
jobKeystring
Parent job key from the workflow. Empty when the target is a run or workflow.
jobDisplayNamestring
Human-readable display name for the parent job. Falls back to jobKey when no display name is set.
jobStatusFailureDiagnosisResourceStatus
Current state of the parent job.
Possible enum values
jobConclusionFailureDiagnosisConclusion
Conclusion of the parent job. Unspecified until the job concludes.
Possible enum values
FAILURE_DIAGNOSIS_CONCLUSION_UNSPECIFIED``FAILURE_DIAGNOSIS_CONCLUSION_SUCCESS``FAILURE_DIAGNOSIS_CONCLUSION_FAILURE``FAILURE_DIAGNOSIS_CONCLUSION_CANCELLED``FAILURE_DIAGNOSIS_CONCLUSION_SKIPPED``FAILURE_DIAGNOSIS_CONCLUSION_TIMED_OUT
attemptIdstring
Unique identifier for the parent attempt. Empty unless the target is an attempt.
attemptinteger
Attempt number for the parent attempt. Zero unless the target is an attempt.
attemptStatusFailureDiagnosisResourceStatus
Current state of the parent attempt.
Possible enum values
attemptConclusionFailureDiagnosisConclusion
Conclusion of the parent attempt. Unspecified until the attempt concludes.
Possible enum values
truncatedContextFieldsstring[]
Names of context fields that were truncated to fit the response limits.
stateFailureDiagnosisState
Overall diagnosis state.
- EMPTY: No failure evidence found.
failureGroupsandrepresentativeAttemptsare 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.
overLimitBreakdownlists per-workflow and per-job counts instead.
Possible enum values
FAILURE_DIAGNOSIS_STATE_UNSPECIFIED``FAILURE_DIAGNOSIS_STATE_EMPTY``FAILURE_DIAGNOSIS_STATE_GROUPED_FAILURES``FAILURE_DIAGNOSIS_STATE_FOCUSED_FAILURE``FAILURE_DIAGNOSIS_STATE_OVER_LIMIT
emptyReasonFailureDiagnosisEmptyReason
Reason the diagnosis is empty. Set only when state is EMPTY.
Possible enum values
FAILURE_DIAGNOSIS_EMPTY_REASON_UNSPECIFIED``FAILURE_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
jobIdstring
Unique identifier for the parent job.
jobKeystring
Parent job key from the workflow.
jobDisplayNamestring
Human-readable display name for the parent job. Falls back to jobKey when no display name is set.
jobStatusFailureDiagnosisResourceStatus
Current state of the parent job.
Possible enum values
jobConclusionFailureDiagnosisConclusion
Conclusion of the parent job. Unspecified until the job concludes.
Possible enum values
attemptIdstring
Unique identifier for this attempt.
attemptinteger
Attempt number, starting at 1 for the first run.
attemptStatusFailureDiagnosisResourceStatus
Current state of the attempt.
Possible enum values
attemptConclusionFailureDiagnosisConclusion
Conclusion of the attempt. Unspecified until the attempt concludes.
Possible enum values
errorMessagestring
Error message captured for this attempt, possibly truncated.
errorMessageTruncatedboolean
True when errorMessage was truncated to fit the response limit.
errorMessageOriginalLengthinteger
Length of the full errorMessage, in characters, before any truncation.
diagnosisstring
AI-generated diagnosis for this attempt. Empty when no diagnosis is available.
possibleFixstring
AI-generated suggested fix for this attempt. Empty when no suggestion is available.
relevantLinesRelevantErrorLine[]
AI-selected log lines correlated with the failure. Empty when no log analysis is available.
nextCommandsDrillDownCommand[]
Drill-down commands suggested for this attempt. For example, "depot ci logs" or "depot ci summary".
omittedRepresentativeCountinteger
Number of additional candidate attempts omitted from representatives.
representativeAttemptsRepresentativeAttempt[]
Representative attempts from all failure groups in one list. Contains the same entries as the nested failureGroups[].representatives lists. Empty when state is EMPTY or OVER_LIMIT.
+Show child parameters
runIdstring
Unique identifier for the parent CI run.
workflowIdstring
Unique identifier for the parent workflow.
workflowNamestring
Parent workflow name from the YAML name: key. Falls back to the file path stem when the workflow doesn't set name:. Empty when neither is available.
workflowPathstring
jobIdstring
Unique identifier for the parent job.
jobKeystring
Parent job key from the workflow.
jobDisplayNamestring
Human-readable display name for the parent job. Falls back to jobKey when no display name is set.
jobStatusFailureDiagnosisResourceStatus
Current state of the parent job.
Possible enum values
jobConclusionFailureDiagnosisConclusion
Conclusion of the parent job. Unspecified until the job concludes.
Possible enum values
attemptIdstring
Unique identifier for this attempt.
attemptinteger
Attempt number, starting at 1 for the first run.
attemptStatusFailureDiagnosisResourceStatus
Current state of the attempt.
Possible enum values
attemptConclusionFailureDiagnosisConclusion
Conclusion of the attempt. Unspecified until the attempt concludes.
Possible enum values
errorMessagestring
Error message captured for this attempt, possibly truncated.
errorMessageTruncatedboolean
True when errorMessage was truncated to fit the response limit.
errorMessageOriginalLengthinteger
Length of the full errorMessage, in characters, before any truncation.
diagnosisstring
AI-generated diagnosis for this attempt. Empty when no diagnosis is available.
possibleFixstring
AI-generated suggested fix for this attempt. Empty when no suggestion is available.
relevantLinesRelevantErrorLine[]
AI-selected log lines correlated with the failure. Empty when no log analysis is available.
+Show child parameters
stepIdstring
Workflow step identifier the line was emitted from. Empty when not associated with a step.
lineNumberinteger
Persisted line number within the emitting stream.
contentstring
Log line content, possibly truncated.
contentTruncatedboolean
True when content was truncated to fit the per-line limit.
contentOriginalLengthinteger
Length of the full content, in characters, before any truncation.
nextCommandsDrillDownCommand[]
Drill-down commands suggested for this attempt. For example, "depot ci logs" or "depot ci summary".
+Show child parameters
kindDrillDownCommandKind
Kind of drill-down command.
- LOGS: Equivalent to
depot ci logs <attempt_id>. - SUMMARY: Equivalent to
depot ci summary <attempt_id>. - DIAGNOSE_WORKFLOW: Equivalent to
depot ci diagnose --workflow <workflow_id>. - DIAGNOSE_JOB: Equivalent to
depot ci diagnose --job <job_id>.
Possible enum values
DRILL_DOWN_COMMAND_KIND_UNSPECIFIED``DRILL_DOWN_COMMAND_KIND_LOGS``DRILL_DOWN_COMMAND_KIND_SUMMARY``DRILL_DOWN_COMMAND_KIND_DIAGNOSE_WORKFLOW``DRILL_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.
omittedFailureGroupCountinteger
Number of omitted failure groups.
failureGroupLimitinteger
Maximum number of failure groups returned in a single response. 0 means no group limit.
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.
Possible enum values
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
targetIdstring
Unique identifier for the resource this row describes.
labelstring
Human-readable label for the resource. For example, a workflow name or job key.
statusFailureDiagnosisResourceStatus
Current state of the resource.
Possible enum values
failedProblemCandidateCountinteger
Number of failed problem candidates attributed to this resource.
nextCommandsDrillDownCommand[]
Drill-down commands suggested for this resource.
+Show child parameters
kindDrillDownCommandKind
Kind of drill-down command.
Possible enum values
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
cURLNode.jsGo
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetFailureDiagnosis \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "targetId": "target_123",8 "targetType": "FAILURE_DIAGNOSIS_TARGET_TYPE_UNSPECIFIED"9}10JSON
Response
{ "orgId": "org_123", "target": { "targetId": "target_123", "targetType": "FAILURE_DIAGNOSIS_TARGET_TYPE_UNSPECIFIED", "status": "FAILURE_DIAGNOSIS_RESOURCE_STATUS_UNSPECIFIED" }, "context": { "runId": "run_123", "repo": "repo_example", "ref": "ref_example", "sha": "b2f5ff47436671b6e533d8dc3614845d", "headSha": "b2f5ff47436671b6e533d8dc3614845d", "trigger": "trigger_example" }, "state": "FAILURE_DIAGNOSIS_STATE_UNSPECIFIED", "emptyReason": "FAILURE_DIAGNOSIS_EMPTY_REASON_UNSPECIFIED", "failureGroups": [ { "fingerprint": "fingerprint_example", "source": "source_example", "count": 1, "errorMessage": "errorMessage_example", "errorMessageTruncated": false, "errorMessageOriginalLength": 1 } ], "representativeAttempts": [ { "runId": "run_123", "workflowId": "workflow_123", "workflowName": "workflowName_example", "workflowPath": "workflowPath_example", "jobId": "job_123", "jobKey": "jobKey_example" } ], "bounds": { "failedProblemCandidateCount": 1, "failedProblemCandidateCap": 1, "totalProblemJobCount": 1, "skippedDependentCount": 1, "totalFailureGroupCount": 1, "omittedFailureGroupCount": 1 }}
Errors
Every method returns errors as a Connect error object with a string code, a developer-facing message, and optional details. The status code maps to an HTTP status for callers using the JSON over HTTP transport. The following codes may be returned by the Depot CI API.
Code
HTTP
When it happens
Common causes
unauthenticatedgRPC 16
401
The request has no valid token.
Missing Authorization header, a non-Bearer scheme, or an invalid or expired token.
permission_deniedgRPC 7
403
The token is valid but not allowed for this resource or action.
Wrong token type, the caller is not a member of the organization, a missing x-depot-org header on an organization token, or the organization has no GitHub Code Connection.
invalid_argumentgRPC 3
400
A request field is missing or malformed.
A repo not in owner/name format, a missing run, workflow, or artifact identifier, an invalid page token, a non-numeric pr, a malformed sha, or an unsupported target_type or log format.
not_foundgRPC 5
404
The referenced resource does not exist or is not visible to the caller.
An unknown run, workflow, job, attempt, or artifact identifier, or a workflow that has no workflow_dispatch trigger.
failed_preconditiongRPC 9
412
The resource exists but is not in a valid state for the action.
Cancelling a run, workflow, or job that is not queued or running, retrying before a workflow finishes, or a status that changed mid-request.
resource_exhaustedgRPC 8
429
A limit was reached.
Too many concurrent log streams for the token, organization, or attempt, a log stream or export that exceeded its maximum duration, or a metrics result that is too large.
unavailablegRPC 14
503
A dependency is temporarily down. The request can be retried.
The log or metrics store is unavailable, or a transient read failure occurred.
internalgRPC 13
500
An unexpected server-side failure occurred.
A download URL could not be generated, a trigger config failed to parse, or a database write failed.
Ask AI
StripeM-Inner