Sign in
agent

Get agent run

Get the current state of an asynchronous agent run.

Required scope: `inference:run`

get/agent/runs/{run_id}

Path parameters

run_idstring required

Query parameters

principal_idstring

Scope by principal. If omitted, only a run with no principal (principal_id is null) is addressed; a run whose principal differs yields 404.

Response

Agent run state

run_idstring required
thread_idstring required
workflow_typestring 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_arnstring nullable
mcp_session_idstring nullable
trace_idstring nullable

保存済みW3C trace contextから導出したlowercase OpenTelemetry trace ID。移行前の行はnull。

idempotency_keystring nullable
created_atstring date-time nullable
started_atstring date-time nullable
finished_atstring date-time nullable
inputobject nullable

Server-enriched agent input used to reconstruct the thread transcript.

parent_run_idstring nullable

Run this run branched from within the thread (null for the thread root).

input_history_mode'legacy_full' | 'delta_v1' required

How the request supplied conversation history for this run.

context_start_run_idstring nullable required

Oldest run included in the reconstructed rolling context, or null when none was needed.

context_truncatedboolean required

Whether older turns were omitted to stay within the server context budget.

resultobject nullable
errorobject nullable

Example response

{
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}

Changes

Changed in 3 of the 71 revisions of this API.14

  • 05d4c3bc46f23See the full diff
    • ○

      added the new optional query request parameter principal_id

      new-optional-request-parameter

    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      added the optional property to the response with the status

      response-optional-property-added

  • 7c778f65dca51See the full diff
    • ●

      added the new VERTEX_AI enum value to the response property for the response status

      response-property-enum-value-added

  • d5bad61b15421See the full diff
    • ○

      endpoint added

      endpoint-added

Of the 71 revisions, 18 have no diff computed.