Return distinct values for a single field.

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.

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

Return distinct values for a single field.

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/distinct \
  --header 'Content-Type: application/json' \
  --data '
{
  "field": "<string>",
  "filters": {},
  "limit": 5000
}
'

200

{
  "field": "<string>",
  "values": [
    {
      "value": "<unknown>",
      "count": 123
    }
  ],
  "total_distinct": 123
}

Headers

Authorization · string

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Examples:

"Bearer YOUR_API_KEY"

"Bearer YOUR_STRIPE_API_KEY"

authorization · string

X-Namespace · string

Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'. Falls back to ?namespace= query parameter if the header is omitted.

Examples:

"ns_abc123def456"

"production"

"my-namespace"

Path Parameters

collection_identifier · string · required

The unique identifier of the collection.

Body

application/json

Field + optional filters/limit for the distinct query.

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.

Examples:

"brand_slug"

"metadata.category"

filters · Filters · object

Optional pre-aggregation filters, same syntax as the standard aggregation endpoint. Applied before distinct values are computed.

limit · integer | null

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.

Required range: 1 <= x <= 10000

Response

200

application/json

Successful Response

Flat list of distinct values for a single field.

field · string · required

The field that was queried.

values · DistinctValue · object[] · required

Distinct values sorted by descending count. Respects the limit argument; use the length of this list as the returned count.

Show child attributes

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.