---
title: "POST /api/metabot/conversations/{id}/fork"
method: POST
path: "/api/metabot/conversations/{id}/fork"
tags: ["/api/metabot/conversations"]
---

# POST /api/metabot/conversations/{id}/fork

`POST /api/metabot/conversations/{id}/fork`

## Request

- Base URL: `` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/metabot/conversations/{id}/fork`
- Auth: API key in header `X-API-Key`

Fork a conversation at an assistant message, returning a brand-new conversation
  that copies the thread from the start up to and including that message.

  Only the conversation's originator may fork it, for now. `message_id` is the
  `external_id` of the message to fork at, which must be a live, finished,
  non-errored assistant message. The clone gets fresh conversation/message ids,
  fresh timestamps, the current user as owner, and zeroed token usage so the fork
  does not double-count tokens in the analytics views.

## Path parameters

- `id` string, required

## Request body

- object
  - `message_id` string, required: value must be a valid UUID.

## Response `2XX`

Successful response

- object
  - `context_window_tokens` integer
  - `conversation_id` string, required: value must be a valid UUID.
  - `created_at` string, date-time, required: value must be a valid date/time/datetime
  - `forked_from_conversation_id` string, nullable, required: value must be a valid UUID.
  - `messages` MetabaseMetabotSchemaClientMessage[], required
    - `contextTokens` integer
    - `externalId` string
    - `id` string, required
    - `parts` MetabaseMetabotSchemaClientMessagePart[], required
      - union: One part of a persisted message: its a text, tool call, or data blob.
        - object
          - `id` string, required
          - `message` string, required
          - `role` 'user' | 'agent', required
          - `type` 'text', required
        - object
          - `args` string, nullable, required
          - `id` string, required
          - `is_error` boolean
          - `name` string, required
          - `result` string, nullable
          - `role` 'agent', required
          - `status` 'started' | 'ended', required
          - `type` 'tool_call', required
        - object
          - `id` string, required
          - `part` object, required
            - `data` unknown, required
            - `type` string, required
          - `role` 'agent', required
          - `type` 'data_part', required
    - `role` 'user' | 'agent', required
    - `status` union, required: Where a message's turn got to.
      - object
        - `type` 'done', required
      - object
        - `type` 'aborted', required
      - object
        - `type` 'in_progress', required
      - object
        - `contextWindowFull` boolean
        - `finishReason` 'length' | 'content-filter' | 'tool-calls', required
        - `type` 'incomplete', required
      - object
        - `error` union, required
          - string
          - object
            - `data` unknown
            - `message` string, nullable
            - `type` string
        - `type` 'errored', required
  - `saved_entities` object[], required
    - `card_id` integer, required: value must be an integer greater than zero.
    - `chart_id` string, nullable, required
  - `state` MetabaseMetabotSchemaState
    - `chart-configs` object
    - `charts` object
    - `client-ids` union
      - MetabaseMetabotSchemaStateMapKey[]
      - MetabaseMetabotSchemaStateMapKey[]
    - `link-registry` object
    - `queries` object
    - `todos` MetabaseMetabotSchemaTodo[]
      - `content` string, nullable
      - `id` string, required
      - `priority` 'high' | 'medium' | 'low', nullable
      - `status` 'pending' | 'in_progress' | 'completed' | 'cancelled', nullable
    - `transforms` object
  - `title` string, nullable, required
  - `user_id` integer, nullable, required: value must be an integer greater than zero.

## Other responses

- `4XX`: Client error response
- `5XX`: Server error response

## Changes

- **2026-11-04** `2e178f5a7934`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/metabase/apis/metabase-api/changes/api/metabot/conversations/:id/fork/post.md)

---

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