---
title: "List agent conversation threads"
method: GET
path: "/agent/threads"
tags: ["agent"]
---

# List agent conversation threads

`GET /agent/threads`

List the caller's agent conversations grouped by thread (most recently active first). Restore a thread's messages via the run events endpoints.

Required scope: \`inference:run\`

## Query parameters

- `limit` integer
- `offset` integer
- `principal_id` string
- `all_principals` boolean

## Response `200`

Agent thread list

- AgentThreadListResponse
  - `threads` AgentThread[], required
    - `thread_id` string, required
    - `principal_id` string, nullable — Authorization principal this thread belongs to (null if not set).
    - `agent_id` string, uuid, nullable, required — Agent that owns the thread. Legacy rows may return null.
    - `current_run_id` string, nullable, required — Authoritative continuation cursor for `delta_v1`. Send this value as `baseRunId`; legacy rows that have not been classified may return null.
    - `latest_run_id` string, required — Most recently created run; not an authoritative continuation cursor.
    - `status` 'QUEUED' | 'RUNNING' | 'CANCELLING' | 'SUCCEEDED' | 'FAILED' | 'CANCELLED', required — Agent run lifecycle state.
    - `title` string, nullable
    - `run_count` integer
    - `updated_at` string, date-time

## Other responses

- `400` — Bad Request (e.g. principal_id combined with all_principals=true)
- `401` — Unauthorized

## Changes

> 71 revisions in range; 18 not diffed.

- **2026-07-10** `05d4c3bc46f2` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/qlonolink/apis/qaip-apis/changes/agent/threads/get.md)

---

[API](https://skmtc.dev/qlonolink/apis/qaip-apis.md) · [All operations](https://skmtc.dev/qlonolink/apis/qaip-apis/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/qlonolink/qaip-apis/revisions/61dc40676905/schema)