---
title: "Grounded answer over the org's account-level corpus"
method: POST
path: "/ask"
---

# Grounded answer over the org's account-level corpus

`POST /ask`

## Request

- Base URL: `https://api.lochless.io/api/v1`
- URL: `https://api.lochless.io/api/v1/ask`
- Auth: HTTP bearer

Scope: ask. Rate tier: pipeline. ask, dashboards:read, dashboards:write, datasets:write, recordings:write, ingest are the available scopes. Lochless workspaces: /ask runs the same search as /context (from, to, metadata, read_limit_usd, mode; every date unless from/to narrow it), then writes a short answer from the results it kept. The response is answer (cites its evidence as [1], [2]), evidence (only the cited results: n, document_id, date, metadata, text, score), tokens_scanned, coverage {mode, documents_read, documents_total, complete} and request_id. read_limit_usd (default 1) caps what the call may cost, answer fee included: the search reads up to read_limit_usd less the fee, best-matching documents first, and a limit at or below the fee is a 400. Billed as the search's tokens scanned plus the answer fee; a call that writes no answer is not billed. A call still running after about 15 s answers 200 at once and keeps the connection open with whitespace until its JSON is ready; an error after that point is the error envelope in that body. dry_run returns documents_matched, tokens_to_scan, price_usd (what the call would cost: the scan within the limit plus the answer fee), read_limit_usd and complete, for free.

## Request body

- object
  - `query` string, required
  - `since` string, date, nullable: Lower bound on document date. Omit for the workspace default range (about one month); null searches everything Synoptic holds.
  - `until` string, date, nullable: Upper bound on document date.

## Response `200`

answer + references + a formatted text block + `scope` (the range actually read: { since, until, scanned, total, complete, bounded_by }) + `tokens_scanned` (your text this answer read, each piece once)

## Other responses

- `400`: missing query, or a since/until that is neither a YYYY-MM-DD date nor null
- `401`: missing/invalid/expired key
- `402`: spend_cap_reached (monthly spend cap reached) or add_credit (balance used up; top up in the console)
- `403`: key lacks the ask scope
- `429`: rate limited — see info.description; honour Retry-After

---

[API](https://skmtc.dev/lochless/apis/synoptic-customer-api.md) · [All operations](https://skmtc.dev/lochless/apis/synoptic-customer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lochless/apis/synoptic-customer-api/revisions/e6dee3956611?raw)