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

# Get agent run

> <p> Get the current state of an asynchronous agent run. </p> <p> Required scope: `inference:run` </p>




## OpenAPI

````yaml https://app.stainless.com/api/spec/documented/qaip/openapi.documented.yml get /agent/runs/{run_id}
openapi: 3.0.3
info:
  title: QAIP APIs
  version: 1.0.0
servers:
  - url: https://developer.qaip.com/api/v1
    description: API base path
security:
  - ApiKeyAuth: []
tags:
  - name: completions
    description: Generate completions
  - name: search
    description: Search content
  - name: query
    description: Query materialized external tables
  - name: extract
    description: Data extraction using LLM
  - name: tags
    description: List available tags
  - name: agent
    description: (Experimental) Agent operations
  - name: tag-source-groups
    description: Tag and source group associations
  - name: source-groups
    description: Source group (job) management and metadata
  - name: sources
    description: Sources management and metadata
  - name: local-file-groups
    description: Local file group management
  - name: secrets
    description: Secret management
  - name: google-drives
    description: Google Drive data source management
  - name: google-drive-settings
    description: Google Drive data source setting management
  - name: crawls
    description: Web crawl data source management
  - name: crawl-settings
    description: Web crawl setting management
  - name: githubs
    description: GitHub data source management
  - name: github-settings
    description: GitHub data source setting management
  - name: notions
    description: Notion data source management
  - name: notion-settings
    description: Notion data source setting management
  - name: authz-subject-attributes
    description: >-
      Authorization subject attribute management (requires the `authz:grant`
      scope)
  - name: redaction-policies
    description: >-
      Tenant redaction policy management (requires the `policy:redaction:manage`
      scope)
  - name: api-keys
    description: API key issuance (requires the `apikeys:issue` scope)
paths:
  /agent/runs/{run_id}:
    get:
      tags:
        - agent
      summary: Get agent run
      description: >
        <p> Get the current state of an asynchronous agent run. </p> <p>
        Required scope: `inference:run` </p>
      operationId: getAgentRun
      parameters:
        - name: run_id
          in: path
          required: true
          schema:
            type: string
        - name: principal_id
          in: query
          required: false
          description: >
            Scope by principal. If omitted, only a run with no principal
            (principal_id is null) is addressed; a run whose principal differs
            yields 404.
          schema:
            type: string
      responses:
        '200':
          description: Agent run state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRun'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: Python
          source: |-
            import os
            from qaip import Qaip

            client = Qaip(
                api_key=os.environ.get("QAIP_API_KEY"),  # This is the default and can be omitted
            )
            agent_run = client.agent.retrieve_run(
                run_id="run_id",
            )
            print(agent_run.context_start_run_id)
components:
  schemas:
    AgentRun:
      type: object
      required:
        - run_id
        - thread_id
        - workflow_type
        - provider
        - execution_mode
        - status
        - input_history_mode
        - context_start_run_id
        - context_truncated
      properties:
        run_id:
          type: string
        thread_id:
          type: string
        workflow_type:
          type: string
        provider:
          $ref: '#/components/schemas/AgentProvider'
        execution_mode:
          $ref: '#/components/schemas/AgentExecutionMode'
        status:
          $ref: '#/components/schemas/AgentRunStatus'
        runtime_arn:
          type: string
          nullable: true
        mcp_session_id:
          type: string
          nullable: true
        trace_id:
          type: string
          nullable: true
          pattern: ^[0-9a-f]{32}$
          description: >-
            保存済みW3C trace contextから導出したlowercase OpenTelemetry trace
            ID。移行前の行はnull。
          example: 4bf92f3577b34da6a3ce929d0e0e4736
        idempotency_key:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
          nullable: true
        started_at:
          type: string
          format: date-time
          nullable: true
        finished_at:
          type: string
          format: date-time
          nullable: true
        input:
          type: object
          additionalProperties: true
          nullable: true
          description: >-
            Server-enriched agent input used to reconstruct the thread
            transcript.
        parent_run_id:
          type: string
          nullable: true
          description: >-
            Run this run branched from within the thread (null for the thread
            root).
        input_history_mode:
          $ref: '#/components/schemas/AgentInputHistoryMode'
        context_start_run_id:
          type: string
          nullable: true
          description: >-
            Oldest run included in the reconstructed rolling context, or null
            when none was needed.
        context_truncated:
          type: boolean
          description: >-
            Whether older turns were omitted to stay within the server context
            budget.
        result:
          type: object
          additionalProperties: true
          nullable: true
        error:
          type: object
          additionalProperties: true
          nullable: true
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
          properties:
            message:
              type: string
              description: Human-readable error message
            type:
              type: string
              description: Machine-readable error code
    AgentProvider:
      type: string
      enum:
        - ANTHROPIC_DIRECT
        - BEDROCK
        - OPENAI
        - VERTEX_AI
    AgentExecutionMode:
      type: string
      enum:
        - LOCAL
        - AGENTCORE
    AgentRunStatus:
      type: string
      description: Agent run lifecycle state.
      enum:
        - QUEUED
        - RUNNING
        - CANCELLING
        - SUCCEEDED
        - FAILED
        - CANCELLED
    AgentInputHistoryMode:
      type: string
      description: How the request supplied conversation history for this run.
      enum:
        - legacy_full
        - delta_v1
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication

````