---
title: "List agent runs"
method: GET
path: "/v1/runs"
tags: ["runs"]
---

# List agent runs

`GET /v1/runs`

Returns a paginated list of agent runs

## Query parameters

- `page` integer
- `per_page` integer

## Headers

- `Authorization` string, required

## Response `200`

agent runs list with pagination

- TypeRunsListAgentRunsResponse
  - `data` TypeAgentsRun[]
    - `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.
  - `object` string, required
  - `has_more` boolean, required
  - `total_count` integer

---

[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)