agent

Get agent run

Changed on

Get the current state of an asynchronous agent run.

Required scope: `inference:run`

get/agent/runs/{run_id}

Request

  • Base URL
    https://developer.qaip.com/api/v1
  • URL
    https://developer.qaip.com/api/v1/agent/runs/{run_id}
  • Auth
    API key in header x-api-key

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。

request_idstring nullable

Correlation ID of the first request that created this run. For HTTP creation it matches that request's X-Request-ID. Idempotent retries and later reads preserve this value even though their own HTTP response headers carry different request IDs. Runs created before correlation recording was introduced return null. Direct service callers without an HTTP request receive a generated correlation ID.

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

  • 2489c6f1a9d8Revision changes
    • info

      added the non-success response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property to the response with the status

  • b065e544fec5Revision changes
    • warning

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

    • info

      the response's property pattern ^[0-9a-f]{32}$ was added for the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status