---
title: "List chat completions"
method: GET
path: "/v1/chat/completions"
tags: ["chat"]
---

# List chat completions

`GET /v1/chat/completions`

List stored chat completions, one per conversation.

Only conversation tips are returned: a completion is listed unless another
stored completion continues from it via previous_completion_id.

## Query parameters

- `limit` integer — Number of completions to return
- `after` string, nullable — Completion ID to list completions after (older than)
- `q` string, nullable — Filter by title (case-insensitive substring)
- `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 latest completion of each conversation, newest first

- ChatCompletionList — List envelope of stored completions, newest first.
  - `object` 'list'
  - `data` ChatCompletion[]
    - `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.
              - …
            - UrlCitation — The OpenAI ``url_citation`` annotation, for a hit of the web store; ``chunk_id`` as on the hosted result.
              - …
      - `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`.
              - …
          - `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`.
              - …
          - `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`.
              - …
          - `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`.
              - …
          - `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`.
              - …
          - `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`.
              - …
          - `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[]
              - …
        - DeveloperMessage — Alias of the system role; forwarded to the provider as system instructions.
          - `role` 'developer', required
          - `content` union, required
            - string
            - TextPart[]
              - …
        - UserMessage
          - `role` 'user', required
          - `content` union, required
            - string
            - TextPart[]
              - …
        - AssistantMessageOutput
          - `role` 'assistant', required
          - `content` union
            - string
            - TextPart[]
              - …
          - `tool_calls` MessageToolCall[]
            - `id` string, required
            - `type` 'function'
            - `function` ToolCallFunction, required
              - …
          - `reasoning_content` string, nullable
          - `annotations` union[]
            - union
              - …
        - ToolMessage — Result of a function tool call, sent back by the caller.
          - `role` 'tool', required
          - `content` union, required
            - string
            - TextPart[]
              - …
          - `tool_call_id` string, required
  - `first_id` string, nullable
  - `last_id` string, nullable
  - `has_more` boolean

## 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 `data/items/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 `data/items/transcript/anyOf[subschema #1]/items/oneOf[subschema #4: AssistantMessage]/annotations/items/` response property `oneOf` list for the response status `200`
  - the `data/items/choices/items/message/annotations/anyOf[subschema #1]/items/` response's property type changed from `object` to no type for status `200`
  - the `data/items/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 `data/items/choices/items/message/refusal` to the response with the `200` status
- **2026-09-11** `ce3609b10ef1` — 2 info
  - added the optional property `data/items/choices/items/message/annotations` to the response with the `200` status
  - added the optional property `data/items/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/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)