---
title: "Get agent run"
method: GET
path: "/agent/runs/{run_id}"
tags: ["agent"]
---

# Get agent run

`GET /agent/runs/{run_id}`

Get the current state of an asynchronous agent run.

Required scope: \`inference:run\`

## Path parameters

- `run_id` string, required

## Query parameters

- `principal_id` string

## Response `200`

Agent run state

- AgentRun
  - `run_id` string, required
  - `thread_id` string, required
  - `workflow_type` string, required
  - `provider` 'ANTHROPIC_DIRECT' | 'BEDROCK' | 'OPENAI' | 'VERTEX_AI', required
  - `execution_mode` 'LOCAL' | 'AGENTCORE', required
  - `status` 'QUEUED' | 'RUNNING' | 'CANCELLING' | 'SUCCEEDED' | 'FAILED' | 'CANCELLED', required — Agent run lifecycle state.
  - `runtime_arn` string, nullable
  - `mcp_session_id` string, nullable
  - `trace_id` string, nullable
  - `idempotency_key` string, nullable
  - `created_at` string, date-time, nullable
  - `started_at` string, date-time, nullable
  - `finished_at` string, date-time, nullable
  - `input` object, nullable — Server-enriched agent input used to reconstruct the thread transcript.
  - `parent_run_id` string, nullable — Run this run branched from within the thread (null for the thread root).
  - `result` object, nullable
  - `error` object, nullable

## Other responses

- `401` — Unauthorized
- `404` — Not Found

## Changes

> 65 revisions in range; 12 not diffed.

- **2026-07-10** `05d4c3bc46f2` — 3 info
  - added the new optional `query` request parameter `principal_id`
  - added the optional property `input` to the response with the `200` status
  - added the optional property `parent_run_id` to the response with the `200` status
- **2026-04-30** `7c778f65dca5` — 1 warning
  - added the new `VERTEX_AI` enum value to the `provider` response property for the response status `200`
- **2026-03-27** `d5bad61b1542` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/qlonolink/apis/qaip-apis/changes/agent/runs/:run_id/get.md)

---

[API](https://skmtc.dev/qlonolink/apis/qaip-apis.md) · [All operations](https://skmtc.dev/qlonolink/apis/qaip-apis/llms.txt) · [OpenAPI document](https://skmtc.dev/qlonolink/apis/qaip-apis/revisions/430440bbcc56?raw)