---
title: "Get metadata facets"
method: POST
path: "/v1/stores/metadata-facets"
tags: ["stores"]
---

# Get metadata facets

`POST /v1/stores/metadata-facets`

## Request body

- MetadataFacetsParams — Parameters for getting metadata facets.
  - `store_identifiers` union[], required — IDs or names of stores
    - union
      - string
      - string, uuid
  - `top_k` integer — Number of results to return
  - `filters` union — Optional filter conditions
    - SearchFilterInput — Represents a filter with AND, OR, and NOT conditions.
      - `all` union[], nullable — List of conditions or filters to be ANDed together
        - union
          - SearchFilterInput — recursive
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
      - `any` union[], nullable — List of conditions or filters to be ORed together
        - union
          - SearchFilterInput — recursive
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
      - `none` union[], nullable — List of conditions or filters to be NOTed
        - union
          - SearchFilterInput — recursive
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
    - SearchFilterCondition — Represents a condition with a field, operator, and value.
      - `key` string, required — The field to apply the condition on
      - `value` string, required — The value to compare against
      - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
    - union[]
      - union
        - SearchFilterInput — Represents a filter with AND, OR, and NOT conditions.
          - `all` union[], nullable — List of conditions or filters to be ANDed together
            - union
              - …
          - `any` union[], nullable — List of conditions or filters to be ORed together
            - union
              - …
          - `none` union[], nullable — List of conditions or filters to be NOTed
            - union
              - …
        - SearchFilterCondition — Represents a condition with a field, operator, and value.
          - `key` string, required — The field to apply the condition on
          - `value` string, required — The value to compare against
          - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
  - `file_ids` string[], nullable — Optional list of file IDs to filter chunks by (inclusion filter)
  - `query` string, nullable — Search query text
  - `search_options` StoreChunkSearchOptions — Options for configuring store chunk searches.
    - `score_threshold` number — Minimum similarity score threshold
    - `rewrite_query` boolean — Whether to rewrite the query. Ignored when agentic is enabled (the agent handles query decomposition).
    - `rerank` union — Whether to rerank results and optional reranking configuration. Ignored when agentic is enabled (the agent handles ranking).
      - boolean
      - RerankConfig — Represents a reranking configuration.
        - `model` string — The name of the reranking model
        - `with_metadata` union — Whether to include metadata in the reranked results
          - boolean
          - string[]
        - `top_k` integer, nullable — Maximum number of results to return after reranking. If None, returns all reranked results.
    - `agentic` union — Whether to use agentic multi-query search with automatic query decomposition and ranking. When enabled, rewrite_query and rerank options are ignored.
      - boolean
      - AgenticSearchConfig — Configuration for agentic multi-query search.
        - `max_rounds` integer — Maximum number of search rounds
        - `queries_per_round` integer — Maximum queries per round
        - `strict_top_k` boolean — Whether the final retrieved chunk list must provide exactly top_k ranked chunks
        - `media_content` 'auto' | 'never' | 'always' — Controls when retrieved image content is provided to the agent. `auto` sends images only when no OCR text or summary is available, `never` disables image content, and `always` sends image content when available. Currently not forwarded: the search agent runs without image content.
        - `instructions` string, nullable — Additional custom instructions (followed only when not in conflict with existing rules)
        - `verbose` boolean — Internal: when set, the response includes a `trace` field with the full tool-call timeline. Used by the Mixedbread playground; not part of the documented public API.
    - `return_metadata` boolean — Whether to return file metadata
    - `apply_search_rules` boolean — Whether to apply search rules
  - `facets` string[], nullable — Optional list of facets to return. Use dot for nested fields.
  - `max_fields` integer — Maximum number of distinct metadata fields (keys) to return.
  - `max_values_per_field` integer — Maximum number of distinct values returned per field, ranked by count.
  - `max_files` integer — Maximum number of store files scanned to compute facets.

## Response `200`

The metadata facets

- MetadataFacets — Represents metadata facets for a store.
  - `facets` object, required — Metadata facets

## 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)