Skip to main content
Schema 2 uses one refusal discriminator everywhere: 
{ "unavailable": "not_reported" }
An object is a refusal if and only if it contains unavailable. Do not replace it with 0, null, or an empty chart point. For the product decisions behind deliberately absent metrics, see why specific metrics are deliberately absent →.

​
Refusal grammar

{
  "unavailable": "valuation_operand_unavailable",
  "missing_operand": "shares_outstanding",
  "affects": ["market_cap", "price_to_book"],
  "recovery": { "action": "none", "note": "shares_outstanding is a data gap we own; no caller action serves it" }
}
Refusals can appear at four altitudes:
  • cell: one period of one field
  • field row: all requested periods for one field
  • block: one cause affects multiple fields
  • response: data itself is a refusal

​
Worked block refusal

Request schema 2 explicitly: 
curl -sS "https://api.stockcontext.com/v1/tools/stock_overview" \
  -H "X-API-Key: $STOCKCONTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schema":2,"symbol":"RIVN","detail":"core"}'
Trimmed from tests/fixtures/overview_v2/golden_overview_rivn_core.wire.json; shown values are unchanged. 
{
  "data": {
    "snapshot": {
      "period": "FY2025",
      "price": { "close": 17.18, "session": "2026-07-01" },
      "revenue": { "v": "5387000000", "d": "≈$5.387B" },
      "net_income": { "v": "-3646000000", "d": "≈-$3.646B" },
      "shares_outstanding": { "unavailable": "not_reported" }
    },
    "valuation": {
      "block_refusal": {
        "unavailable": "valuation_operand_unavailable",
        "recovery": {
          "action": "none",
          "note": "shares_outstanding is a data gap we own; no caller action serves it"
        },
        "missing_operand": "shares_outstanding",
        "affects": [
          "market_cap",
          "price_to_book",
          "price_to_sales",
          "enterprise_value",
          "ev_to_sales",
          "earnings_yield_pct",
          "book_value_per_share",
          "fcf_per_share"
        ]
      },
      "price_to_earnings": { "unavailable": "ratio_undefined_nonpositive_denominator" },
      "price_to_fcf": { "unavailable": "ratio_undefined_nonpositive_denominator" },
      "dividend_yield_pct": { "unavailable": "valuation_operand_unavailable", "missing_operand": "dividends_paid" }
    }
  }
}
The block refusal covers only fields that the missing share count would unlock. Other fields keep their own reasons.

​
Closed vocabulary

Resolve tokens with the refusal catalog: 
curl -sS "https://api.stockcontext.com/v1/tools/stock_reference" \
  -H "X-API-Key: $STOCKCONTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schema":2,"catalog":"refusal_reasons"}'
Trimmed from tests/fixtures/v2_golden/reference_refusal_reasons.json. 
{
  "data": {
    "catalog": "refusal_reasons",
    "items": [
      {
        "token": "ingestion_pending",
        "meaning": "This company is known but its filings are not ingested yet; retry later.",
        "recovery": [
          { "action": "retry", "requires": ["retry_after_s"] },
          { "action": "none" }
        ]
      },
      {
        "token": "interim_not_filed_with_sec",
        "meaning": "The filer files no interim (10-Q) reports with the SEC, so no quarterly fundamentals exist to serve — a fact about the filer (a 20-F/40-F foreign private issuer publishes interim results only as unstructured 6-K narrative, never as sub-annual XBRL), not a coverage gap.",
        "recovery": [{ "action": "none" }]
      },
      {
        "token": "invalid_request",
        "meaning": "The request failed parameter validation. errors[] names each offending param with what was given and what is expected; the recovery carries a literal corrected params fragment whenever one can be honestly derived (alias canonicalization or a documented default).",
        "recovery": [
          { "action": "supply_params", "requires": ["params"] },
          { "action": "none" }
        ]
      },
      {
        "token": "not_applicable_for_shape",
        "meaning": "The statement shape structurally lacks this line, distinct from a filer-specific not_reported omission; use the named shape-native analog when the recovery provides one.",
        "recovery": [
          { "action": "use_alternative_field", "requires": ["field"] },
          { "action": "none" }
        ]
      }
    ]
  },
  "meta": { "schema_version": "2" }
}

​
doc_extracted

Most served fundamentals are direct tagged values or exact derivations from tagged operands. doc_extracted is an exceptional provenance class for a value extracted from the filed document rather than the normal direct XBRL face path, and it is stamped so an agent does not quote it as a plain direct tagged value. Request schema 2 explicitly: 
curl -sS "https://api.stockcontext.com/v1/tools/stock_financials" \
  -H "X-API-Key: $STOCKCONTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schema":2,"symbol":"DEMO","statements":["income"],"periods":1}'
Trimmed from tests/fixtures/render_v2/golden_doc_extracted_income_core.wire.json; shown values are unchanged. 
{
  "data": {
    "statement": "income_statement",
    "shape": "operating_company",
    "periods": [{ "id": "FY2025", "start": "2024-09-29", "end": "2025-09-27", "restated": false }],
    "source": { "form": "10-K", "accession": "0001067983-25-000123", "filed": "2025-10-31" },
    "fields": {
      "revenue": ["416161000000"],
      "net_income": ["112010000000"],
      "eps_diluted": [{ "v": "7.46", "source_class": "doc_extracted" }]
    },
    "unavailable_fields": {
      "operating_income": {
        "unavailable": "verification_pending",
        "recovery": { "action": "retry", "retry_after_s": 3600 }
      }
    }
  },
  "meta": { "schema_version": "2", "as_of": { "sec": "2025-10-31" } }
}
The repo has a dedicated fixture for this class, but no committed coverage catalog with a measured frequency. Treat it as rare and explicitly stamped; do not publish a rate until the coverage catalog reports one.