---
title: "List Runs"
method: GET
path: "/api/agents/runs"
tags: ["agents"]
---

# List Runs

`GET /api/agents/runs`

## Request

- Base URL: `https://api.advisorppc.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.advisorppc.com/api/agents/runs`
- Auth: HTTP bearer

Runs + their questions, shaped for the task tab, with chip counts.

``filter`` scopes the returned runs; ``limit`` bounds them (newest first,
default 50, cap 200) so a 15s poll never materializes an unbounded history;
``counts`` is always computed across ALL this tenant's runs (SQL aggregate)
so the chip badges stay correct regardless of the filter or limit.

## Query parameters

- `filter` 'all' | 'needs_input' | 'ready' | 'working'
- `limit` integer

## Headers

- `X-Tenant-Id` integer, nullable

## Response `200`

Successful Response

- RunListOut: The task-tab payload: the (filtered, limited) runs plus the per-chip counts computed across ALL of the tenant's runs.
  - `runs` RunOut[], required
    - `id` integer, required
    - `instance_id` integer, required
    - `definition_key` string, required
    - `agent_name` string, required
    - `display_name` string, required
    - `status` string, required
    - `summary` string, nullable, required
    - `proposal` object, nullable, required
    - `error` string, nullable, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `questions` QuestionOut[], required
      - `id` integer, required
      - `question` string, required
      - `options` unknown[], nullable, required
        - unknown
      - `status` string, required
      - `answer` string, nullable, required
      - `created_at` string, date-time, required
      - `answered_at` string, date-time, nullable, required
  - `counts` object, required

## Other responses

- `422`: Validation Error

---

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