---
title: "Ask the agent (legacy alias of /v1/ask)"
method: POST
path: "/v1/agent/query"
tags: ["Agent"]
---

# Ask the agent (legacy alias of /v1/ask)

`POST /v1/agent/query`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/agent/query`
- Auth: HTTP bearer

Legacy alias of `POST /v1/ask` with a minimal response shape. Starts a read-only
agent turn (202) to poll via `GET /v1/agent/query/{id}`, which returns only
`status` and the plain `answer` text. New integrations should use `/v1/ask`,
which adds structured citations, the verification verdict, and usage. Charges the
same flat `agent_ask` unit.

**Bounded synchronous mode (`?wait=`).** Some questions are answered by a cheap
deterministic retrieval tier that runs inline, in roughly 1.5-2.5s, rather than by
the agent loop. For those, the 202 makes the caller spend a whole poll interval
rediscovering an answer the server already has. Send `?wait=<seconds>` and an
answer produced inside that budget comes back as `200` with the completed payload
— the poll body plus `turnId`. Every other outcome, including a fast-tier answer
that overran the budget and every question that goes to the agent loop, still
returns `202 { "turnId": ... }` exactly as before.

`wait` is opt-in and additive: a request without it is unchanged. It bounds how
long you block before being handed an INLINE answer; it does not cancel work
already running, and it never waits on an agent-loop turn. Overrunning the budget
costs nothing — the answer is already stored, so your first poll returns it.

## Query parameters

- `wait` number

## Request body

- object
  - `query` string, required

## Response `200`

Only when `wait` was sent and the fast retrieval tier answered inside it.
The body is the `GET /v1/agent/query/{id}` body plus `turnId`, so the same
code can read it.

- object
  - `turnId` string, uuid
  - `status` 'completed'
  - `answer` string
  - `tier` string: Which engine answered; `retrieval_fast_path` for every 200.
  - `citations` object[]
    - `quote` string
    - `document_id` string, uuid
    - `kind` 'field' | 'quote'
    - `reference` string
    - `filename` string, nullable
    - `app_url` string

## Other responses

- `202`: Turn started. The unconditional response when `wait` is absent.
- `400`: The request is invalid.
- `401`: Missing or invalid API key.
- `402`: Insufficient credits (`insufficient_credits` contract).
- `429`: Daily rate limit exceeded.

---

[API](https://skmtc.dev/talonic/apis/talonic-api.md) · [All operations](https://skmtc.dev/talonic/apis/talonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/talonic/apis/talonic-api/revisions/678fe5f8c9c3?raw)