---
title: "Retrieve a chat completion"
method: GET
path: "/v1/chat/completions/{completion_id}"
tags: ["chat"]
---

# Retrieve a chat completion

`GET /v1/chat/completions/{completion_id}`

Retrieve a previously stored chat completion by ID.

## Path parameters

- `completion_id` string, required — ID of the chat completion

## Query parameters

- `include` string[], nullable — Extra fields to include, e.g. store_search_call.results, store_grep_call.results, store_list_chunks_call.results or transcript; unsupported values are ignored

## Response `200`

The stored chat completion

- ChatCompletion — A chat completion object, as returned by the API and persisted for retrieval.
  - `id` string, required
  - `object` 'chat.completion'
  - `created` integer, required
  - `model` string, required
  - `choices` ChatCompletionChoice[], required
    - `index` integer
    - `message` ChatCompletionMessage, required — The assistant message of one completion choice.
      - `role` 'assistant'
      - `content` string, nullable
      - `refusal` string, nullable
      - `tool_calls` MessageToolCall[], nullable
        - `id` string, required
        - `type` 'function'
        - `function` ToolCallFunction, required
          - `name` string, required
          - `arguments` string, required
      - `reasoning_content` string, nullable
      - `annotations` union[], nullable
        - union
          - FileCitation — The OpenAI ``file_citation`` annotation, plus the chunk it points at. ``chunk_id`` is the same ``file_id:chunk_index`` reference every hosted result carries, and ``store_id`` the store whose index holds the chunk; the cited text and score are on the included tool results.
            - `type` 'file_citation'
            - `file_id` string, required
            - `filename` string, required
            - `index` integer, required
            - `chunk_id` string, required
            - `store_id` string, required
          - UrlCitation — The OpenAI ``url_citation`` annotation, for a hit of the web store; ``chunk_id`` as on the hosted result.
            - `type` 'url_citation'
            - `url` string, required
            - `title` string, required
            - `start_index` integer, required
            - `end_index` integer, required
            - `chunk_id` string, required
    - `finish_reason` 'stop' | 'tool_calls' | 'length'
    - `logprobs` unknown
  - `usage` CompletionUsage
    - `prompt_tokens` integer
    - `completion_tokens` integer
    - `total_tokens` integer
    - `prompt_tokens_details` PromptTokensDetails — Breakdown of the prompt tokens, as in the OpenAI usage object.
      - `cached_tokens` integer — Prompt tokens served from the cache; part of prompt_tokens, not extra
    - `completion_tokens_details` CompletionTokensDetails — Breakdown of the completion tokens, as in the OpenAI usage object.
      - `reasoning_tokens` integer — Tokens of the hosted loop's narration; part of completion_tokens, not extra
  - `metadata` object, nullable
  - `title` string, nullable — Short display title of the conversation this completion belongs to (Mixedbread extension)
  - `hosted_tool_calls` union[] — Server-side hosted tool executions of this completion (Mixedbread extension); chunk results ride along only for requested include keys, e.g. search_corpus_call.results
    - union
      - SearchCorpusCallItem — Record of one server-side search execution.
        - `type` 'search_corpus_call'
        - `id` string, required
        - `status` 'in_progress' | 'completed' | 'failed'
        - `queries` string[]
        - `metadata_filters` MetadataFilter[], nullable
          - `key` string, required — Metadata field key
          - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - `value` union, required — Value to compare against. Use a list for `in`/`not_in`.
            - string
            - integer
            - number
            - boolean
            - union[]
              - …
        - `filter_mode` 'all' | 'any'
        - `store` string, nullable
        - `results` object[], nullable
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
      - GrepCallItem — Record of one server-side grep execution.
        - `type` 'grep_call'
        - `id` string, required
        - `status` 'in_progress' | 'completed' | 'failed'
        - `pattern` string, nullable
        - `targets` StoreChunkGrepTarget[], nullable
        - `case_sensitive` boolean
        - `metadata_filters` MetadataFilter[], nullable
          - `key` string, required — Metadata field key
          - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - `value` union, required — Value to compare against. Use a list for `in`/`not_in`.
            - string
            - integer
            - number
            - boolean
            - union[]
              - …
        - `filter_mode` 'all' | 'any'
        - `store` string, nullable
        - `results` object[], nullable
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
      - FilterChunksCallItem — Record of one server-side metadata-driven chunk listing.
        - `type` 'filter_chunks_call'
        - `id` string, required
        - `status` 'in_progress' | 'completed' | 'failed'
        - `metadata_filters` MetadataFilter[], nullable
          - `key` string, required — Metadata field key
          - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - `value` union, required — Value to compare against. Use a list for `in`/`not_in`.
            - string
            - integer
            - number
            - boolean
            - union[]
              - …
        - `filter_mode` 'all' | 'any'
        - `rank_by` string, nullable
        - `direction` 'asc' | 'desc'
        - `store` string, nullable
        - `results` object[], nullable
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
      - InspectMetadataCallItem — Record of one server-side metadata facets lookup.
        - `type` 'inspect_metadata_call'
        - `id` string, required
        - `status` 'in_progress' | 'completed' | 'failed'
        - `store` string, nullable
        - `facets` object, nullable
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
      - GetChunksCallItem — Record of one server-side re-fetch of already-seen chunks.
        - `type` 'get_chunks_call'
        - `id` string, required
        - `status` 'in_progress' | 'completed' | 'failed'
        - `chunk_ids` string[]
        - `results` object[], nullable
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
      - StoreSearchCallItem — Deprecated `store_search_call` form, emitted for requests that declared the alias.
        - `type` 'store_search_call'
        - `id` string, required
        - `status` 'in_progress' | 'completed' | 'failed'
        - `queries` string[]
        - `metadata_filters` MetadataFilter[], nullable
          - `key` string, required — Metadata field key
          - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - `value` union, required — Value to compare against. Use a list for `in`/`not_in`.
            - string
            - integer
            - number
            - boolean
            - union[]
              - …
        - `filter_mode` 'all' | 'any'
        - `store` string, nullable
        - `results` object[], nullable
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
      - StoreGrepCallItem — Deprecated `store_grep_call` form, emitted for requests that declared the alias.
        - `type` 'store_grep_call'
        - `id` string, required
        - `status` 'in_progress' | 'completed' | 'failed'
        - `pattern` string, nullable
        - `targets` StoreChunkGrepTarget[], nullable
        - `case_sensitive` boolean
        - `metadata_filters` MetadataFilter[], nullable
          - `key` string, required — Metadata field key
          - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - `value` union, required — Value to compare against. Use a list for `in`/`not_in`.
            - string
            - integer
            - number
            - boolean
            - union[]
              - …
        - `filter_mode` 'all' | 'any'
        - `store` string, nullable
        - `results` object[], nullable
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
      - StoreListChunksCallItem — Deprecated `store_list_chunks_call` form, emitted for requests that declared the alias.
        - `type` 'store_list_chunks_call'
        - `id` string, required
        - `status` 'in_progress' | 'completed' | 'failed'
        - `metadata_filters` MetadataFilter[], nullable
          - `key` string, required — Metadata field key
          - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - `value` union, required — Value to compare against. Use a list for `in`/`not_in`.
            - string
            - integer
            - number
            - boolean
            - union[]
              - …
        - `filter_mode` 'all' | 'any'
        - `rank_by` string, nullable
        - `direction` 'asc' | 'desc'
        - `store` string, nullable
        - `results` object[], nullable
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
      - MetadataFacetsCallItem — Deprecated `store_metadata_facets_call` form, emitted for requests that declared the alias.
        - `type` 'store_metadata_facets_call'
        - `id` string, required
        - `status` 'in_progress' | 'completed' | 'failed'
        - `store` string, nullable
        - `facets` object, nullable
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
      - ListStoresCallItem — Record of one server-side store listing execution.
        - `type` 'list_stores_call'
        - `id` string, required
        - `status` 'in_progress' | 'completed' | 'failed'
        - `cursor` string, nullable
        - `stores` ListStoresResult[], nullable
          - `name` string, required
          - `description` string, nullable
          - `connectors` string[] — Providers of the connectors ingesting into this store, e.g. slack or notion
        - `has_more` boolean
        - `next_cursor` string, nullable
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
  - `context_management` ContextManagementResult — Context edits applied while serving one request (Mixedbread extension). Only ever emitted non-empty: a request whose context was never edited carries no `context_management` object at all.
    - `applied_edits` union[], required
      - union
        - AppliedPruneContextEdit — Aggregate of the model's prune_context calls in one request.
          - `type` 'prune_context'
          - `calls` integer, required — Number of prune_context calls the model made in this request
          - `cleared_input_tokens` integer, required — Input tokens cleared from the model's context
        - AppliedTruncateToolResultEdit — One caller tool result shortened by the server's context-overflow recovery.
          - `type` 'truncate_tool_result'
          - `tool_call_id` string, required — ID of the tool call whose result was shortened
          - `cleared_input_tokens` integer, required — Input tokens cleared from the model's context
  - `tool_tickets` ToolTicket[] — One short-lived ticket per client-executed tool call (Mixedbread extension). Send the matching ticket as the X-Mxbai-Tool-Ticket header on the store search or grep you run for that call, and it bills at the discounted agent rate. Each ticket redeems once.
    - `tool_call_id` string, required — ID of the tool call in `choices[].message.tool_calls` this covers
    - `ticket` string, required — Opaque token to send as the X-Mxbai-Tool-Ticket header
    - `expires_at` integer, required — Unix timestamp after which the ticket no longer redeems
  - `transcript` union[], nullable — Complete stored conversation transcript when requested through include
    - union
      - SystemMessage
        - `role` 'system', required
        - `content` union, required
          - string
          - TextPart[]
            - `type` 'text'
            - `text` string, required
      - DeveloperMessage — Alias of the system role; forwarded to the provider as system instructions.
        - `role` 'developer', required
        - `content` union, required
          - string
          - TextPart[]
            - `type` 'text'
            - `text` string, required
      - UserMessage
        - `role` 'user', required
        - `content` union, required
          - string
          - TextPart[]
            - `type` 'text'
            - `text` string, required
      - AssistantMessageOutput
        - `role` 'assistant', required
        - `content` union
          - string
          - TextPart[]
            - `type` 'text'
            - `text` string, required
        - `tool_calls` MessageToolCall[]
          - `id` string, required
          - `type` 'function'
          - `function` ToolCallFunction, required
            - `name` string, required
            - `arguments` string, required
        - `reasoning_content` string, nullable
        - `annotations` union[]
          - union
            - FileCitation — The OpenAI ``file_citation`` annotation, plus the chunk it points at. ``chunk_id`` is the same ``file_id:chunk_index`` reference every hosted result carries, and ``store_id`` the store whose index holds the chunk; the cited text and score are on the included tool results.
              - …
            - UrlCitation — The OpenAI ``url_citation`` annotation, for a hit of the web store; ``chunk_id`` as on the hosted result.
              - …
      - ToolMessage — Result of a function tool call, sent back by the caller.
        - `role` 'tool', required
        - `content` union, required
          - string
          - TextPart[]
            - `type` 'text'
            - `text` string, required
        - `tool_call_id` string, required

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-23** `824e59bfac1e` — 14 breaking, 2 warning, 2 info
  - added `#/components/schemas/FileCitation, #/components/schemas/UrlCitation` to the `choices/items/message/annotations/anyOf[subschema #1]/items/` response property `oneOf` list for the response status `200`
  - added `#/components/schemas/FileCitation, #/components/schemas/UrlCitation` to the `transcript/anyOf[subschema #1]/items/oneOf[subschema #4: AssistantMessage]/annotations/items/` response property `oneOf` list for the response status `200`
  - the `choices/items/message/annotations/anyOf[subschema #1]/items/` response's property type changed from `object` to no type for status `200`
  - the `transcript/anyOf[subschema #1]/items/oneOf[subschema #4: AssistantMessage]/annotations/items/` response's property type changed from `object` to no type for status `200`
  - …14 more
- **2026-09-15** `957bf8ec8df8` — 1 info
  - added the optional property `choices/items/message/refusal` to the response with the `200` status
- **2026-09-11** `ce3609b10ef1` — 2 info
  - added the optional property `choices/items/message/annotations` to the response with the `200` status
  - added the optional property `transcript/anyOf[subschema #1]/items/oneOf[subschema #4: AssistantMessage]/annotations` to the response with the `200` status
- …earlier changes not shown

[Full history](https://skmtc.dev/mixedbread/apis/mxbai-omni/changes/v1/chat/completions/:completion_id/get.md)

---

[API](https://skmtc.dev/mixedbread/apis/mxbai-omni.md) · [All operations](https://skmtc.dev/mixedbread/apis/mxbai-omni/llms.txt) · [OpenAPI document](https://skmtc.dev/mixedbread/apis/mxbai-omni/revisions/824e59bfac1e?raw)