API Reference

Documents

Browse the corpus directly. List the documents available for a ticker, fetch a single document's metadata, or read its full text as ordered segments — useful for building a source viewer alongside Retrieve.

These read-only endpoints expose the same corpus that Retrieve searches. A typical flow: retrieve cited chunks, take the source.documentId from a chunk, then call these endpoints to show the surrounding document or highlight a span. All three require the same API key as every other request — passed as Authorization: Bearer (shown below) or an X-API-Key header.

List documents by ticker#

GET/v1/documents/by-ticker/:ticker

Returns the documents on file for a ticker, most recent first (reverse-recency). Use the query parameters to narrow by period and to page through results.

Path parameters

tickerstringrequired

US ticker symbol, e.g. NVDA.

Query parameters

yearnumberoptional

Restrict to a fiscal year, e.g. 2025. Integer in the range 2000–2100; out-of-range or non-integer values return 400.

quarter"Q1" | "Q2" | "Q3" | "Q4"optional

Restrict to a fiscal quarter. Combine with year for a single period.

limitnumberoptional

Maximum number of documents to return for this page. Integer 1–100; defaults to 20. Values outside this range return 400.

offsetnumberoptional

Number of documents to skip, for pagination.

curlbash

curl "https://api.focusalpha.ai/v1/documents/by-ticker/NVDA?year=2025&limit=5" \
  -H "Authorization: Bearer fa_live_your_key_here"

response.jsonjson

{
  "documents": [
    {
      "id": "doc_8f2a1c",
      "documentTitle": "NVIDIA Q1 2025 Earnings Call",
      "documentType": "earnings_call",
      "ticker": "NVDA",
      "year": 2025,
      "quarter": "Q1",
      "filingType": null,
      "sourceUrl": null,
      "status": "indexed"
    }
  ],
  "meta": { "total": 18, "limit": 5, "offset": 0, "latencyMs": 24 }
}

Get a document#

GET/v1/documents/:id

Fetch a single document’s metadata by id. Returns 404 if no document with that id exists in the corpus.

curlbash

curl "https://api.focusalpha.ai/v1/documents/doc_8f2a1c" \
  -H "Authorization: Bearer fa_live_your_key_here"

response.jsonjson

{
  "document": {
    "id": "doc_8f2a1c",
    "documentTitle": "NVIDIA Q1 2025 Earnings Call",
    "documentType": "earnings_call",
    "ticker": "NVDA",
    "year": 2025,
    "quarter": "Q1",
    "filingType": null,
    "sourceUrl": null,
    "status": "indexed"
  },
  "meta": { "latencyMs": 11 }
}

document#

idstringrequired

Stable document identifier.

documentTitlestringrequired

Human-readable document title.

documentTypestringrequired

Document type, e.g. "earnings_call" or "sec_filing".

tickerstring | nulloptional

Company ticker.

yearnumber | nulloptional

Fiscal year of the document.

quarterstring | nulloptional

Fiscal quarter, e.g. "Q1".

filingTypestring | nulloptional

The SEC filing type for filing documents, e.g. "10-K"; null for transcripts.

sourceUrlstring | nulloptional

Link to the primary source document.

statusstringoptional

Ingestion status of the document, e.g. "indexed".

Read a document’s segments#

GET/v1/documents/:id/segments

Returns the document’s full text as ordered segments — speaker turns for the transcript — with character offsets. This is the read-the-whole-document counterpart to the per-chunk source.segments on Retrieve.

Query parameters

limitnumberoptional

Maximum number of segments to return, in sequence order. Integer 1–100; defaults to 20. Values outside this range return 400.

curlbash

curl "https://api.focusalpha.ai/v1/documents/doc_8f2a1c/segments?limit=200" \
  -H "Authorization: Bearer fa_live_your_key_here"

response.jsonjson

{
  "segments": [
    {
      "id": "seg_0",
      "documentId": "doc_8f2a1c",
      "content": "Thanks, and good afternoon, everyone.",
      "sequence": 0,
      "speakerName": "Colette Kress",
      "speakerTitle": "EVP and CFO",
      "charStart": 0,
      "charEnd": 37
    }
  ],
  "meta": { "total": 142, "latencyMs": 31 }
}

segment#

idstringrequired

Segment identifier within the document.

documentIdstringrequired

Id of the parent document.

contentstringrequired

The segment text.

sequencenumberrequired

Zero-based position of the segment within the document, in reading order.

speakerNamestring | nulloptional

The speaker for this turn, where known.

speakerTitlestring | nulloptional

The speaker's role/title, where known.

charStartnumberrequired

Start character offset of this segment within the reconstructed document text.

charEndnumberrequired

End character offset (exclusive) of this segment.

How offsets are computed

charStart and charEnd are computed at read time by concatenating the segments in sequence order, joined with a \n\n separator. They are positions into that reconstructed text — not stored columns — so use the same join when you reassemble the document, and treat charEnd as exclusive.

Errors#

These endpoints use the standard envelope ({ success: false, error: {...} }). Beyond the usual 401, invalid query parameters (e.g. limit outside 1–100, an out-of-range year, or an unknown parameter) return 400, and a request for a missing document id returns 404. See Errors.

PreviousRetrieval

Next Account