---
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 roles: All, App

## 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).
    - `latest_run_id` string, required
    - `status` string, required — Agent run status. Values are QUEUED, RUNNING, SUCCEEDED, FAILED, or CANCELLED.
    - `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

---

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