Search Chunks

POST/v1/stores/search

Authorization

Authorizationstringrequired

Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`

Request Body

querystringrequired

Search query text

Constraints

•Minimum length: 1

store_identifiersarray | null

IDs or names of stores to search. This can be stores in your org or `mixedbread/web` for the web-store.

Constraints

•Minimum items: 1•Maximum items: 16

top_kintegerdefault: 10

Number of results to return

Constraints

•Minimum: 1

file_idsarray | null

Optional file IDs to filter. Use list only for inclusion or specify an operator (`in` or `not_in`). Example: ["file_id_1", "file_id_2"] or ["not_in", ["file_id_1", "file_id_2"]].

streambooleandefault: false

Return live agentic-search trace events as a server-sent event stream. Requires `search_options.agentic` to be enabled. A successful stream ends with a `search.completed` event containing the final search response, followed by `[DONE]`.

Response Body

objectstringdefault: list

The object type of the response

Request

POST/v1/stores/search

from mixedbread import Mixedbread

mxbai = Mixedbread(api_key="YOUR_API_KEY")

response = mxbai.stores.search(
    query="How does authentication work?",
    store_identifiers=["my-knowledge-base"],
    top_k=5,
)

for chunk in response.data:
    print(chunk)

Response

JSON

{
  "object": "list",
  "data": [
    {
      "chunk_index": 0,
      "mime_type": "text/plain",
      "model": "mxbai-omni",
      "score": 0.8512,
      "file_id": "{{FILE_ID}}",
      "filename": "auth_guide.pdf",
      "store_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "metadata": {
        "source": "upload",
        "page": 1
      },
      "type": "text",
      "text": "Authentication is handled through JWT tokens. First, the user provides credentials..."
    },
    {
      "chunk_index": 2,
      "mime_type": "image/jpeg",
      "model": "mxbai-omni",
      "score": 0.8234,
      "file_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "filename": "security_diagram.pdf",
      "store_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "metadata": {
        "category": "security",
        "year": 2024
      },
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/auth-flow.jpg",
        "format": "jpeg"
      },
      "ocr_text": "Authentication Flow Diagram",
      "summary": "A diagram showing the OAuth 2.0 authentication flow"
    }
  ]
}

Streaming events

When you search chunks with search_options.agentic: true and stream: true, the server emits server-sent events as the Agentic Search runs. This section contains the events emitted by the server.

search.started

Emitted when the Agentic Search starts.

type"search.started"required

The event type. Always `search.started`.

started_atstring(date-time)required

Time when the Agentic Search began.

querystringrequired

Original query submitted by the user.

search.started

JSON

{
  "type": "search.started",
  "started_at": "2026-08-19T12:00:00Z",
  "query": "How did revenue change from 2024 to 2025?"
}

tool_call.started

Emitted when the agent starts a retrieval, metadata, or generation step.

type"tool_call.started"required

The event type. Always `tool_call.started`.

tool_call_idstringrequired

Identifier that pairs this event with its `tool_call.completed` event.

tool_namestringrequired

Name of the tool being invoked.

started_atstring(date-time)required

Time when the tool call began.

argumentsobject | null

Compact summary of the arguments passed to the tool.

tool_call.started

JSON

{
  "type": "tool_call.started",
  "tool_call_id": "live-a1b2c3d4e5f6",
  "tool_name": "search_corpus",
  "started_at": "2026-08-19T12:00:00.120Z",
  "arguments": {
    "query": "2025 annual revenue",
    "top_k": 10
  }
}

tool_call.completed

Emitted when a retrieval, metadata, or generation step finishes. The tool_call_id matches the preceding tool_call.started event.

type"tool_call.completed"required

The event type. Always `tool_call.completed`.

tool_call.completed

JSON

{
  "type": "tool_call.completed",
  "tool_call": {
    "tool_call_id": "live-a1b2c3d4e5f6",
    "tool_name": "search_corpus",
    "tool_type": "function",
    "started_at": "2026-08-19T12:00:00.120Z",
    "duration": "PT0.42S",
    "arguments": {
      "query": "2025 annual revenue",
      "top_k": 10
    },
    "result": {
      "result_count": 10
    },
    "error": null,
    "error_kind": null
  }
}

search.completed

Emitted when the Agentic Search succeeds. Its response field contains the final search response and the authoritative trace for the completed run. After this event, the server emits data: [DONE] and closes the stream.

type"search.completed"required

The event type. Always `search.completed`.

responseStoreSearchResponserequired

The final ranked search response, including the authoritative Agentic Search trace.

search.completed

JSON

{
  "type": "search.completed",
  "response": {
    "object": "list",
    "data": [],
    "trace": {
      "started_at": "2026-08-19T12:00:00Z",
      "search_time": "PT1.84S",
      "query": "How did revenue change from 2024 to 2025?",
      "instructions": null,
      "rounds_executed": 1,
      "tool_calls": [],
      "results": []
    }
  }
}

search.failed

Emitted when the Agentic Search stops with an error. The stream closes after this event and does not emit [DONE].

type"search.failed"required

The event type. Always `search.failed`.

errorstringrequired

User-safe failure message.

search.failed

JSON

{
  "type": "search.failed",
  "error": "The search could not be completed."
}