---
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
        - `tool_calls` MessageToolCall[], nullable
          - `id` string, required
          - `type` 'function'
          - `function` ToolCallFunction, required
            - `name` string, required
            - `arguments` string, required
        - `reasoning_content` string, nullable
      - `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
    - `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. store_search_call.results
      - union
        - StoreSearchCallItem — Record of one server-side store search execution.
          - `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` StoreSearchResult[], nullable
            - `index` integer, nullable
            - `store_id` string, required
            - `file_id` string, required
            - `chunk_index` integer, required
            - `filename` string, nullable
            - `mime_type` string, nullable
            - `score` number, required
            - `text` string, nullable
            - `ocr_text` string, nullable
            - `transcription` string, nullable
            - `summary` string, nullable
            - `metadata` unknown
            - `generated_metadata` unknown
          - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
            - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
            - `message` string, required
          - `reasoning_offset` integer, nullable
        - StoreGrepCallItem — Record of one server-side grep execution.
          - `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` StoreSearchResult[], nullable
            - `index` integer, nullable
            - `store_id` string, required
            - `file_id` string, required
            - `chunk_index` integer, required
            - `filename` string, nullable
            - `mime_type` string, nullable
            - `score` number, required
            - `text` string, nullable
            - `ocr_text` string, nullable
            - `transcription` string, nullable
            - `summary` string, nullable
            - `metadata` unknown
            - `generated_metadata` unknown
          - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
            - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
            - `message` string, required
          - `reasoning_offset` integer, nullable
        - StoreListChunksCallItem — Record of one server-side metadata-driven chunk listing.
          - `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` StoreSearchResult[], nullable
            - `index` integer, nullable
            - `store_id` string, required
            - `file_id` string, required
            - `chunk_index` integer, required
            - `filename` string, nullable
            - `mime_type` string, nullable
            - `score` number, required
            - `text` string, nullable
            - `ocr_text` string, nullable
            - `transcription` string, nullable
            - `summary` string, nullable
            - `metadata` unknown
            - `generated_metadata` unknown
          - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
            - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
            - `message` string, required
          - `reasoning_offset` integer, nullable
        - MetadataFacetsCallItem — Record of one server-side metadata facets lookup.
          - `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
          - `reasoning_offset` integer, nullable
        - 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
          - `reasoning_offset` integer, nullable
    - `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
        - 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

---

[API](https://skmtc.net/mixedbread/apis/mxbai-omni.md) · [All operations](https://skmtc.net/mixedbread/apis/mxbai-omni/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixedbread/mxbai-omni/revisions/6dac6bb49f72/schema)