talonic_ask
Ask a natural-language question over the workspace's documents and get a cited, verified answer in markdown. The Talonic agent plans over the structured field plane, runs read-only SQL over extracted cells, reads document text, and grounds every load-bearing claim in a source span. The call waits up to wait_seconds (default 45, max 55) for the answer; if it is not ready in time, the response comes back processing with an ask_id to poll. Consumes credits.
Costs credits. For a known field's values use
talonic_field_values or talonic_filter — they are free.When to use
- The user asks an open question about their documents, e.g. 'which vendors invoiced us twice in May?'
- The user wants a summary across documents.
- The answer needs reasoning over several fields, not a single known value.
When not to use
- Reading a known field's values — use
talonic_field_values(free). - Filtering documents by a known value — use
talonic_filter(free). - Locating which field holds a concept — use
talonic_find_data.
Parameters
| Parameter | Type | Description |
|---|---|---|
| question * | string | The question, in the user's words (max 4000 characters). |
| scope | object | Restrict the question to a slice of the workspace — `document_ids[]`, `schema_id`, `pipeline_id`, `data_product_id`, `document_type`, `source_id`, `tags[]`, `ingested_after`, `ingested_before`. Present fields are ANDed. |
| conversation_id | string | Continue an existing conversation; the agent sees prior turns. |
| output_format | object | Shape the answer — `instruction` and/or `template`. Form only, never grounding. |
| wait_seconds | number | Seconds to wait for the answer before returning `processing` (0–55, default 45). Default: `45` |
Response shape
Fields
| Parameter | Type | Description |
|---|---|---|
| ask_id | string | The ask's id — pass to `talonic_get_answer` if still processing. |
| status | string | `completed`, `processing` or `error`. |
| conversation_id | string | This ask's conversation id; pass it back to continue the thread. |
| answer | string | The answer, in markdown. |
| citations[].quote | string | The exact source span backing a claim. |
| citations[].document_id | string | The document the citation came from. |
| citations[].filename | string | That document's filename. |
| verification.verdict | string | Whether every load-bearing claim checked out against its citation. |
| usage.credits_charged | number | Credits consumed by this ask. |
| waited_ms | number | How long the call actually waited before returning. |
Frequently asked questions
What if the answer is not ready in time?+
The tool returns status `processing` with the `ask_id`; call `talonic_get_answer` with it a few seconds later. Passing `conversation_id` lets follow-up questions see earlier turns.