Start a Dag-failure diagnosis run

Starts an asynchronous AI-powered diagnosis (root cause investigation) of a failed Dag run, or of one task within it, and returns a run ID. If the same failure was already diagnosed or is being diagnosed, returns that run instead unless force is true. Then poll the run’s status until it is completed, and read its diagnosis with “Get the diagnosis of a Dag-failure diagnosis run”. Rate limited per Organization.

POST

/

organizations

/

{organizationId}

/

observability

/

deployments

/

{deploymentId}

/

dag-failure-diagnosis

/

runs

Error

A valid request URL is required to generate request examples

{
  "createdAt": "2026-05-14T12:34:56Z",
  "runId": "7f3b6f5d-2c4e-4f2b-9c1d-1a2b3c4d5e6f",
  "status": "pending"
}

{
  "message": "<string>",
  "requestId": "<string>",
  "statusCode": 500,
  "fieldErrors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "message": "<string>",
  "requestId": "<string>",
  "statusCode": 500,
  "fieldErrors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "message": "<string>",
  "requestId": "<string>",
  "statusCode": 500,
  "fieldErrors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "message": "<string>",
  "requestId": "<string>",
  "statusCode": 500,
  "fieldErrors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "message": "<string>",
  "requestId": "<string>",
  "statusCode": 500,
  "fieldErrors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

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.

Maximum string length: 250

Example:

"my_dag"

runId

string

required

The ID of the Dag run that failed.

Maximum string length: 250

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.

Maximum string length: 250

Example:

"my_task"

tryNumbers

integer[]

The specific task try numbers to diagnose. Optional.

Maximum array length: 100

Example:

[1, 2]

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"

⌘I

Error

A valid request URL is required to generate request examples

{
  "createdAt": "2026-05-14T12:34:56Z",
  "runId": "7f3b6f5d-2c4e-4f2b-9c1d-1a2b3c4d5e6f",
  "status": "pending"
}

{
  "message": "<string>",
  "requestId": "<string>",
  "statusCode": 500,
  "fieldErrors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "message": "<string>",
  "requestId": "<string>",
  "statusCode": 500,
  "fieldErrors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "message": "<string>",
  "requestId": "<string>",
  "statusCode": 500,
  "fieldErrors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "message": "<string>",
  "requestId": "<string>",
  "statusCode": 500,
  "fieldErrors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "message": "<string>",
  "requestId": "<string>",
  "statusCode": 500,
  "fieldErrors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>"
    }
  ]
}