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

# List threads

`GET /v1/threads`

List captain threads for a project.

## Query parameters

- `limit` integer
- `cursor` string
- `projectId` string, required
- `status` 'active' | 'idle' | 'archived'
- `prNumber` integer
- `branch` string
- `slackThreadTs` string
- `authorId` string — Filter to threads created by this Capy user ID. Mutually exclusive with authorEmail.
- `authorEmail` string, email — Filter to threads created by the organization member with this email address. Returns an empty page if the email does not match an organization member. Mutually exclusive with authorId.
- `participantId` string — Filter to threads this Capy user ID authored or participated in. Mutually exclusive with participantEmail.
- `participantEmail` string, email — Filter to threads the organization member with this email address authored or participated in. Returns an empty page if the email does not match an organization member. Mutually exclusive with participantId.
- `origin` 'web' | 'slack' | 'api' | 'linear' | 'automation' | 'github' — Filter by thread origin source.
- `prState` 'open' | 'merged' | 'closed' | 'none' — Filter by the thread's rolled-up pull request state. Combines with prNumber and branch.
- `tag` string — Filter to threads with this tag name (lowercase).
- `slackChannelId` string — Filter to threads linked to this Slack channel ID (e.g. C0123456789). Combines with slackThreadTs.
- `q` string — Free-text search across thread titles and content.

## Response `200`

Success

- ListThreadsResponse
  - `items` ThreadListItem[], required
    - `id` string, required
    - `projectId` string, required
    - `title` string, nullable, required
    - `status` 'active' | 'idle' | 'archived', required — Coarse Captain run-loop status retained for compatibility. Prefer runState/waitingOn/blockedOn for completion and waiting UX.
    - `runState` 'running' | 'stopping' | 'queued' | 'waiting' | 'blocked' | 'ready' | 'archived', required — Full computed execution state for the agent thread.
    - `waitingOn` string[], required — Async system dependencies expected to continue without user action.
    - `blockedOn` string[], required — User/integration gates required before progress can continue.
    - `pendingWakeups` integer, required — Pending append-and-resume notifications waiting to be processed.
    - `tasks` object[], required
      - `id` string, required
      - `threadIndex` integer, nullable, required
      - `identifier` string, required
      - `title` string, required
      - `status` 'backlog' | 'queued' | 'in_progress' | 'needs_review' | 'completed' | 'error' | 'archived', required
    - `participants` object[], required
      - `userId` string, required
      - `userType` 'human' | 'service_user', required
      - `firstParticipatedAt` string, required
      - `lastParticipatedAt` string, required
    - `pullRequests` object[], required
      - `number` integer, required
      - `url` string, required
      - `repoFullName` string, required
      - `state` string, required
      - `headRef` string, required
      - `baseRef` string, required
      - `draft` boolean, required
    - `slackThreads` object[], required
      - `teamId` string, required
      - `channelId` string, required
      - `threadTs` string, required
      - `url` string, required
    - `tags` object[], required
      - `name` string, required
      - `color` 'default' | 'primary' | 'success' | 'warning' | 'destructive' | 'blue' | 'purple' | 'pink' | 'orange' | 'lime', required
    - `createdAt` string, required
    - `updatedAt` string, required
  - `nextCursor` string, nullable, required
  - `hasMore` boolean, required

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not found
- `422` — Validation error
- `500` — Internal error

---

[API](https://skmtc.dev/capy/apis/capy-api.md) · [All operations](https://skmtc.dev/capy/apis/capy-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/capy/capy-api/revisions/c9ea28cb32b6/schema)