Start a Dag-failure diagnosis run - Astronomer

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>"
    }
  ]
}

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.

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:

[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