Filter Talonic Documents
talonic_filterFilter documents by extracted field values using operators like eq, gt, between. Get a paginated, sortable list matching your structured criteria.
Instructions
STATUS: stable. Field-name resolution is server-side.
Filter the user's Talonic documents by extracted field values using composable conditions. Conditions accept either a canonical field name (e.g. 'vendor.name', 'policy.0_coverage_type') or a field UUID. The Talonic API resolves names to ids server-side.
USE WHEN:
The user wants documents matching specific structured criteria, like 'invoices over 1000 EUR' or 'contracts expiring before 2026-12-31' or 'COIs from Acme'.
The query is value-based on extracted fields, not a free-text concept search.
You need to retrieve a sortable, paginated list filtered by field conditions.
DO NOT USE WHEN:
The user wants conceptual / free-text search across content (use talonic_search).
The user is looking for a single document by id (use talonic_get_document).
The user wants extracted data from a new document (use talonic_extract).
OPERATORS:
eq, neq: equality / inequality.
gt, gte, lt, lte: numeric or date comparisons.
between: requires both
valueandvalue_to.contains: substring match on string fields.
is_empty: presence check, no value needed. Returns documents where the field is null or missing.
is_not_empty: presence check, no value needed. Returns documents where the field has a materialized value. Results reflect data within seconds of extraction completing.
SCHEMA TYPING:
Numeric operators (
gt,gte,lt,lte,between) only resolve correctly when the schema field is typed asnumber. A field typed asstringthat holds numeric content (e.g. '€1,500.00') will silently return zero matches even after extraction. Pick the right type at schema design time.If the response contains a
warningsarray, surface itsmessage(andsuggestion, if present) to the user verbatim — these explain why a query returned zero or unexpected results and typically suggest a schema-design change (e.g. switching a field'sdata_typefromstringtonumber) that will make subsequent filter calls work correctly. Do not silently retry without flagging the warning.
TIPS:
To discover available field names, call talonic_search first with a related query. Only use fields[] entries where filterable is true — their canonicalName is what to pass as
fieldhere. Fields with filterable: false have no extracted data yet.fieldMatches[].resolvedFieldId is only valid when filterable is true. Entries with filterable: false have resolvedFieldId: null and cannot be used for filtering.
Both
field(name) andfield_id(UUID) reach the API asfieldId. Either is fine.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| conditions | Yes | One or more filter conditions, AND-ed together. | |
| search | No | Optional free-text search applied alongside the filters. | |
| sort | No | Optional sort by a field. | |
| page | No | Page number for pagination. | |
| limit | No | Results per page. Default 50 server-side. | |
| source_connection_id | No | Optionally scope to a specific source connection. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Documents matching the filter conditions, with their extracted field values. | |
| total | No | Total documents matching across all pages. | |
| page | No | Current page number. | |
| pagination | No | Cursor-based pagination metadata. | |
| warnings | No | API warnings surfaced by the Talonic filter endpoint. Most commonly raised when a numeric operator is applied to a string-typed field, in which case the warning explains the lexicographic-comparison trap and suggests a schema-design change. Agents should surface these to the user rather than silently retrying. |