Skip to navigation
Concepts

Ask vs. Search

Two ways to consume the corpus

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):

{"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:

{"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:

{"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.

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:

{
  "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):

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