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

# Get a run

> One run: its status, the step it waits on and the question the reviewers have, the decisions so far and the result. With `wait`, the call holds until the run has finished or that many seconds have passed (max 60), so you can poll without hammering the API.



## OpenAPI

````yaml GET /api/executions/{id}
openapi: 3.1.0
info:
  title: HITL API
  version: 1.0.0
  description: >-
    Run the workflows you build in HITL, follow each run until a person has
    answered, and manage who reviews them.
servers:
  - url: https://api.hitl.sh/v1
security:
  - bearerAuth: []
tags:
  - name: Workflows
  - name: Runs
  - name: Reviewers
  - name: Webhooks
  - name: Account
  - name: Uploads
paths:
  /api/executions/{id}:
    get:
      tags:
        - Runs
      summary: Get a run
      description: >-
        One run: its status, the step it waits on and the question the reviewers
        have, the decisions so far and the result. With `wait`, the call holds
        until the run has finished or that many seconds have passed (max 60), so
        you can poll without hammering the API.
      operationId: runs-get
      parameters:
        - name: id
          in: path
          required: true
          description: The execution id
          schema:
            type: string
            example: 6af2cf07c6a9f1dc71efd5e7
        - name: wait
          in: query
          required: false
          description: Seconds to wait for the run to finish, up to 60
          schema:
            type: integer
            example: 30
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: boolean
                  msg:
                    type: string
                  data:
                    $ref: '#/components/schemas/Execution'
              example:
                data:
                  id: 6af2ceb8c6a9f1dc71efd5dc
                  workflow_id: 6af2ce4e8207961501f59472
                  workflow_name: Refund approval
                  status: completed
                  finished: true
                  input:
                    amount: 249
                    currency: USD
                    customer:
                      email: ada@example.com
                      name: Ada Lovelace
                    order_id: ORD-48213
                    reason: Arrived with a cracked screen.
                  result: approve
                  decisions:
                    - node_id: review-1
                      reviewer_id: 6af2ce48967ce8777084a293
                      reviewer_name: Priya Shah
                      platform: web_portal
                      decision: approve
                      responded_at: '2026-11-10T07:58:52.241Z'
                      response_time_seconds: 2.532943375
                  action_results:
                    - node_id: action-1
                      type: webhook
                      status: success
                      response: >-
                        200: {"json": {"amount": 249, "approved_by": "Priya
                        Shah", "order_id": "ORD-48213"}}
                      executed_at: '2026-11-10T07:58:53.482Z'
                  trail:
                    - node_id: trigger-1
                      status: done
                      at: '2026-11-10T07:58:49.604Z'
                    - node_id: review-1
                      status: waiting
                      at: '2026-11-10T07:58:49.817Z'
                    - node_id: review-1
                      status: done
                      at: '2026-11-10T07:58:53.482Z'
                    - node_id: condition-1
                      status: done
                      at: '2026-11-10T07:58:53.482Z'
                    - node_id: action-1
                      status: done
                      at: '2026-11-10T07:58:53.847Z'
                    - node_id: end-1
                      status: done
                      at: '2026-11-10T07:58:53.847Z'
                  triggered_via: api
                  callback_url: https://httpbin.org/post
                  callback:
                    state: delivered
                    attempts: 1
                    last_status: 200
                    last_attempt_at: '2026-11-10T07:58:54.938Z'
                    delivered_at: '2026-11-10T07:58:54.938Z'
                  started_at: '2026-11-10T07:58:48.493Z'
                  completed_at: '2026-11-10T07:58:53.847Z'
                  duration_seconds: 5.354
                error: false
                msg: Execution retrieved
        '400':
          $ref: '#/components/responses/E400'
        '401':
          $ref: '#/components/responses/E401'
        '404':
          $ref: '#/components/responses/E404'
        '429':
          $ref: '#/components/responses/E429'
components:
  schemas:
    Execution:
      type: object
      properties:
        id:
          type: string
        workflow_id:
          type: string
        workflow_name:
          type: string
        status:
          type: string
          enum:
            - running
            - pending_review
            - completed
            - failed
            - timed_out
        finished:
          type: boolean
          description: True for completed, failed and timed_out
        input:
          type: object
          additionalProperties: true
          description: What the run was started with
        current_step:
          type: object
          properties:
            node_id:
              type: string
            type:
              type: string
            label:
              type: string
        waiting_for:
          type: object
          description: 'While `pending_review`: the question the reviewers have'
          properties:
            request_id:
              type: string
            status:
              type: string
            request_text:
              type: string
            response_type:
              type: string
            response_config:
              type: object
              additionalProperties: true
            timeout_at:
              type: string
              format: date-time
            created_at:
              type: string
              format: date-time
        result:
          description: The last decision, once there is one
        decisions:
          type: array
          items:
            $ref: '#/components/schemas/Decision'
        action_results:
          type: array
          items:
            $ref: '#/components/schemas/ActionResult'
        trail:
          type: array
          items:
            type: object
            properties:
              node_id:
                type: string
              status:
                type: string
                enum:
                  - done
                  - waiting
                  - failed
                  - skipped
              at:
                type: string
                format: date-time
        error:
          type: string
        triggered_via:
          type: string
          enum:
            - api
            - webhook
            - email
            - schedule
            - manual
            - test
        callback_url:
          type: string
        callback:
          type: object
          properties:
            state:
              type: string
              enum:
                - queued
                - delivered
                - failed
            attempts:
              type: integer
            last_status:
              type: integer
            last_error:
              type: string
            last_attempt_at:
              type: string
              format: date-time
            delivered_at:
              type: string
              format: date-time
        started_at:
          type: string
          format: date-time
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
        duration_seconds:
          type: number
    Decision:
      type: object
      properties:
        node_id:
          type: string
          description: The review step
        reviewer_id:
          type: string
        reviewer_name:
          type: string
        platform:
          type: string
          description: 'Where they answered: `mobile`, `web_portal`, `telegram`, ...'
        decision:
          description: >-
            The answer: an option value, a list of values, `true`/`false`, a
            number or text
        responded_at:
          type: string
          format: date-time
        response_time_seconds:
          type: number
    ActionResult:
      type: object
      properties:
        node_id:
          type: string
        type:
          type: string
          example: webhook
        status:
          type: string
          enum:
            - success
            - failed
        response:
          type: string
          description: Status code and the start of the response
        executed_at:
          type: string
          format: date-time
    Error:
      type: object
      required:
        - error
        - msg
      properties:
        error:
          type: boolean
          example: true
        msg:
          type: string
          description: What went wrong, in plain words
        code:
          type: string
          description: >-
            A machine-readable reason, when there is one (for example
            `confirmation_required`)
  responses:
    E400:
      description: Invalid input; `msg` says what to fix
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: true
            msg: Invalid execution id
    E401:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: true
            msg: Invalid API key
    E404:
      description: Not found, or not yours
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: true
            msg: Workflow not found
    E429:
      description: 'Rate limit: 1,000 requests an hour per key on /workflows and /executions'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: true
            msg: Rate limit exceeded
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your API key: `hitl_live_…`'

````

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