Skip to main content
POST
Start a DAG-failure diagnosis run

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

organizationId
string
required

The ID of the Organization to which the Deployment belongs.

deploymentId
string
required

The Deployment's ID.

Query Parameters

force
boolean
default:false

Skip DB session dedup + Redis cache and force a fresh diagnosis run

Body

application/json

The request body for starting a DAG-failure diagnosis run.

dagId
string
required

The ID of the DAG that failed.

Example:

"my_dag"

runId
string
required

The ID of the DAG run that failed.

Example:

"scheduled__2026-05-13T00:00:00+00:00"

skipCacheRead
boolean

If true, bypass any previously cached diagnosis for this DAG/run/task and force a fresh run.

taskId
string

The ID of the task that failed. Optional; if omitted, the agent diagnoses the run as a whole.

Example:

"my_task"

tryNumbers
integer[]

The specific task try numbers to diagnose. Optional.

Example:

Response

OK

createdAt
string
required

The RFC3339 timestamp when the run was created.

Example:

"2026-05-14T12:34:56Z"

runId
string
required

The unique identifier of the diagnosis run. Use this to poll status and stream events.

Example:

"7f3b6f5d-2c4e-4f2b-9c1d-1a2b3c4d5e6f"

status
enum<string>
required

The current status of the diagnosis run.

Available options:
pending,
running,
completed,
failed,
timed_out
Example:

"pending"