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. A value comes back as a JSON number or boolean when the namespace declares a payload index of type integer, float or bool on the field. Any other field, including an undeclared numeric one, facets as strings, so check the namespace’s payload_indexes to know which you will get. When a storage shard times out or returns only part of its documents, the list can be short: query_info.truncated is then true and query_info.warning says what to do.

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 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "field": "brand_slug",
  "filters": {},
  "limit": 5000
}
'

200

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

Authorizations

Authorization · string · header · required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

X-Namespace · string · header · required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

Path Parameters

collection_identifier · string · required

The unique identifier of the collection.

Body

application/json

Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

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 | null

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.

query_info · Query Info · object

Empty when the answer is complete. When a storage shard timed out or returned only part of its documents, this holds truncated: true, a reason, any shard_warnings, and a warning; the list may then be missing values and every count is a lower bound. Retrying usually gives the full answer.