> For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.sonicalpha.ai/llms.txt. For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.sonicalpha.ai/_mcp/server. For SDK generation or contract validation, use the authoritative OpenAPI spec at https://api.sonicalpha.ai/openapi.json — this docs domain's /openapi.json is a regenerated copy that can differ in auth modeling and strictness annotations.

# Ask vs. Search

## Agentic search — `POST /v1/insights/ask`

Send a research question; our agent decomposes it into sub-queries, runs
them against the corpus, and curates the evidence.

By default the response is **evidence-only** — `sources` with
`answer: null`, \~10–30s — the natural mode when you're combining our
evidence with other data in your own generation. Pass `"answer": true` to
also get a written, cited answer (every `[n]` maps to a source object); it
adds \~15–25s, so expect \~25–45s end-to-end.

The agent picks its own filters from the question's wording: name a show
or an episode and it scopes to that source, name an audience ("what do
*investors* think…") and it filters by speaker role, give a window
("since June") and it dates the search.

Evidence only (default):

```json
{"query": "Where do investors split on hyperscaler ASICs versus NVIDIA's GPUs — and who's making the strongest case on each side?"}
```

Full written answer:

```json
{"query": "Where do investors split on hyperscaler ASICs versus NVIDIA's GPUs — and who's making the strongest case on each side?", "answer": true}
```

Scoped to a source and a time window — no ids needed:

```json
{"query": "How have the All-In podcast's views on AI capex evolved over the last 6 months?"}
```

### Streaming

`POST /v1/insights/ask/stream` delivers the same over SSE — sub-query
events as retrieval progresses, then answer deltas when the written answer
is on. Events: `stage`, `sub_query`, `sub_query_result`, `retrieval_done`,
`sources`, `answer_delta`, `done`, `ping`, `error`.

> **Warning**
>
> Each event is a `data:` line whose JSON carries a `type` field — there are
> no named SSE `event:` frames, so parse the JSON rather than using
> `addEventListener("stage", …)`. `done` repeats the complete answer — treat
> it as the canonical text; `answer_delta` events are for display.

## Individual search — `POST /v1/insights/search`

If your AI agent does its own query decomposition and orchestration, this
is your endpoint: you set the query and filters explicitly, and you own
ranking and synthesis.

### Worked examples

Evidence pack — bearish takes on NVDA from professional investors, with
verbatim grounding:

```json
{
  "query": "NVIDIA downside risks",
  "mentions": [{"ticker": "NVDA", "sentiment": "bearish"}],
  "speaker_roles": ["investor"],
  "date_from": "2026-07-18",
  "include_quotes": true
}
```

Follow one voice — everything a show has said on a topic (`idl2iow9` is
The Real Eisman Playbook, resolved via the directory):

```json
{"query": "regional banks credit risk", "podcast_ids": ["idl2iow9"]}
```