---
title: "Filter Field Values"
method: POST
path: "/search/filter-field-values"
tags: ["Search"]
---

# Filter Field Values

`POST /search/filter-field-values`

Get the top values by count for a single filter-search field.

## Headers

- `x-api-key` string, nullable

## Request body

- FilterFieldValuesRequest — Request for top values of a single field.
  - `mode` 'people' | 'company' — Search mode: 'people' or 'company'.
  - `field` string, required — Canonical field path to aggregate values for.
  - `top_k` integer — Maximum number of top values to return.
  - `filters` object, nullable — Raw OpenSearch DSL filters that scope the aggregation.
  - `simple_filters` object, nullable — MongoDB-style filters that scope the aggregation.

## Response `200`

Successful Response

- FilterFieldValuesResponse — Top values response for one field.
  - `mode` 'people' | 'company' — Search mode: 'people' or 'company'.
  - `field` string, required — Field requested by the caller.
  - `canonical_field` string, required — Canonical field path used for aggregation.
  - `aggregation_field` string, nullable — Underlying field used for the terms aggregation.
  - `nested_path` string, nullable — Nested path, if any.
  - `value_type` string, required — Aggregation target type (keyword, long, etc.).
  - `supports_top_values` boolean, required — Whether this field supports top-values aggregation.
  - `supports_exact_filter_snippet` boolean, required — Whether the response includes deterministic filter snippets.
  - `related_fields` string[] — Other field paths representing the same concept (e.g. flat counterpart of nested).
  - `preferred_for_exact_match` boolean — Recommended for simple exact-match queries over its nested counterpart.
  - `total_scoped_documents` integer, required — Total documents matched by the scoped query.
  - `request_duration_ms` integer, nullable — Server-side request duration in milliseconds.
  - `values` FilterFieldValuesValue[] — Top values ordered by count.
    - `value` union — Field value; null bucket represents missing values.
      - string
      - integer
      - number
      - boolean
    - `count` integer, required — Document count for this value within the scoped query.
    - `percent_of_scope` number, required — Share (0-1) of scoped documents matching this value.
    - `filter_snippet` object, nullable — Ready-to-merge filter clause that selects this value.

## Other responses

- `400` — Request was rejected by the route's validation rules.
- `401` — Missing or invalid API key.
- `402` — Insufficient credits or no active subscription for this organization.
- `403` — Forwarded user_id does not belong to caller's organization.
- `404` — Search task or export file not found.
- `409` — Export workflow already running for this search.
- `422` — Request body failed validation.
- `429` — Rate limit exceeded.
- `500` — Unexpected server error. Retry with backoff.
- `502` — Upstream search backend returned an error.
- `503` — Search backend is not configured or unavailable.
- `504` — Upstream search backend timed out.

---

[API](https://skmtc.dev/sixtyfour/apis/sixtyfour-api.md) · [All operations](https://skmtc.dev/sixtyfour/apis/sixtyfour-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/sixtyfour/sixtyfour-api/revisions/51f0a2b62b44/schema)