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

# Analyze a failed workflow run

> <Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Explains why a run failed, in plain language.

This only works on runs whose `status` is `failed`. Anything else returns a 400.

The first call runs a language model over the run's steps and its definition, then stores the result, so later calls for the same run return the stored text without paying for it again.

Check that `explanation` is non-empty before showing it. If the model is unavailable you still get a 200, with `explanation` and `generated_at` both empty rather than an error.

This endpoint is limited to 5 requests per minute.



## OpenAPI

````yaml /developers/references/app-management/app-management-openapi.json post /api/apps/{app_id}/workflows/{workflow_id}/runs/{run_id}/analyze
openapi: 3.1.0
info:
  title: Base44 App Management API
  version: 1.0.0
servers:
  - url: https://app.base44.com
security:
  - ApiKeyAuth: []
paths:
  /api/apps/{app_id}/workflows/{workflow_id}/runs/{run_id}/analyze:
    post:
      summary: Analyze a failed workflow run
      description: >-
        <Info>This API is in beta. Endpoints, fields, and behavior may still
        change, so avoid depending on it in production.</Info>


        Explains why a run failed, in plain language.


        This only works on runs whose `status` is `failed`. Anything else
        returns a 400.


        The first call runs a language model over the run's steps and its
        definition, then stores the result, so later calls for the same run
        return the stored text without paying for it again.


        Check that `explanation` is non-empty before showing it. If the model is
        unavailable you still get a 200, with `explanation` and `generated_at`
        both empty rather than an error.


        This endpoint is limited to 5 requests per minute.
      operationId: >-
        analyze_run_api_apps__app_id__workflows__workflow_id__runs__run_id__analyze_post
      parameters:
        - name: app_id
          in: path
          required: true
          schema:
            type: string
            description: ID of the app whose workflows you want to work with.
            title: App Id
          description: ID of the app whose workflows you want to work with.
          example: 6820f3a4e7b91d003c45a1f2
        - name: workflow_id
          in: path
          required: true
          schema:
            type: string
            description: >-
              ID of the workflow, as returned in `id` by [List
              workflows](/api-reference/list-workflows).
            title: Workflow Id
          description: >-
            ID of the workflow, as returned in `id` by [List
            workflows](/api-reference/list-workflows).
          example: 68b1c0d4e7b91d003c45a1f2
        - name: run_id
          in: path
          required: true
          schema:
            type: string
            description: >-
              ID of the run, as returned in `run_id` by [List runs for a
              workflow](/api-reference/list-runs-for-a-workflow).
            title: Run Id
          description: >-
            ID of the run, as returned in `run_id` by [List runs for a
            workflow](/api-reference/list-runs-for-a-workflow).
          example: 0195f2a1-4c3e-7b21-9f0d-2a5c8e1b4d77
      responses:
        '200':
          description: The explanation. Check that it is non-empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeRunResponse'
        '400':
          description: The run did not fail, so there is nothing to explain.
        '401':
          description: Missing or invalid credentials.
        '403':
          description: >-
            You don't have access to this app, the app does not exist, the app
            still runs the older automations engine instead of workflows, or you
            used a workspace API key.
        '404':
          description: >-
            There is no workflow with this ID on this app, or no run with this
            ID on that workflow.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AnalyzeRunResponse:
      properties:
        explanation:
          type: string
          title: Explanation
          description: >-
            Why the run failed, in plain language. Empty when the model could
            not be reached.
          example: >-
            The email step failed because the recipient address was missing from
            the trigger payload.
        generated_at:
          type: string
          title: Generated At
          description: >-
            When the explanation was produced, as an ISO 8601 timestamp. Empty
            when none was produced.
          example: '2026-08-25T09:20:11Z'
      type: object
      required:
        - explanation
        - generated_at
      title: AnalyzeRunResponse
      description: AI-generated failure analysis.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api_key
      description: Personal API key.

````