Search & documents

These endpoints cover the retrieval corpus: semantic search that returns source-attributed passages, metadata browsing over the underlying documents, and your own usage summary. In the dashboard’s dataset list this is Earnings call transcripts (retrieve via MCP). Responses use the standard { ...payload, meta } envelope, and errors use the standard error envelope described in Errors. POST /v1/retrieve is rate-limited per plan and returns 429 when the per-minute limit is exceeded.

POST /v1/retrieve

Semantic retrieval over the document corpus — SEC filings and earnings-call transcripts. Send a natural-language query and receive ranked, source-attributed passages (“chunks”). The response is the product: cited chunks you can feed directly to an LLM or display with citations — never a generated answer. Plan: Free and above · Credits: 1 per call · Rate limited: yes (429 on breach)

string

required

The natural-language search query. 1–2,000 characters.

object

Optional filters narrowing the search.

tickers (string[]) — up to 25 trading symbols, each ≤10 characters.
year (integer) — calendar year, 2000–2100.
quarter (string) — one of Q1, Q2, Q3, Q4.
source_types (string[]) — up to 10 document-type filters.

integer

Number of chunks to return, 1–50. Clamped to your plan’s ceiling: Free 10, Professional 25, Fund 50.

boolean

When true, rerank results for higher precision.

boolean

default:"false"

When true, each chunk’s source.segments is populated with the source document’s ordered segments (with character offsets) for citation highlighting. Off by default.

curl -X POST https://api.focusalpha.ai/v1/retrieve \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What did management say about AI infrastructure demand?",
    "filters": { "tickers": ["NVDA"], "year": 2026, "quarter": "Q2" },
    "top_k": 5,
    "rerank": true
  }'

{
  "chunks": [
    {
      "id": "chunk_01",
      "text": "Demand for our data center platform continued to outpace supply...",
      "score": 0.31,
      "evidenceText": "Demand for our data center platform continued to outpace supply.",
      "source": {
        "documentId": "6f0c2a1e-...",
        "documentTitle": "NVDA Q2 2026 Earnings Call",
        "documentType": "transcript",
        "ticker": "NVDA",
        "year": 2026,
        "quarter": "Q2",
        "filingType": null,
        "sourceUrl": "https://...",
        "pageNumbers": []
      }
    }
  ],
  "meta": {
    "total": 5,
    "periodMismatch": null,
    "requestId": "req_a1b2c3d4e5f60718"
  }
}

Leave filters.year and filters.quarter unset unless you genuinely need a specific period. A guessed period silently returns stale passages rather than an error. Use GET /v1/documents/by-ticker first to see which periods exist.

score is a cosine distance — lower means more similar. When the exact requested period was unavailable, meta.periodMismatch carries a { requested, served, message } notice instead of failing.

This endpoint returns source passages, not a generated answer. Unknown body properties are rejected with a 400 — check spelling of top_k, source_types, and other snake_case fields.

GET /v1/documents/by-ticker/{ticker}

Lists corpus documents for a ticker in reverse-recency order, paginated with limit + offset. The ticker is expanded to every symbol the company is known by, so a renamed listing still returns its history. Plan: Free and above · Credits: 1 per call

integer

Filter to one calendar year (2000–2100).

string

Filter to one quarter: Q1, Q2, Q3, or Q4.

integer

default:"20"

Page size, 1–100.

integer

default:"0"

Number of rows to skip. Increment by limit to paginate.

curl "https://api.focusalpha.ai/v1/documents/by-ticker/AAPL?year=2026&limit=5" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"

{
  "documents": [
    {
      "id": "6f0c2a1e-...",
      "documentTitle": "AAPL Q2 2026 Earnings Call",
      "documentType": "transcript",
      "ticker": "AAPL",
      "year": 2026,
      "quarter": "Q2",
      "filingType": null,
      "sourceUrl": "https://...",
      "status": "indexed"
    }
  ],
  "meta": { "total": 12, "limit": 5, "offset": 0, "latencyMs": 42 }
}

This is the reliable way to discover which periods exist for a company. Call it before pinning a year/quarter in /v1/retrieve, instead of assuming a period from today’s date.

GET /v1/documents/{id}

Fetches metadata for a single document by its id. Plan: Free and above · Credits: 1 per call — refunded automatically if the document is not found (404)

curl https://api.focusalpha.ai/v1/documents/6f0c2a1e-... \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"

{
  "document": {
    "id": "6f0c2a1e-...",
    "documentTitle": "AAPL Q2 2026 Earnings Call",
    "documentType": "transcript",
    "ticker": "AAPL",
    "year": 2026,
    "quarter": "Q2",
    "filingType": null,
    "sourceUrl": "https://...",
    "status": "indexed"
  },
  "meta": { "latencyMs": 18 }
}

GET /v1/documents/{id}/segments

Returns the ordered segments of one document — for transcripts, one segment per speaker turn, with speaker attribution and character offsets suitable for highlighting. Plan: Free and above · Credits: 1 per call

integer

default:"20"

Number of segments to return, 1–100.

curl "https://api.focusalpha.ai/v1/documents/6f0c2a1e-.../segments?limit=3" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"

{
  "segments": [
    {
      "id": "seg_...",
      "documentId": "6f0c2a1e-...",
      "content": "Good afternoon, everyone, and thanks for joining us...",
      "sequence": 0,
      "speakerName": "Tim Cook",
      "speakerTitle": "CEO",
      "charStart": 0,
      "charEnd": 54
    }
  ],
  "meta": { "total": 87, "latencyMs": 33 }
}

charStart/charEnd are computed from segment content and order at read time, so they always match the text exactly.

GET /v1/usage

Returns your own usage summary over a time window — total requests, chunks returned, and a per-key breakdown. Scoped to the account behind the API key you call with. Plan: Free and above · Credits: free (not metered)

string

ISO-8601 start of the window. Defaults to the start of the current month (UTC).

string

ISO-8601 end of the window. Defaults to now.

curl "https://api.focusalpha.ai/v1/usage" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"

{
  "period": { "from": "2026-08-01T00:00:00.000Z", "to": "2026-08-27T14:00:00.000Z" },
  "totals": { "requests": 412, "chunksReturned": 1968 },
  "byKey": [
    { "prefix": "fa_live_7Fb3", "requests": 412 }
  ]
}

Overview

SEC filings & financials

Companies & screening

Markets & ownership

Events & news

International

Service

Search & documents

POST /v1/retrieve

GET /v1/documents/by-ticker/{ticker}

GET /v1/documents/{id}

GET /v1/documents/{id}/segments

GET /v1/usage

​POST /v1/retrieve

​GET /v1/documents/by-ticker/{ticker}

​GET /v1/documents/{id}

​GET /v1/documents/{id}/segments

​GET /v1/usage

POST /v1/retrieve

GET /v1/documents/by-ticker/{ticker}

GET /v1/documents/{id}

GET /v1/documents/{id}/segments

GET /v1/usage