talonic_field_values
Read a field's current values across documents, with provenance — one row per bound occurrence: document id, filename and type, the value, its confidence, the raw name it was captured under, the verbatim source text, and the resolution band that bound it. Rows are Sources-IAM filtered for the caller and cursor-paginated newest first.
When to use
- The user asks 'what are all the X across my documents'.
- You need to tabulate or aggregate one concept across the corpus.
- You want the evidence (source text plus document) behind a value.
When not to use
- Multi-field, row-shaped queries over documents — use
talonic_filter. - One document's full field set — use
talonic_get_document.
Parameters
| Parameter | Type | Description |
|---|---|---|
| field_id | string | Field UUID. Provide either `field_id` or `name`. |
| name | string | Field name (resolved like `talonic_get_field`). |
| document_id | string | Only occurrences on this document. |
| value | string | Case-insensitive contains filter on the value text. |
| limit | number | Page size (default 20, max 100). |
| cursor | string | Opaque cursor from `pagination.next_cursor`. |
Response shape
Fields
| Parameter | Type | Description |
|---|---|---|
| data[].document_id | string | Document the value came from (`document_filename`, `document_type` alongside). |
| data[].value | any | The current bound value as captured. |
| data[].confidence | number|null | Capture confidence 0–1. |
| data[].provenance | object | `raw_field_name`, `source_text`, `resolved_by` (`exact`, `cluster`, `semantic_auto`, `llm_rescue`, …), `needs_confirmation`, `via_redirect`. |
| concept_ids | string[] | The concept plus absorbed redirects whose occurrences are included. |
| pagination | object | `total` counts the visible set. |
Tool input
{ "name": "invoice_number", "value": "2026", "limit": 2 }Tool response
{
"field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"canonical_name": "invoice_number",
"concept_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
"data": [
{
"occurrence_id": "0f1e2d3c-…",
"document_id": "f0e1d2c3-…",
"document_filename": "RE-2026-0142.pdf",
"document_type": "invoice",
"value": "INV-2026-0142",
"confidence": 0.97,
"provenance": { "raw_field_name": "Rechnungsnummer", "source_text": "Rechnungsnummer: INV-2026-0142", "resolved_by": "exact", "needs_confirmation": false, "via_redirect": false },
"links": { "document": "/v1/documents/f0e1…", "document_fields": "/v1/documents/f0e1…/fields" }
}
],
"pagination": { "total": 37, "limit": 2, "has_more": true, "next_cursor": "MGYx…" }
}Frequently asked questions
Are the values filtered by the caller's document visibility?+
Yes. Rows and `pagination.total` are Sources-IAM filtered as the API key's minting user, exactly like the other document reads.