Filter Talonic Documents
talonic_filterFilter documents by extracted field values using conditions like 'total > 1000'. Supports numeric, date, text comparisons and presence checks.
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. |