Skip to Content
Mixedbread

List Store Chunks

List store chunks purely by metadata filters, with no embeddings, semantic similarity or reranking. Useful for ranked retrieval over numeric metadata attributes.

POST
/v1/stores/list-chunks

Unlike /stores/search, this endpoint does not require a query and never runs a vector lookup. It returns chunks whose file and chunk metadata satisfy filters, optionally ordered by a numeric metadata field via sort_by. Useful for ranked retrieval over numeric attributes (e.g. price, BPM) and for reproducing the agentic filter_chunks tool externally.

list-chunks filters across all requested stores and returns at most top_k chunks in total. With sort_by, results are ordered globally by that field. Otherwise results are interleaved across stores in the order requested, preserving each store's result order. Pagination is not supported; raise top_k to retrieve more chunks.

Authorization

ApiKeyAuth
headerAuthorizationBearer <token>

Api key to access Mixedbreads API

Request Body

application/json
  1. body

Filter parameters including metadata filters, optional numeric sort, and pagination options

store_identifiers*array<string|>

IDs or names of stores

Items1 <= items <= 64
filters?||array<|>|

Optional filter conditions

file_ids?array<any>|array<>|

Optional list of file IDs to filter chunks by (inclusion filter)

top_k?Top K

Number of results to return

Range1 <= value <= 10000
Default10
sort_by?|array<any>|

Optional sort applied to the returned chunks. Pass a metadata field path or a tuple of (field path, ascending). Unprefixed dot paths target file metadata; generated_metadata.* targets chunk metadata.

search_options?

Search configuration options

Response Body

List of chunks matching the metadata filters, optionally ordered by a numeric metadata field

application/json
  1. response
object?Object

The object type of the response

Default"list"
data*array<|||>

The list of chunks matching the metadata filters

Example Request
from mixedbread import Mixedbread

mxbai = Mixedbread(api_key="YOUR_API_KEY")

response = mxbai.stores.list_chunks(
    store_identifiers=["my-knowledge-base"],
    top_k=10,
)

for chunk in response.data:
    print(chunk)
Example Response
{
  "object": "list",
  "data": [
    {
      "chunk_index": 0,
      "mime_type": "text/plain",
      "model": "mxbai-omni",
      "score": 1,
      "file_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "filename": "pricing.csv",
      "store_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "metadata": {
        "category": "pricing",
        "currency": "USD"
      },
      "type": "text",
      "text": "Premium plan: $99/month, includes unlimited search across all stores."
    },
    {
      "chunk_index": 3,
      "mime_type": "text/plain",
      "model": "mxbai-omni",
      "score": 1,
      "file_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "filename": "pricing.csv",
      "store_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "metadata": {
        "category": "pricing",
        "currency": "USD"
      },
      "type": "text",
      "text": "Starter plan: $19/month, includes 1,000 search queries per month."
    }
  ]
}