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

# List conversations

`GET /v1/conversations`

## Request

- Base URL: `https://api.shardflux.dev`
- URL: `https://api.shardflux.dev/v1/conversations`
- Auth: HTTP bearer

Scope: `project_id`, else an API key’s project; a signed-in person without `project_id` lists every project they work in (`organization_id` narrows it to one organization).

## Query parameters

- `project_id` string, uuid
- `organization_id` string, uuid
- `state` 'working' | 'needs_you' | 'unresolved' | 'done' | 'archived'
- `parent_id` string
- `updated_after` string, date-time
- `limit` integer
- `cursor` string

## Response `200`

Default Response

- object
  - `data` Conversation[], required
    - `id` string, required
    - `project_id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `key` string, required
    - `name` string, required
    - `title` string, required
    - `summary` string, required
    - `harness` 'claude' | 'codex', required
    - `harness_session_id` string, nullable, required
    - `route` 'terminal' | 'acp' | 'codex-app' | 'codex-cloud' | 'claude-desktop' | 't3-ssh', required
    - `role` 'main' | 'fork' | 'spawn' | 'join', required
    - `join_mode` 'reviewer' | 'worker', nullable, required
    - `orchestrator_conversation_id` string, nullable
    - `orchestrator_input_id` string, nullable
    - `settled_reason` 'computer_suspended' | 'computer_failed', nullable: The computer suspended or failed while a native turn was active. Cleared by later live activity. Null or absent does not establish that a turn finished.
    - `parent_id` string, nullable, required
    - `root_id` string, required
    - `workspace_id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `worktree_path` string, required
    - `branch` string, required
    - `base_commit` string, required: The commit the conversation started from; empty for a home conversation.
    - `base_branch` string, nullable, required
    - `repo_remote` string, required
    - `home` boolean, required: A conversation on your machine’s home: no repository (`repo_remote`, `branch` and `base_commit` are empty). Its agent runs in `/home/user` on a computer from your machine environment and starts threads in the project’s repositories.
    - `state` 'working' | 'needs_you' | 'unresolved' | 'done' | 'archived' | 'deleted', required: `deleted` only on the one feed delivery of a deleted conversation.
    - `changes` object, required
      - `files` integer, required
      - `insertions` integer, required
      - `deletions` integer, required
      - `commits` integer, required
      - `uncommitted` boolean, required
    - `landed` object, nullable, required
      - `how` 'merged' | 'pushed' | 'pr' | 'kept' | 'discarded' | 'no_changes', required
      - `at` string, date-time, required: RFC 3339 UTC timestamp with Z.
      - `ref` string, required
    - `pending_move` object, nullable, required
      - `to` string, required
      - `requested_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `initial_input` object: Only a qualified computer guest receives its exact bound initial-input receipt metadata.
      - `protocol` 1, required
      - `input_id` string, required
      - `received` boolean, required
      - `recovery_blocked` boolean, required
      - `halted` boolean, required
      - `sha256` string, required
      - `bytes` integer, required
    - `brief` string, nullable, required
    - `last_activity_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `created_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `ended_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `model` string, nullable, required
    - `effort` string, nullable, required
    - `title_prefix` string, nullable: The marker the conversation’s Claude session title starts with; an empty string for none. Null: the default “☁ ”.
    - `started_by` object, nullable: The user who started the conversation: the signed-in user, or the user who created the API key that started it. A conversation a guest spawns, forks or joins carries its VM creator’s user. Null for conversations started before this was recorded and for a key without a known creator.
      - `user_id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `question` string, nullable: Why the conversation needs you: the agent’s question or the reason its turn stopped (“Codex reached its usage limit; try again at 4:40 AM.”), on one line of up to 500 characters. Set while `state` is `needs_you`; null otherwise, and for a permission prompt that asks no question.
    - `title_short` string, nullable, required: The agent’s own short name for the conversation (“CSV export for todo list”): Claude Code’s generated title or the Codex thread name, on one line. Null until the agent has named it; show `title` meanwhile.
    - `updated_at` string, date-time, required: When something this conversation shows last changed (state, titles, summary, changes, landing, question, activity). GET /v1/conversations?updated_after= filters on it.
    - `deleted_at` string, date-time, nullable: Set once the conversation was deleted: a feed delivers it this one time, with its content cleared; remove it. Lists leave it out and it reads 404.
    - `parent_deleted` boolean: Its parent conversation was deleted (`parent_id` reads 404).
    - `needs_you_reason` 'permission' | 'question' | 'sign_in' | 'turn_failed', nullable: Why the conversation needs you, while `state` is `needs_you`: `permission` (the agent asks to use a tool), `question` (the agent asks you something), `sign_in` (the agent’s account must sign in again) or `turn_failed` (its turn stopped, for example on a usage limit; `question` says why). Null otherwise.
    - `seen_at` string, date-time, nullable: When you last opened this conversation, on any of your devices (POST /v1/conversations/marks `seen`). A conversation you never opened reads the time your marks start from (no earlier than when you joined its organization). A result is new to you when the conversation finished after this time. Each person has their own. Present on GET /v1/conversations, GET /v1/conversations/{id}, GET /v1/conversations/feed and POST /v1/conversations/marks; absent on other answers, which do not read marks.
    - `dismissed_at` string, date-time, nullable: When you archived this conversation from your inbox, on any of your devices (POST /v1/conversations/marks `dismissed`); null when you have not, or restored it. Each person has their own. Present where `seen_at` is.
  - `next_cursor` string, nullable, required

## Other responses

- `4XX`: Default Response
- `5XX`: Default Response

---

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