Skip to navigation
API Referenceinsights

Ask a research question

Ask a research question in natural language.

SonicAlpha agentically searches the corpus — it decomposes the question into sub-queries, runs them, and curates the most relevant evidence into a ranked sources set. Set "answer": true to also synthesize that evidence into a written, cited answer.

The agent picks its filters from the question’s wording — there is nothing else to configure:

  • Name a show or episode (“How have the All-In podcast’s views on AI capex evolved over the last 6 months?”) and retrieval scopes to that source.
  • Name an audience (“What do operators say about data center power constraints?”) and it filters by speaker role.
  • Give a time window (“since June”, “over the last 3 months”) and it dates the search.

By default the response is evidence-only — sources with answer: null, in ~10-30s — the natural mode when you’re combining the evidence with other data in your own generation. With "answer": true, synthesis adds ~15-25s, and every [n] citation in the answer maps to a source object.

If no sources are returned, note_type says why. "source_not_covered": the question named a show or episode that isn’t in our corpus — we can’t know what it said. "no_evidence": nothing in the corpus addressed the question. When sources are returned, note_type is null.

For live progress and answer tokens over SSE, use POST /v1/insights/ask/stream. To run retrieval yourself with explicit filters, use POST /v1/insights/search.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
querystringRequired8-1000 characters

The research question, in natural language (8–1000 characters) — phrase it as a question or claim, not keywords. Scope by naming shows, audiences, or time windows directly in the wording.

answerbooleanOptionalDefaults to false

Default (false) returns the agent-curated evidence (sources) with answer: null in ~10-30s. Set true for a written, cited answer — every [n] maps to a source object; adds ~15-25s.

include_quotesbooleanOptionalDefaults to false

Attach the verbatim transcript passage to each source as quote.

Response headers

X-RateLimit-Limitinteger
Requests allowed per minute for this key's tier.
X-RateLimit-Remaininginteger
Requests remaining in the current window.
X-RateLimit-Resetinteger
Seconds until the window resets.

Response

Successful Response
querystring
The question as submitted, echoed back.
answerstring or null

Markdown synthesis with [n] citations. Null in evidence-only mode (the default — sources still returned) and when no evidence was found.

sourceslist of objects

The agent-curated evidence set, best-first.

took_msinteger

Server-side time for this request, in milliseconds. Ask runs several searches plus an optional synthesis, so expect seconds rather than milliseconds.

note_typeenum or null

Null when evidence was found. source_not_covered = a named show/episode is not in the corpus; no_evidence = covered ground, nothing matched the question.

Allowed values:
notestring or null

Display-ready sentence paired with note_type — for source_not_covered it names the missing show or episode. Null when evidence was found.

Errors

400
Bad Request Error
401
Unauthorized Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error