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

# Retrieve an agent run

`GET /v1/runs/{id}`

Retrieves details of a specific agent run

## Path parameters

- `id` string, required

## Query parameters

- `include` string

## Headers

- `Authorization` string, required

## Response `200`

agent run found

- TypeAgentsRun — A single agent run execution within an agent thread.
  - `object` string, required — Object type identifier.
  - `id` string, uuid, required — Unique identifier for the agent run.
  - `created_at` string, date-time, required — Timestamp when the agent run record was created.
  - `updated_at` string, date-time, required — Timestamp when the agent run record was last updated.
  - `status` 'running' | 'completed' | 'error' | 'interrupted', required — Current lifecycle status of the agent run.
  - `thread_id` string, uuid — Identifier of the agent thread this run belongs to.
  - `agent` string — Agent type that produced this run (for example, `cip_orchestrator`).
  - `requester` TypeAgentsRunRequester — Principal that initiated the run. Populated with the authenticated user's identity when a session caller initiates the run, and with the account when an API key caller initiates the run. `null` for system-initiated runs.
    - `id` string, uuid, required — Identifier of the requesting user or account.
    - `name` string, required — Display name of the requester.
    - `email` string, email, nullable — Email address of the requester. Populated for user requesters and `null` for account requesters.
  - `started_at` string, date-time, nullable — Timestamp when the agent run started.
  - `ended_at` string, date-time, nullable — Timestamp when the agent run finished.
  - `output` TypeAgentsRunOutput — Artifact envelope produced by the agent. Non-null only when `status` is `completed`; `null` for `running`, `interrupted`, and `error` runs.
    - `artifacts` TypeAgentsArtifact[], required — Artifacts produced by the agent during this run.
      - `title` string, required — Human-readable title for the artifact.
      - `type` string, required — Artifact type identifier.
      - `confidence` string, nullable — Optional confidence label for artifact quality.
      - `summary` string, nullable — Optional summary of the artifact contents.
      - `sources` TypeAgentsSource[] — Source references used to produce the artifact.
        - `url` string, uri, required — Canonical source URL.
        - `source_name` string — Human-readable source name.
        - `source_tier` string — Source quality or trust tier.
        - `source_type` string — Source category.
  - `interrupts` TypeAgentsRunInterruptsItem[] — Pending interrupt requests awaiting input. Empty when the run is not interrupted. To resume a run, POST the interrupt's `id` along with the caller-supplied input to `POST /v1/runs/{id}/resume`.
    - `id` string, required — Identifier of the interrupt request.
    - `value` object, required — Agent-defined interrupt payload. Shape varies by agent, but typically carries `agent` (the sub-agent that raised the interrupt), `label` (human-readable prompt), and `artifacts` (proposed changes awaiting review). The orchestrator agent (`cip_orchestrator`) wraps sub-agent interrupts under a `proposals` array with `type: combined_proposal`.
    - `agent` string, nullable — Agent type that raised the interrupt. Lifted from `value.agent` and surfaced at the top level for convenience; omitted when the interrupt did not declare an agent.
  - `steps` TypeAgentsStep[] — Top-level execution steps for this run. Opt-in: pass `?include=steps` on `GET /v1/runs/{id}` (or `POST /v1/runs/{id}/resume`) to populate this field. Omitted by default to avoid the cost of fetching step state from the underlying execution backend.
    - `id` string, uuid, required — Unique identifier for the step.
    - `run_id` string, uuid, required — Identifier of the agent run that produced the step.
    - `agent` string — Agent identifier that generated this step.
    - `type` 'activity' | 'output' | 'interrupt' | 'error', required — Category of step output.
    - `name` string, required — Internal step name.
    - `label` string, required — Human-readable step label.
    - `parent_step_id` string, uuid, nullable — Parent step identifier for nested steps.
    - `status` 'running' | 'completed' | 'error', required — Current execution status for the step.
    - `started_at` string, date-time, required — Timestamp when the step started.
    - `completed_at` string, date-time, nullable — Timestamp when the step completed.
    - `steps` TypeAgentsStep[] — Nested child steps.
    - `result` TypeAgentsStepResult — Structured result payload for the step.
      - `resolution` 'auto_approve' | 'skip' — How the interrupt was resolved. Present only on completed interrupt steps when an interrupt policy auto-approved or skipped the interrupt. Absent for manual resolutions.
    - `artifacts` TypeAgentsArtifact[] — Artifacts produced by the step.
      - `title` string, required — Human-readable title for the artifact.
      - `type` string, required — Artifact type identifier.
      - `confidence` string, nullable — Optional confidence label for artifact quality.
      - `summary` string, nullable — Optional summary of the artifact contents.
      - `sources` TypeAgentsSource[] — Source references used to produce the artifact.
        - `url` string, uri, required — Canonical source URL.
        - `source_name` string — Human-readable source name.
        - `source_tier` string — Source quality or trust tier.
        - `source_type` string — Source category.

## Other responses

- `404` — agent run not found

---

[API](https://skmtc.net/middesk/apis/middesk-api.md) · [All operations](https://skmtc.net/middesk/apis/middesk-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/middesk/middesk-api/revisions/f849b82a42e1/schema)