> ## Documentation Index
> Fetch the complete documentation index at: https://astronomer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Start a DAG-failure diagnosis run

> Starts an asynchronous AI-powered diagnosis run for a failed DAG run (or specific task within it) and returns a run ID. Use the run ID to poll status and stream events.



## OpenAPI

````yaml /astro/api/v-1-labs/openapi.yaml post /organizations/{organizationId}/observability/deployments/{deploymentId}/dag-failure-diagnosis/runs
openapi: 3.0.3
info:
  contact: {}
  description: Astro Labs API - Experimental endpoints for preview features
  title: Astro Labs API
  version: v1
servers:
  - url: https://api.astronomer.io/labs/v1
security:
  - JWT: []
tags:
  - description: >-
      Canned-data placeholder used to exercise the labs epoch versioning
      surface. Real labs endpoints register their own tags.
    name: Example
paths:
  /organizations/{organizationId}/observability/deployments/{deploymentId}/dag-failure-diagnosis/runs:
    post:
      tags:
        - Observability
      summary: Start a DAG-failure diagnosis run
      description: >-
        Starts an asynchronous AI-powered diagnosis run for a failed DAG run (or
        specific task within it) and returns a run ID. Use the run ID to poll
        status and stream events.
      operationId: LabsStartDagFailureDiagnosis
      parameters:
        - description: The ID of the Organization to which the Deployment belongs.
          in: path
          name: organizationId
          required: true
          schema:
            type: string
        - description: The Deployment's ID.
          in: path
          name: deploymentId
          required: true
          schema:
            type: string
        - description: Skip DB session dedup + Redis cache and force a fresh diagnosis run
          in: query
          name: force
          schema:
            default: false
            type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartDagFailureDiagnosisRequest'
        description: The request body for starting a DAG-failure diagnosis run.
        required: true
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DagFailureDiagnosisRun'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      security:
        - JWT: []
components:
  schemas:
    StartDagFailureDiagnosisRequest:
      properties:
        dagId:
          description: The ID of the DAG that failed.
          example: my_dag
          type: string
        runId:
          description: The ID of the DAG run that failed.
          example: scheduled__2026-05-13T00:00:00+00:00
          type: string
        skipCacheRead:
          description: >-
            If true, bypass any previously cached diagnosis for this
            DAG/run/task and force a fresh run.
          type: boolean
        taskId:
          description: >-
            The ID of the task that failed. Optional; if omitted, the agent
            diagnoses the run as a whole.
          example: my_task
          type: string
        tryNumbers:
          description: The specific task try numbers to diagnose. Optional.
          example:
            - 1
            - 2
          items:
            type: integer
          type: array
      required:
        - dagId
        - runId
      type: object
    DagFailureDiagnosisRun:
      properties:
        createdAt:
          description: The RFC3339 timestamp when the run was created.
          example: '2026-05-14T12:34:56Z'
          type: string
        runId:
          description: >-
            The unique identifier of the diagnosis run. Use this to poll status
            and stream events.
          example: 7f3b6f5d-2c4e-4f2b-9c1d-1a2b3c4d5e6f
          type: string
        status:
          description: The current status of the diagnosis run.
          enum:
            - pending
            - running
            - completed
            - failed
            - timed_out
          example: pending
          type: string
      required:
        - createdAt
        - runId
        - status
      type: object
    Error:
      properties:
        fieldErrors:
          description: >-
            FieldErrors carries one entry per failed request-validation
            constraint.

            Only present on 400 responses caused by request binding/validation.
          items:
            $ref: '#/components/schemas/FieldValidationError'
          type: array
        message:
          type: string
        requestId:
          type: string
        statusCode:
          maximum: 600
          minimum: 400
          type: integer
      required:
        - message
        - requestId
        - statusCode
      type: object
    FieldValidationError:
      properties:
        code:
          type: string
        field:
          type: string
        message:
          type: string
      required:
        - code
        - field
        - message
      type: object
  securitySchemes:
    JWT:
      scheme: bearer
      type: http

````