---
title: "Wait for a conversation or child question/result"
method: POST
path: "/v1/conversations/{id}/wait"
tags: ["Conversations"]
---

# Wait for a conversation or child question/result

`POST /v1/conversations/{id}/wait`

## Request

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

## Path parameters

- `id` string, required

## Request body

- object
  - `until` string[], required
  - `timeout_seconds` integer
  - `turn_after` string, date-time: Also return (event `turn_ended`) when a turn of this conversation ends after this time, the agent no longer working.

## Response `200`

Default Response

- union
  - object
    - `timeout` true, required
  - object
    - `conversation` 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.
    - `event` object, required
      - `kind` union, required
        - 'working' | 'needs_you' | 'unresolved' | 'done' | 'archived'
        - 'turn_ended'
      - `reported_at` string, date-time: With `turn_ended`: when the turn ended (its first turn-end report arrived); pass it as the next `turn_after`.
      - `question` string
      - `result` object
        - `summary` string, required
        - `branch` string, required
        - `changes` object, required
          - `files` integer, required
          - `insertions` integer, required
          - `deletions` integer, required
          - `commits` integer, required
          - `uncommitted` boolean, 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)