--- title: "Cancel Chat Turn" method: POST path: "/v1/chat/{chat_id}/turns/{turn_id}/cancel" tags: ["chat"] --- # Cancel Chat Turn `POST /v1/chat/{chat_id}/turns/{turn_id}/cancel` ## Request - Base URL: `https://api.happenstance.ai` (the document declares no server; this is the origin it was published from) - URL: `https://api.happenstance.ai/v1/chat/{chat_id}/turns/{turn_id}/cancel` - Auth: HTTP bearer Stop a running turn, as the Stop button in the app does. Chat keeps what it wrote, its searches stop, and the turn ends cancelled, charged for the work done. A finished turn is returned as it is. `latest` stops whatever the chat is working on. ## Path parameters - `chat_id` string, required - `turn_id` string, required: A turn ID from POST /v1/chat or /messages, or `latest` for the chat's newest turn ## Response `200` Successful Response - ChatTurnV1: Response from GET /v1/chat/{chat_id}/turns/{turn_id}: a message and Chat's work on it. - `id` string, required: The turn's id - `chat_id` string, required: The chat's id - `status` 'queued' | 'running' | 'completed' | 'failed' | 'cancelled', required: queued (not started), running, completed, failed (not charged) or cancelled - `stop_reason` 'done' | 'needs_input' | 'stopped' | 'error', nullable: Why a finished turn ended: done; needs_input (Chat asked questions and waits for the answers, see reply.questions); stopped (cancelled); error. Null while running. - `started_by` 'message' | 'schedule': message: a message or answers started the turn. schedule: one of the chat's scheduled tasks ran, and nobody sent a message (only a chat started in the app has scheduled tasks). - `message` string, required: The message that started the turn, or for a scheduled run the task's instruction - `messages` string[], required: Every message in the turn: the first started it, any later one was sent while it ran and joined it. A scheduled run's turn has none. - `reply` ChatReplyV1, required - `markdown` string, required: Chat's reply, as markdown with absolute links: its latest message, and every message with people or drafts. People appear as list items and drafts as quoted blocks; read them as data with /people and /drafts. Grows while the turn runs. - `updates` string[]: Chat's earlier notes in this turn that hold no people or drafts, such as 'searching now' or a reply to a message that joined the turn. Not part of the answer. - `people_count` integer, required: People shown in this turn - `people_new_count` integer, required: People shown in this turn who weren't shown in an earlier one - `drafts_count` integer, required: Message drafts written in this turn - `searches` ChatSearchV1[]: People searches run in this turn - `search_id` string, required: The search's id, for GET /v1/search/{search_id} - `page_id` string, nullable: The find-more page of that search, when this was one - `turn_id` string, nullable: The turn that ran it - `query` string, nullable: What Chat searched for - `status` 'running' | 'completed' | 'failed' | 'stopped', required: The search's status - `results_count` integer, nullable: How many people the search returned, once completed - `suggested_followup` string, nullable: A next message Chat suggests, in the user's voice, when it offers one - `questions` ChatQuestionV1[]: The last questions Chat asked the user in this turn. When the turn ends with stop_reason needs_input, Chat waits for their answers: send them with POST /v1/chat/{chat_id}/messages (answers, or a message). Answer from what you know of the user's goal; ask the user when you don't know. - `index` integer, required: Its index, as answers[].question_index takes it - `header` string, required: A one to three word label - `question` string, required - `options` ChatQuestionOptionV1[], required - `label` string, required: The option, as answers[].selected takes it - `description` string, required: What choosing it means - `multi_select` boolean, required: Whether more than one option may be chosen - `usage` ChatTurnUsageV1, required - `credits_charged` number, nullable: Credits charged for the turn, to two decimal places. Null while the turn runs, for a few seconds after it finishes until billing records the charge, and for chats started in the Happenstance app. - `searches` integer, required: People searches Chat ran - `web_searches` integer, required: Web searches and page reads Chat ran - `model_calls` integer, required: Model calls Chat made - `people_reviewed` integer, required: People the searches returned for Chat to review - `scope` ChatScopeV1: Whose networks the turn's searches covered (the union across its searches). - `my_connections` boolean, required: The user's own connections - `friends_connections` boolean, required: The user's friends' connections - `all_groups` boolean, required: Every group the user is in - `group_ids` string[]: Specific groups searched, when not all - `created_at` string, required: When the turn started (ISO 8601) - `completed_at` string, nullable: When the turn finished (ISO 8601) - `last_activity_at` string, nullable: When Chat last made progress on the turn (a reply, a search starting or finishing). A running turn with no progress for several minutes is stuck or slow and can be cancelled. - `elapsed_seconds` integer, required: Seconds since the turn started, or how long it took once finished - `next_turn_id` string, nullable: The chat's next turn, once one was started ## Other responses - `400`: Bad Request - `401`: Unauthorized - `402`: Payment Required - `403`: Forbidden - `404`: Not Found - `410`: Gone - `422`: Validation Error - `500`: Internal Server Error - `503`: Service Unavailable ## Changes - **2026-10-23** `c8149ed29b44`: 1 info - endpoint added [Operation history](https://skmtc.dev/happenstance/apis/happenstance-api/changes/v1/chat/:chat_id/turns/:turn_id/cancel/post.md) --- [API](https://skmtc.dev/happenstance/apis/happenstance-api.md) - [All operations](https://skmtc.dev/happenstance/apis/happenstance-api/llms.txt) - [OpenAPI document](https://skmtc.dev/happenstance/apis/happenstance-api/revisions/0b6ee3927db3?raw)