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

# Get a run

> Returns a run's status, its failure kind when it failed or was cancelled, the document it processed and the credits it billed. Poll it until `status` is `completed`, `failed` or `cancelled`.

Requires the `runs:read` [scope](/api-reference/authentication#scopes). See [polling a run](/api-reference/polling-runs) for what each `status` means and when to stop polling.


## OpenAPI

````yaml GET /runs/{runId}
openapi: 3.1.1
info:
  title: Ingestly API
  description: >-
    Public Ingestly API. Authenticate every request with an API key in the
    `X-Api-Key` header. A key belongs to one organization and carries scopes
    (such as `workflows:trigger` or `runs:read`); each operation requires one
    scope, and a key without it is rejected with 403. Errors use RFC 7807
    problem details.
  version: 1.0.0
servers:
  - url: https://api.ingestly.ai
security:
  - ApiKey: []
tags:
  - name: Workflows
  - name: Runs
  - name: Review Tasks
  - name: Events
  - name: Documents
paths:
  /runs/{runId}:
    get:
      tags:
        - Runs
      summary: Get a run
      description: >-
        Returns a run's status, its failure kind when it failed or was
        cancelled, the document it processed and the credits it billed. Poll it
        until `status` is `completed`, `failed` or `cancelled`.
      operationId: getRun
      parameters:
        - name: runId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          headers:
            X-Correlation-ID:
              description: >-
                Server-generated request identifier. Quote it when contacting
                support.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRunResponse'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetailResponse'
        '401':
          description: >-
            Unauthorized. The API key is missing, invalid, expired or
            deactivated.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetailResponse'
        '403':
          description: >-
            Forbidden. The API key lacks the `runs:read` scope, or the plan does
            not include API access.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetailResponse'
        '404':
          description: >-
            Not Found. No run with this id exists in the key's organization and
            environment. A run the trigger returned may stay 404 when it never
            started; the document then carries the reason.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetailResponse'
        '429':
          description: >-
            Too Many Requests. The plan's rate limit was exceeded; retry after
            the seconds in Retry-After.
          headers:
            Retry-After:
              description: Seconds until the rate limit window resets.
              schema:
                type: integer
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetailResponse'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetailResponse'
components:
  schemas:
    GetRunResponse:
      required:
        - id
        - workflowId
        - documentId
        - kind
        - status
        - startedOn
        - billedCredits
      type: object
      properties:
        id:
          examples:
            - 0199a6c2-4b7d-7e01-8f3a-2c4d6e8f0a1b
          type: string
          format: uuid
        workflowId:
          examples:
            - 0199a6c1-9e2f-7c3d-8a4b-1c2d3e4f5a6b
          type: string
          format: uuid
        documentId:
          examples:
            - 0199a6c2-3f1e-7b2a-9c4d-5e6f7a8b9c0d
          type: string
          format: uuid
        parentRunId:
          type:
            - 'null'
            - string
          format: uuid
        sourceRunId:
          type:
            - 'null'
            - string
          format: uuid
        kind:
          examples:
            - full
          enum:
            - full
            - step_test
            - up_to_node_test
            - restart_from_node
            - fan_out_child
            - sub_workflow_call
          type: string
        status:
          examples:
            - completed
          enum:
            - running
            - completed
            - failed
            - cancelled
            - awaiting_children
            - queued
            - review
            - waiting
          type: string
        error:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/GetRunResponseErrorResponse'
        reference:
          examples:
            - PO-1182
          type:
            - 'null'
            - string
        startedOn:
          examples:
            - '2026-10-02T14:03:11+00:00'
          type: string
          format: date-time
        completedOn:
          type:
            - 'null'
            - string
          format: date-time
        billedCredits:
          examples:
            - 3
          type: integer
          format: int32
    ProblemDetailResponse:
      required:
        - status
        - title
        - type
        - instance
        - traceId
      type: object
      properties:
        status:
          type: integer
          format: int32
        title:
          type: string
        type:
          type: string
        instance:
          type: string
        traceId:
          type: string
        detail:
          type:
            - 'null'
            - string
        errors:
          type:
            - 'null'
            - object
          additionalProperties:
            type: array
            items:
              type: string
    GetRunResponseErrorResponse:
      required:
        - code
        - message
      type: object
      properties:
        code:
          examples:
            - timeout
          enum:
            - timeout
            - provider_error
            - connector_error
            - configuration
            - document_rejected
            - credits
            - organization_inactive
            - startup_error
            - child_run_failed
            - review_resume_failed
            - step_budget_exhausted
            - run_deleted
            - step_failed
            - cancelled_by_user
            - cancelled_by_timeout_or_operator
            - parent_cancelled
            - parent_failed
          type: string
        message:
          examples:
            - Timed out
          type: string
  securitySchemes:
    ApiKey:
      type: apiKey
      name: X-Api-Key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.