Field Values

List the distinct values of an extracted field across documents with GET /v1/search/field-values: per-value counts sorted by frequency for faceted search UIs.

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.

Values are read from the materialized value store — the same store POST /v1/documents/filter executes against — so every value returned here, passed as an eq condition to the filter, matches exactly count documents. That closed loop is what makes the endpoint safe for facet UIs: a facet chip can display its count up front and the click can never come back empty. Counts respect Sources-IAM visibility, evaluated as the API key's minting user.

The optional q parameter narrows values by case-insensitive substring match, which turns the endpoint into a value-level autocomplete: as a user types into a filter input, fetch matching values with their counts and offer them as suggestions. Combine with source_id to scope the distribution to one ingestion stream — useful when the same field (say currency) has different distributions per source.

curl "https://api.talonic.com/v1/search/field-values?field=6f1e9a2b-4c3d-4e5f-8a7b-9c0d1e2f3a4b" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Response

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

Errors

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, and for spotting data-quality issues — a field like currency reporting 40 distinct values usually means unnormalized variants worth a resolution policy.