Filter Talonic Documents
talonic_filterFilter documents by extracted field values using conditions like equals, greater than, or contains to find exactly what you need.
Instructions
Find documents by their extracted field VALUES using composable conditions (e.g. 'invoices where total > 1000').
USE WHEN: value-based criteria on extracted fields — numeric/date/text comparisons or presence checks.
NOT FOR: free-text / concept search (use talonic_search) · a single document by id (use talonic_get_document).
ARGS: conditions[] (AND-ed). Each = EXACTLY ONE of field (canonical name) or field_id (UUID), an operator, and usually a value. Operators: eq, neq, gt, gte, lt, lte, between (needs value AND value_to), contains, is_empty / is_not_empty (no value). value/value_to are string|number|boolean matching the field type (ISO YYYY-MM-DD for dates).
TEXT FILTERS: for eq/contains/is_not_empty on a text field, just TRY a natural field name ('currency', 'vendor_name') — names resolve server-side and an unresolved field surfaces in warnings[] rather than erroring. Do NOT block on discovering the field first; search-first is only required for numeric operators.
NUMERIC GUARD: gt/gte/lt/lte/between only work when the field's dataType is 'number'. Call talonic_search first and check dataType; a numeric op on a string field returns zero matches. If the response has warnings[], surface them to the user — do not silently retry.
RETURNS: data[] (matching documents with field values), total, warnings[].
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. |