Get Metadata Facets

POST/v1/stores/metadata-facets

AuthorizationLink to section

Authorizationstringrequired

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

Request BodyLink to section

store_identifiersarrayrequired

IDs or names of stores

Constraints

•Minimum items: 1•Maximum items: 16

top_kintegerdefault: 10

Number of results to return

Constraints

•Minimum: 1

file_idsarray | null

Optional list of file IDs to filter chunks by (inclusion 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"]].

querystring | null

Search query text

Constraints

•Minimum length: 1

facetsarray | null

Optional list of facets to return. Use dot for nested fields.

max_fieldsintegerdefault: 64

Maximum number of distinct metadata fields (keys) to return.

Constraints

•Minimum: 1•Maximum: 256

max_values_per_fieldintegerdefault: 32

Maximum number of distinct values returned per field, ranked by count.

Constraints

•Minimum: 1•Maximum: 256

max_filesintegerdefault: 10000

Maximum number of store files scanned to compute facets.

Constraints

•Minimum: 1•Maximum: 100000

Response BodyLink to section

facetsobjectrequired

Metadata facets, keyed by field name. Each value is a map of facet value to occurrence count. Nested fields use dot notation.

Request

POST/v1/stores/metadata-facets

from mixedbread import Mixedbread

mxbai = Mixedbread(api_key="YOUR_API_KEY")

response = mxbai.stores.metadata_facets(
    store_identifiers=["my-knowledge-base"],
    facets=["author", "year"],
)

print(response.facets)

Response

JSON

{
  "facets": {
    "category": {
      "report": 3,
      "press": 2
    },
    "year": {
      "2022": 1,
      "2023": 2,
      "2024": 2
    },
    "author.name": {
      "alice": 2,
      "bob": 1,
      "carol": 2
    }
  }
}