Search Chunks
POST/v1/stores/search
AuthorizationLink to section
Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`
Request BodyLink to section
Search query text
Constraints
IDs or names of stores to search. This can be stores in your org or `mixedbread/web` for the web-store.
Constraints
10Number of results to return
Constraints
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"]].
falseReturn 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 BodyLink to section
listThe object type of the response
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){
"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 eventsLink to section
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.startedLink to section
Emitted when the Agentic Search starts.
The event type. Always `search.started`.
Time when the Agentic Search began.
Original query submitted by the user.
{
"type": "search.started",
"started_at": "2026-08-19T12:00:00Z",
"query": "How did revenue change from 2024 to 2025?"
}tool_call.startedLink to section
Emitted when the agent starts a retrieval, metadata, or generation step.
The event type. Always `tool_call.started`.
Identifier that pairs this event with its `tool_call.completed` event.
Name of the tool being invoked.
Time when the tool call began.
Compact summary of the arguments passed to the tool.
{
"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.completedLink to section
Emitted when a retrieval, metadata, or generation step finishes. The
tool_call_id matches the preceding tool_call.started event.
The event type. Always `tool_call.completed`.
{
"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.completedLink to section
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.
The event type. Always `search.completed`.
The final ranked search response, including the authoritative Agentic Search trace.
{
"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.failedLink to section
Emitted when the Agentic Search stops with an error. The stream closes after
this event and does not emit [DONE].
The event type. Always `search.failed`.
User-safe failure message.
{
"type": "search.failed",
"error": "The search could not be completed."
}