Skip to main content
Semantic Retrieval searches company language across earnings call transcripts, SEC filings and other corpus documents. It takes a natural-language query and returns the most relevant source passages with their citations. It returns passages, not a generated answer: there is no model in the loop on the FocusAlpha side, so the caller chooses the model, the prompt and the reasoning.
Plan: Free and above · Credits: 1 per call

​
What You Can Use Semantic Retrieval For

Answer open-ended qualitative questions — what did management say about AI, how did they explain the margin move, what risks did they highlight, what was said about pricing or tariffs. Ground an LLM answer in citable source text. Compare how several companies described the same issue in the same quarter.

​
Semantic Retrieval Complements the Structured Endpoints

Retrieval and the structured datasets answer different halves of a question and are not alternatives. When the discussion concerns forward guidance, also call Management Guidance and present the parsed values alongside the supporting passages. When it concerns reported figures or KPIs, also call Reported Earnings Figures. Searching prose for a number a structured endpoint serves wastes a call and returns commentary instead of a value.

​
How Period Filters Change Retrieval Behaviour

Leave year and quarter unset unless the caller named a specific period. With no period set, the search covers the whole corpus and ranks recent documents higher. This is the correct behaviour for “latest”, “most recent”, and for any unqualified question. Setting year restricts candidates to that fiscal year. Setting both year and quarter additionally turns the recency preference off.
Do not infer a period from your own sense of the current date. A guessed year silently returns stale passages rather than an error. To learn which periods exist for a company, call the document listing first — it returns that ticker’s documents most recent first.

​
What a Retrieval Result Carries

Each returned passage carries the text itself plus the provenance needed to cite it: the company, the fiscal year and quarter, the document type, the source URL, and page numbers where the source has them. Because every passage is traceable to a specific document and period, an answer built from them can always be checked against the original.

​
Semantic Retrieval Sources

Retrieval runs over the FocusAlpha document corpus: earnings call transcripts and SEC filings and company documents. The ranking is computed by FocusAlpha; the text is the source document’s own.

​
Query Semantic Retrieval

Use the retrieve endpoint with a natural-language query. It is a POST, and it authenticates with a bearer token.
​
string
required
The natural-language search query, between 1 and 2000 characters.
​
string[]
Restrict the search to these companies.
​
integer
Restrict to this fiscal year. Omit unless the caller named a year.
​
string
Restrict to this fiscal quarter: Q1, Q2, Q3 or Q4. With year, it also disables the recency preference.
​
string[]
Restrict to these document or source types.
​
integer
Number of passages to return, between 1 and 50. The ceiling is also capped by plan — see Plans and credits.
​
boolean
Re-rank the candidate passages for relevance.
See also Earnings Call Transcripts for what the corpus contains, Document Corpus for listing and fetching a specific document, SEC Filing Items when you want a named section of a named filing rather than a semantic search, and Management Guidance for the structured half of a forward-looking question.