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

# Get a run's current status, including its tool invocations



## OpenAPI

````yaml /openapi.json get /api/v1/runs/{runId}
openapi: 3.1.0
info:
  title: VyomFlow API
  version: 1.0.0
  description: >-
    Internal REST surface (S1–S6) exposed as reference documentation. This is
    the S8 minimum-fallback scope (Submission Requirement #13) — generated
    directly from the same Zod contracts the Route Handlers validate against,
    not a hand-maintained duplicate. Auth documented here is the app's own Clerk
    bearer scheme; see the public API-key section for the versioned public
    surface, where shipped.
servers:
  - url: '{baseUrl}'
    variables:
      baseUrl:
        default: http://localhost:3000
security: []
paths:
  /api/v1/runs/{runId}:
    get:
      tags:
        - Runs
      summary: Get a run's current status, including its tool invocations
      parameters:
        - schema:
            type: string
            minLength: 1
          required: true
          name: runId
          in: path
      responses:
        '200':
          description: The run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRun'
        '401':
          description: Missing or invalid credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Not found (non-leaking — see above).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - ClerkBearer: []
components:
  schemas:
    AgentRun:
      type: object
      properties:
        id:
          type: string
        chatId:
          type: string
        status:
          type: string
          enum:
            - queued
            - running
            - waiting
            - completed
            - failed
            - cancelled
        userMessageId:
          type: string
        assistantMessageId:
          type:
            - string
            - 'null'
        lastStreamIndex:
          type: integer
        cancelRequestedAt:
          type:
            - string
            - 'null'
        requestedModel:
          type: string
        resolvedModel:
          type:
            - string
            - 'null'
        errorCode:
          type:
            - string
            - 'null'
        errorMessage:
          type:
            - string
            - 'null'
        createdAt:
          type: string
        updatedAt:
          type: string
        startedAt:
          type:
            - string
            - 'null'
        finishedAt:
          type:
            - string
            - 'null'
        toolInvocations:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              agentRunId:
                type: string
              turnIndex:
                type: integer
                minimum: 0
              callIndex:
                type: integer
                minimum: 0
              toolCallId:
                type: string
              name:
                type: string
              nodeType:
                type: string
              input:
                type: object
                additionalProperties: {}
              status:
                type: string
                enum:
                  - DISPATCHING
                  - QUEUED
                  - RUNNING
                  - COMPLETED
                  - FAILED
                  - CANCELLED
              creditEstimate:
                type:
                  - number
                  - 'null'
                minimum: 0
              creditUsed:
                type:
                  - number
                  - 'null'
                minimum: 0
              resultUrls:
                type:
                  - array
                  - 'null'
                items:
                  type: string
                  format: uri
              errorCode:
                type:
                  - string
                  - 'null'
              errorMessage:
                type:
                  - string
                  - 'null'
              startedAt:
                type:
                  - string
                  - 'null'
              finishedAt:
                type:
                  - string
                  - 'null'
              durationMs:
                type:
                  - integer
                  - 'null'
                minimum: 0
              createdAt:
                type: string
              updatedAt:
                type: string
            required:
              - id
              - agentRunId
              - turnIndex
              - callIndex
              - toolCallId
              - name
              - nodeType
              - input
              - status
              - creditEstimate
              - creditUsed
              - resultUrls
              - errorCode
              - errorMessage
              - startedAt
              - finishedAt
              - durationMs
              - createdAt
              - updatedAt
        totalCreditsUsed:
          type: number
          minimum: 0
        pendingWaitpoint:
          oneOf:
            - type: object
              properties:
                id:
                  type: string
                agentRunId:
                  type: string
                kind:
                  type: string
                  enum:
                    - CREDIT_APPROVAL
                status:
                  type: string
                  enum:
                    - PENDING
                    - COMPLETED
                    - EXPIRED
                requestPayload:
                  type: object
                  properties:
                    toolName:
                      type: string
                    estimatedCredits:
                      type: number
                      minimum: 0
                    threshold:
                      type: number
                      minimum: 0
                  required:
                    - toolName
                    - estimatedCredits
                    - threshold
                resolvedPayload:
                  type:
                    - object
                    - 'null'
                  properties:
                    approved:
                      type: boolean
                    respondedAt:
                      type: string
                  required:
                    - approved
                    - respondedAt
                expiresAt:
                  type: string
                resolvedAt:
                  type:
                    - string
                    - 'null'
              required:
                - id
                - agentRunId
                - kind
                - status
                - requestPayload
                - resolvedPayload
                - expiresAt
                - resolvedAt
            - type: object
              properties:
                id:
                  type: string
                agentRunId:
                  type: string
                kind:
                  type: string
                  enum:
                    - CLARIFICATION
                status:
                  type: string
                  enum:
                    - PENDING
                    - COMPLETED
                    - EXPIRED
                requestPayload:
                  type: object
                  properties:
                    question:
                      type: string
                    options:
                      type: array
                      items:
                        type: string
                  required:
                    - question
                resolvedPayload:
                  type:
                    - object
                    - 'null'
                  properties:
                    answer:
                      type: string
                    respondedAt:
                      type: string
                  required:
                    - answer
                    - respondedAt
                expiresAt:
                  type: string
                resolvedAt:
                  type:
                    - string
                    - 'null'
              required:
                - id
                - agentRunId
                - kind
                - status
                - requestPayload
                - resolvedPayload
                - expiresAt
                - resolvedAt
            - type: 'null'
      required:
        - id
        - chatId
        - status
        - userMessageId
        - assistantMessageId
        - lastStreamIndex
        - cancelRequestedAt
        - requestedModel
        - resolvedModel
        - errorCode
        - errorMessage
        - createdAt
        - updatedAt
        - startedAt
        - finishedAt
        - toolInvocations
        - totalCreditsUsed
        - pendingWaitpoint
    ApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details: {}
          required:
            - code
            - message
      required:
        - error
  securitySchemes:
    ClerkBearer:
      type: http
      scheme: bearer
      description: >-
        Clerk session token, `Authorization: Bearer <token>`. This documents the
        app's own internal auth as of S1-S6 — see S8-public-api-bonus.md for the
        fallback scope this doc covers, and the public API-key scheme's own page
        once the full scope ships.

````