Skip to main content

Field Values

List the distinct values of an extracted field across all documents, with per-value counts. Build filter dropdowns and faceted search interfaces.

The field values endpoint returns the distinct values of a specific extracted field across all documents in your workspace, with a count of how many documents carry each value. Results are sorted by count descending, so the most common values appear first. Use it to populate filter dropdowns, build faceted search interfaces, or analyze value distributions for data quality.

The field parameter must be a field registry UUID, not a field name. Resolve names to UUIDs with the field autocomplete endpoint or GET /v1/fields; a non-UUID value returns a 400 error.
GET/v1/search/field-values

Query parameters

field*stringThe field registry UUID to read values for (resolve it via field autocomplete).
source_idstringScope to a specific source connection.
qstringFilter values by substring match (case-insensitive).
limitintegerMaximum number of values to return (up to 500). Default: 50

Request

Response

Response fields

valuesarrayArray of distinct value objects sorted by count descending.
values[].valuestringThe distinct field value.
values[].countintegerNumber of documents containing this value.
totalDistinctintegerTotal number of distinct values for this field (before limit is applied).

Response

{
  "values": [
    { "value": "Acme Corp", "count": 47 },
    { "value": "Globex Inc", "count": 23 }
  ],
  "totalDistinct": 156
}

Errors

Error responses

400validation_errorThe `field` parameter is missing or is not a field registry UUID.
401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Pair this endpoint with the field autocomplete endpoint to build a two-step filter UI: first let the user select a field via GET /v1/search/autocomplete, then populate a dropdown with that field's distinct values from this endpoint. The totalDistinct count is useful for showing "N of M values" pagination hints.

Related

Field Autocomplete
Filter Documents
List Fields