FocusAlphaDocs
Get key
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.

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.
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.
offsetnumberoptional
Number of documents to skip, for pagination.
curl
curl "https://api.focusalpha.ai/v1/documents/by-ticker/NVDA?year=2025&limit=5" \
  -H "Authorization: Bearer fa_live_your_key_here"
response.json
{
  "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.

curl
curl "https://api.focusalpha.ai/v1/documents/doc_8f2a1c" \
  -H "Authorization: Bearer fa_live_your_key_here"
response.json
{
  "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
Currently "earnings_call".
tickerstring | nulloptional
Company ticker.
yearnumber | nulloptional
Fiscal year of the document.
quarterstring | nulloptional
Fiscal quarter, e.g. "Q1".
filingTypestring | nulloptional
Reserved for future document types; 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.
curl
curl "https://api.focusalpha.ai/v1/documents/doc_8f2a1c/segments?limit=200" \
  -H "Authorization: Bearer fa_live_your_key_here"
response.json
{
  "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 and 429, a request for a missing document id returns 404. See Errors.