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

# Get agent run

`GET /v1/admin/agent-runs/{id}`

## Request

- Base URL: `https://api.patricia.app` (the document declares no server; this is the origin it was published from)
- URL: `https://api.patricia.app/v1/admin/agent-runs/{id}`
- Auth: HTTP bearer

Retrieve a single agent run by ID.

## Path parameters

- `id` string, uuid, required

## Response `200`

The requested agent run.

- ModelsRunAgentRunFullValidator: Response shape for the read routes (GET detail / list). Runs are read-only to clients. ``credits`` is the customer-facing consumption for the run: the metered ``cost_micro_usd`` COGS converted to whole credits (half-up, the same ledger conversion), so a run detail can show credits without the dashboard doing token→cost math. ``input_tokens`` / ``output_tokens`` / ``cost_micro_usd`` remain on the payload for internal + admin callers (audit precision) but are never rendered on a normal-user screen (per pricing-v2 §8a). Frozen credits travel through private state, leaving snapshot columns absent from queryable fields. ``checkpoint`` is deliberately NOT here: it is the run's full saved loop state (message history, tool schemas, the pending tool-call vector with raw arguments), i.e. runtime-internal data, exactly like ``pending_snapshot`` and ``sandbox_seconds_used``. Exposing it handed every ``runs:read`` holder the raw pending args the approval surfaces redact per caller. The run timeline is served by the nested messages / tool-calls / approval reads instead. ``message_excerpt`` is the first line of the opening message of a DIRECTED run (mention/DM/message), so a run list can say what was asked rather than only how it arrived. It is not a column on this table — the text lives in the run's first user ``Message`` row — so it is attached by the LIST route alone (``routers.runs._attach_message_excerpts``) and is absent from the detail response, whose caller reads the transcript itself. Like ``credits`` it is derived, so it can never be named in ``fields=``. A scheduled run's instruction is NOT carried here: that text is ``trigger_context.prompt``, which stays approver-gated.
  - `id` string, uuid, required
  - `tenant_id` string, uuid, required
  - `conversation_id` string, uuid, nullable
  - `actor_id` string, uuid, nullable
  - `trigger_code` 'mention' | 'dm' | 'message' | 'proactive' | 'cron' | 'event' | 'heartbeat' | 'discovery' | 'onboarding' | 'manual' | 'spawn', required
  - `trigger_context` RunTriggerContext: Curated provenance for the request card at the start of a run timeline.
    - `sender` string, nullable
    - `attachments` RunTriggerAttachment[]
      - `name` string, nullable
      - `mime_type` string, nullable
      - `size_bytes` integer, nullable
      - `external_id` string, nullable
    - `schedule_name` string, nullable
    - `prompt` string, nullable
    - `description` string, nullable
    - `cron_job_id` string, nullable
    - `built_in_template_key` string, nullable
    - `one_shot` boolean
    - `post_every_run` boolean
    - `mcp_direct_tool_ref` string, nullable
    - `admin_console_operator` boolean
    - `loop_id` string, nullable
    - `loop_final` boolean
    - `task_test_run` boolean
    - `task_summary` string, nullable
    - `prompt_digest` string, nullable
    - `admission` RunTriggerAdmission: Why a chat run's message was admitted as addressed to Patricia (``core.chat.types.AdmissionBasis``).
      - `basis` string, required
      - `generation` integer, required
      - `admitted_at` string, required
      - `classifier_source` string, nullable
    - `answered_ask_id` string, nullable
  - `message_excerpt` string, nullable
  - `status_code` 'queued' | 'running' | 'waiting_approval' | 'suspended' | 'completed' | 'failed' | 'cancelled' | 'denied_autonomous', required
  - `truncated` boolean
  - `no_result` boolean
  - `silent` boolean
  - `model` string, required
  - `input_tokens` integer, required
  - `output_tokens` integer, required
  - `cache_read_tokens` integer, required
  - `cache_write_tokens` integer, required
  - `cost_micro_usd` integer, required
  - `budget_micro_usd` integer, nullable
  - `duration_ms` integer, nullable
  - `error` string, nullable
  - `started_at` string, date-time, nullable
  - `completed_at` string, date-time, nullable
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `credits` integer, required: Credits fixed when the run finished, with live-rate conversion for runs without a snapshot.

## Other responses

- `401`: Unauthorized
- `403`: Permission denied (PERMISSION_DENIED) or email not verified (EMAIL_NOT_VERIFIED)
- `404`: Not found
- `422`: Validation error

---

[API](https://skmtc.dev/patricia/apis/patricia-api.md) · [All operations](https://skmtc.dev/patricia/apis/patricia-api/llms.txt) · [OpenAPI document](https://skmtc.dev/patricia/apis/patricia-api/revisions/0dfb44495ea1?raw)