---
title: "Return distinct values for a single field."
method: POST
path: "/v1/collections/{collection_identifier}/documents/distinct"
tags: ["Collection Documents"]
---

# Return distinct values for a single field.

`POST /v1/collections/{collection_identifier}/documents/distinct`

Return the set of unique values for one document field across a collection, together with a per-value document count sorted desc. Thin wrapper over `/aggregate` for the common `SELECT DISTINCT <field>` case — use this when a UI needs a facet list (e.g. `brand_slug`) without loading every document. Null/missing values are excluded.

## Path parameters

- `collection_identifier` string, required — The unique identifier of the collection.

## Request body

- DistinctValuesRequest — Return the set of unique values for a single field across a collection. Thin wrapper over the aggregation framework for the common `SELECT DISTINCT <field>` use case. Callers don't need to build a `group_by` + COUNT pipeline by hand — pass a field name and (optionally) pre-aggregation filters and get back a flat list of values plus per-value counts.
  - `field` string, required — Document field whose distinct values should be returned. Dotted paths are supported (e.g. `metadata.brand_slug`). Null/missing values are excluded.
  - `filters` object, nullable — Optional pre-aggregation filters, same syntax as the standard aggregation endpoint. Applied before distinct values are computed.
  - `limit` integer, nullable — Maximum number of distinct values to return (sorted by count desc). Defaults to no limit on the server side; for high-cardinality fields always set a limit to keep the response bounded.

## Response `200`

Successful Response

- DistinctValuesResponse — Flat list of distinct values for a single field.
  - `field` string, required — The field that was queried.
  - `values` DistinctValue[], required — Distinct values sorted by descending count. Respects the `limit` argument; use the length of this list as the returned count.
    - `value` unknown, required
    - `count` integer, required — Number of documents with this exact value.
  - `total_distinct` integer, required — Number of distinct values in the response (== len(values)). When `limit` is set this can be less than the true cardinality.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/220a3b263fda/schema)