Skip to main content

Agent Query (Legacy)

POST /v1/agent/query is the legacy alias of POST /v1/ask: same read-only agent turn and same flat charge, but a minimal {status, answer} poll response.

POST /v1/agent/query is the legacy alias of [POST /v1/ask](post-ask). Both endpoints start exactly the same read-only agent turn over the workspace corpus, and both charge the same flat agent_ask unit (100 credits per accepted question, idempotent per turn). The difference is the result surface: the ask endpoints return the full payload with structured citations, the verification verdict, and usage, while the query poll returns a minimal {status, answer} body. New integrations should use /v1/ask; this alias remains supported for integrations built against the original surface.

The request body carries one field, query (up to 20,000 characters), and the submission answers 202 Accepted with a turnId. Poll GET /v1/agent/query/:id roughly every 2 seconds until status leaves processing. Like the ask surface, the alias requires a workspace-scoped key with the read scope, runs the turn under the least-privilege viewer role, and is tenant-isolated: a turn started by another workspace reads as 404.

POST/v1/agent/query

Request body (JSON)

query*stringThe natural-language question, up to 20,000 characters.
GET/v1/agent/query/:id

curl

Response (completed)

{
  "status": "completed",
  "answer": "You have 12 open invoices across 4 vendors. Northwind Supplies Ltd accounts for..."
}

Poll response fields

statusstringprocessing, completed, or error.
answerstringThe final answer text as markdown, including inline citation links. Empty string until the turn completes.
The answer text is identical to what /v1/ask returns; only the envelope is smaller. If you want the structured citations array, the verification verdict, or usage reporting, poll the same class of turn via POST /v1/ask instead: it is the same engine and the same price.

Errors

Error responses

400validation_errorMissing or over-length query, or the API key is not workspace-scoped.
401unauthorizedMissing or invalid API key.
402insufficient_creditsBalance cannot cover one agent_ask unit.
404not_foundOn the poll: no turn with this id exists in your workspace.

Related

Ask Your Documents
Poll & Results
Get Workspace Context
List Agent Tools