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

# Get Run

> Poll a Flow run for its status and result

## Behavior

* Poll this endpoint with the `id` returned by [Create Run](/api-reference/flows/trigger-run) until `status` reaches a terminal value (`COMPLETED`, `FAILED`, `CANCELLED`, or `SKIPPED`).
* **`report`** is the full analyst-facing result as Markdown text. It is only set once `status` is `COMPLETED`.
* **`output_ref`** is set once structured output has been captured for the run. Its presence (not its value) is the signal that [Get Run Output URL](/api-reference/flows/get-run-output-url) can be called to download the structured output file.
* **`error`** is only set when `status` is `FAILED`.
* Returns `404` if `runId` does not exist, or belongs to a different customer.


## OpenAPI

````yaml GET /flow-runs/{runId}
openapi: 3.0.1
info:
  version: 1.0.0
  title: Diligent Flows
  description: Trigger a Flow run and retrieve its result.
servers:
  - url: https://api.godiligent.ai
    description: Production
  - url: https://api.sandbox.godiligent.ai
    description: Sandbox
security:
  - xApiKey: []
tags:
  - name: Flows
    description: Trigger a Flow run and retrieve its result
paths:
  /flow-runs/{runId}:
    get:
      tags:
        - Flows
      summary: Get Run
      description: Returns the current status of a run, and its result once complete.
      operationId: getFlowRun
      parameters:
        - name: runId
          in: path
          description: The run's id, returned by POST /flows/{flowId}/runs
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowRun'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Run not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: RUN_NOT_FOUND
                message: 'Run not found: 8f14e45f-ceea-4c6b-a1b2-3c4d5e6f7890'
        '500':
          description: Internal Server Error
      security:
        - xApiKey: []
components:
  schemas:
    FlowRun:
      type: object
      required:
        - id
        - flow_id
        - status
        - triggered_at
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
        flow_id:
          type: string
        status:
          $ref: '#/components/schemas/FlowRunStatus'
        triggered_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
          nullable: true
          description: Set once the run moves from QUEUED to RUNNING.
        completed_at:
          type: string
          format: date-time
          nullable: true
          description: Set once the run reaches a terminal state.
        input:
          type: object
          additionalProperties: true
          description: The input the run was triggered with.
        report:
          type: string
          nullable: true
          description: >-
            The full analyst-facing Markdown report. Set only once the run has
            COMPLETED.
        output_ref:
          type: string
          nullable: true
          description: >-
            Present once structured output has been captured. Its presence means
            GET /flow-runs/{runId}/output-url can be called to download it.
        error:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/RunError'
          description: Set only when status is FAILED.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: >-
            Machine-readable error code, e.g. FLOW_NOT_FOUND, RUN_NOT_FOUND,
            VALIDATION_ERROR.
        message:
          type: string
    FlowRunStatus:
      type: string
      enum:
        - QUEUED
        - RUNNING
        - COMPLETED
        - FAILED
        - CANCELLED
        - SKIPPED
      description: >-
        QUEUED: awaiting worker pickup. RUNNING: executing.
        COMPLETED/FAILED/CANCELLED/SKIPPED: terminal states.
    RunError:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
  securitySchemes:
    xApiKey:
      type: apiKey
      name: X-API-KEY
      in: header

````