Ask

Answers a question from your own records — “which of these jackets are waterproof?” — and shows where each part of the answer came from.

One call finds the records that match, writes an answer using only those records, and returns both.
Where search gives you a ranked list, Ask gives you a sentence with a citation on every part of it.
The citations are checked against the records actually found — see below.

Asking your own data a question, without writing anything

The console’s Playground is the quickest way to see answers built out of your records. Point Focus at one list, ask in a sentence, and the answer comes back with what it read and quoted. Note what it does when the records do not answer the question: it says so, and shows the one line it did find, rather than writing something that sounds right. The ask endpoint below is that behaviour as a single call you can put in your own product.

The console Playground answering a question from one list's records

Before you start: Ask needs a judge

Ask runs the model on your provider API key, borrowed from one of your judges. The answer costs money at your own provider, on your own bill.
One judge → Ask uses it, pass nothing. Several → name the one to answer with. None → the call tells you so.
Your API key needs the ask:run permission, separate from search-result:read so a key that can search cannot also spend money at your provider. A key limited to one list can ask about that list only.

The request

The question goes in the body, because a question is a sentence, not a keyword:

POST https://api.searchstack.dev/ask/{account}/{list}/{version}

{
  "question": "which of these jackets are waterproof and in stock?",
  "size": 8,
  "filter": "category eq 'outerwear'"
}

Setting	What it does
`size`	How many records to answer from. 8 by default, capped at 20.
`filter` / `radius`	Answer only from the records you care about.
`judge`	Which model and key answers, when you have more than one judge.
`instructions`	The answer’s shape or tone. Applied only where it does not conflict with the rules tying the answer to your records; those win.

A question can cover every list in a group with the /ask/group/{account}/{group}/{version} form; latest works there as it does for search.

What comes back

answer — carrying [^1] markers.
citations — each marker lines up with one in the answer and carries the record’s id, so you can show the record beside the sentence it supports.
results — the records the answer was built from, exactly as search returns them.
query_id — the id of the search behind the answer, so click-through analytics work as for search.
Every field and default: API reference, under Ask.

When it will not answer

A refusal is a normal, successful response — HTTP 200, answered: false — still carrying the records that matched.

`reason`	What happened
`no_results`	Nothing matched, so there was nothing to answer from. No model is called, so a hopeless question costs you nothing.
`no_grounding`	Records matched, but nothing in them answers the question — or the answer cited nothing real.
`blocked`	Your model provider refused, or could not produce an answer in the required format.

How the citations are guaranteed

The model is given the found records, numbered, and told to cite by number and never write a link, an id or a URL. Every number is then checked against the records actually found:

A number matching no found record is removed from the answer and never returned as a citation.
The id, name, list and link on a citation are copied from the record itself, never from the answer.
An answer left with no valid citation becomes a refusal, however convincing it reads.

What it costs, and what limits it

One Ask is one search plus one model call at your provider.
That call’s size is fixed by us, not the caller: at most 20 records, each trimmed to about 1,500 characters, a total budget of roughly 24,000 characters, and a short answer.
The per-minute rate limit is the tighter of the two we apply — the same one image search uses.

Ask versus search

Reach for search when you want records to show: fast, free, returns everything. Reach for Ask when the useful output is a sentence with the proof alongside it — a support answer, a summary across records, a yes-or-no about your own data.