---
title: "A conversation's latest run"
method: GET
path: "/v1/agent/run"
tags: ["Agent"]
---

# A conversation's latest run

`GET /v1/agent/run`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/agent/run`
- Auth: HTTP bearer

Reports the conversation's latest run: live (`running`,
`waiting-approval`) or ended (`completed`, `failed`,
`cancelled`, `interrupted`). A live run lists the call ids still
answerable over `POST /v1/agent/approve`, and `lastEventId` is a replay cursor
for `GET /v1/agent/stream`. A conversation that is only on disk is
answered from its record without being loaded (`resident: false`); a
run it recorded as still running was cut off by a ToolPiper that
stopped mid-turn and reports `interrupted`.

## Query parameters

- `session` string, required

## Response `200`

The conversation's run status

- object
  - `sessionId` string, required
  - `resident` boolean, required: The conversation is held in memory
  - `lastEventId` integer: The frame ring's head id; absent when not resident
  - `run` object: Absent when the conversation has not run a turn under a build that records runs
    - `runId` string, required
    - `turn` integer, required: 1-based turn index this run drives
    - `state` 'running' | 'waiting-approval' | 'completed' | 'failed' | 'cancelled' | 'interrupted', required
    - `reason` 'completed' | 'empty-response' | 'max-iterations' | 'budget-exhausted' | 'cancelled' | 'failed': The terminal `turn-ended` frame's reason; absent while live and for `interrupted`
    - `error` string: The failure's user-facing message; present only when `state` is `failed`
    - `background` boolean, required
    - `startedAt` string, date-time, required
    - `endedAt` string, date-time: Absent while live and for `interrupted`
    - `pendingApprovals` string[], required

## Other responses

- `400`: Missing or malformed `session`
- `404`: No conversation with this id, in memory or on disk

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)