Skip to content
StockAlloy Docs

Evidence & provenance

This is the part that makes StockAlloy different. A fact without provenance is a liability in any product whose users might ask “says who?”. StockAlloy’s proof-backed facts carry an evidence link to the supporting location in the original SEC filing. Evidence fields are nullable: a value can be reconciled with filed data even when a reliable source locator is not available.

Span verification

Section titled “Span verification”

For an evidence-linked fact, extraction ties the value back to a locator in the filing document:

  1. The value is extracted from the filing’s XBRL/iXBRL structure.
  2. The extractor records a locator — for HTML tables, the table fingerprint plus row/column position and character offsets; for iXBRL, the tagged node and context reference.
  3. The displayed value at that location in the raw filing HTML is compared against the extracted value. Only facts whose value is verified at its recorded span carry an evidence link.

So a supported evidence_url is more than a filing-homepage citation: it resolves to the recorded source locator, which may be a tagged value, table region, or cell depending on the filing and locator type.

The evidence URL

Section titled “The evidence URL”

A proof-backed fact row’s evidence_url looks like:

https://stockalloy.com/api/evidence/{evidence_id}/open?cik=0000910521&accession=000091052125000017

Opening it redirects (302) to a filing viewer showing the SEC document at the supporting figure. These links are designed for direct use in a UI and currently need no API key to open. No permanence or availability SLA applies, so retain the filing accession and original SEC document URL as provenance too.

Getting the machine-readable payload

Section titled “Getting the machine-readable payload”

When you need the provenance data (not a human-clickable page) — say, to quote the source snippet in an AI answer — use the evidence export:

Terminal window
curl -s https://api.stockalloy.com/api/b2b/evidence/enriched \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $STOCKALLOY_API_KEY" \
  -d '{"ticker": "DECK", "metric_id": "us-gaap#RevenueFromContractWithCustomerExcludingAssessedTax"}'

A full evidence row:

{
  "evidence_key": "35abfabdc97f…",
  "cik": "0000910521",
  "source_accession": "000091052125000017",
  "source_form_type": "10-K",
  "source_is_amendment": false,
  "source_filed_at": "2025-05-23",
  "filing_url": "https://stockalloy.com/api/rag/filing-html/0000910521/000091052125000017?lang=en&doc_name=deck-20250331.htm",
  "document_url": "https://www.sec.gov/Archives/edgar/data/910521/000091052125000017/deck-20250331.htm",
  "evidence_url": "https://stockalloy.com/api/evidence/35abfabdc97f…/open?cik=0000910521&accession=000091052125000017",
  "viewer_url": "https://stockalloy.com/api/rag/filing-html/0000910521/000091052125000017?lang=en&doc_name=deck-20250331.htm&hl_start=1284502&hl_end=1291840",
  "snippet_text": "Net sales … 4,985,612",
  "locator_type": "html",
  "html_start_offset": 1284502,
  "html_end_offset": 1291840,
  "document_name": "deck-20250331.htm",
  "document_sequence": null,
  "section_title": "Consolidated Statements of Comprehensive Income",
  "highlight_payload_json": {
    "locator_type": "html",
    "locator": {
      "type": "html",
      "tableFingerprint": "a91c…",
      "rowIdx": 4,
      "colIdx": 2
    },
    "source_url": "https://www.sec.gov/Archives/edgar/data/910521/000091052125000017/deck-20250331.htm",
    "viewer_url": "https://stockalloy.com/api/rag/filing-html/0000910521/000091052125000017?…",
    "html_start_offset": 1284502,
    "html_end_offset": 1291840,
    "caption_text": null,
    "section_path": "Part II > Item 8",
    "nearest_heading_text": "Consolidated Statements of Comprehensive Income",
    "table_fingerprint": "a91c…",
    "row_idx": 4,
    "col_idx": 2
  }
}

(Identifiers, offsets, and snippet shortened for readability — shapes are exact.)

What each field gives you:

Field What it is
evidence_key Stable ID — joins to evidence_key on fact rows
snippet_text The source text around the value, for quoting
locator_type html (table cell), ixbrl (inline-tagged value), or xbrl (instance fact)
html_start_offset / html_end_offset Character offsets of the containing table in the filing HTML
section_title Best-effort human label: table caption, nearest heading, or section path
viewer_url Filing viewer pre-scrolled and highlighted (HTML evidence)
document_url The original document on sec.gov
highlight_payload_json Everything the viewer needs to reproduce the highlight — table fingerprint, row/column indexes, iXBRL node and context refs

Rows come back newest filing first. Filter with metric_id to keep payloads small — a full-company evidence export can be large.

Wiring it together

Section titled “Wiring it together”

Fact rows and evidence rows share keys:

facts row.evidence_key  ──►  evidence row.evidence_key
facts row.evidence_url  ──►  human-clickable proof (302 to highlighted filing)
evidence row.snippet_text / highlight_payload_json  ──►  machine-readable proof

A typical AI-product pattern:

  1. Fetch facts (/api/b2b/facts/full/by-series) and answer with the values.
  2. Render each number with its evidence_url as a “verified ✓” link.
  3. If the model needs to quote the filing, look up the evidence row and use snippet_text — never let the model paraphrase a number it can’t see.

Optional: tell us when proofs get opened

Section titled “Optional: tell us when proofs get opened”

If you want evidence-open analytics on your own integration (they appear in your portal usage), fire-and-forget:

Terminal window
curl -s https://api.stockalloy.com/api/b2b/telemetry/proof-open \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $STOCKALLOY_API_KEY" \
  -d '{"evidence_key": "35abfabdc97f…", "surface": "chat-citation"}'

Returns 202 {"ok": true} immediately and doesn’t count against your monthly quota.