---
title: "Submit single SEC query"
method: POST
path: "/api/query"
---

# Submit single SEC query

`POST /api/query`

## Request

- Base URL: `https://financesec.api.caleralabs.com`
- URL: `https://financesec.api.caleralabs.com/api/query`
- Auth: API key in header `X-License-Key`

Queries the VLN lattice for factual answers to questions regarding SEC 10-K, 10-Q, and 8-K filings.

## Request body

- QueryRequest
  - `query` string, required: The natural language query about SEC filings.
  - `target_currency` string: Optional ISO 4217 target currency code (e.g. 'USD') to convert foreign reporting currencies.
  - `currency` string: Alias for target_currency.
  - `usd_only` boolean: When true, forces response values to be output in USD.
  - `low_tokens` boolean: When true, returns compact JSON (MCP and compact REST). Serializer only — not a second engine.

## Response `200`

Query response containing grounding results or Refusal metadata

- QueryResponse
  - `query_id` string
  - `status` 'VERIFIED_SUCCESS' | 'TENTATIVE_MATCH' | 'SAFE_REFUSAL' | 'EVENT_ACK_PENDING_FACTS' | 'EARNINGS_DAY_EMPTY' | 'OUT_OF_UNIVERSE' | 'SCHEDULE_NOT_IN_ONTOLOGY' | 'FILING_EVENT_SET': EVENT_ACK_PENDING_FACTS: 8-K Item 2.02 seen; certified metrics pending (see filing_event). EARNINGS_DAY_EMPTY / OUT_OF_UNIVERSE / SCHEDULE_NOT_IN_ONTOLOGY: typed honest silences (UX-SILENCE-TYPED-1). FILING_EVENT_SET: EDGAR-observed earnings-day set recall (Class B).
  - `source` 'LATTICE_RECALL' | 'ANALYTICAL_GATE' | 'TEMPORAL_GATE' | 'ENTITY_GATE' | 'CONFIDENCE_GATE' | 'FILING_EVENT_GATE' | 'CAPABILITY_GATE' | 'COVERAGE_GATE' | 'ONTOLOGY_GATE'
  - `coverage` object: Public coverage bound for earnings-day answers and typed silences. Never implies full-market calendar coverage.
    - `universe_description` string
    - `universe_size` integer
    - `model_generation` integer
    - `promoted_at` string, date-time
  - `answer` object
    - `value` number
    - `unit` string
    - `formatted` string
  - `filing_event` object: Structured 8-K event metadata (Item codes from SEC submissions). Present on EVENT_ACK_PENDING_FACTS. Never contains invented monetary values.
    - `form_type` string
    - `items` string[]
    - `event_type` string
    - `event_types` string[]
    - `cik` string
    - `ticker` string
    - `accession` string
    - `filing_date` string
    - `next_check` string
  - `confidence_score` number, float
  - `method` string
  - `provenance` object
    - `entity_id` string
    - `source_filing` string
    - `company` string
    - `xbrl_concept` string
    - `doc_period` string
    - `audit_hash` string
    - `original_value` string: Formatted reporting-currency value before FX conversion.
    - `original_unit` string: ISO reporting currency before FX conversion.
    - `fx_rate` string: Audited annual-average FX rate applied at inference time.
    - `fx_converted` boolean: True when the answer was converted from the filer's reporting currency.
  - `decomposition` object
    - `steps` object[]
      - `label` string
      - `value` string
    - `operator` string
    - `result` string
  - `reason` string: Human-readable refusal, typed silence, or pending-facts explanation. EVENT_ACK_PENDING_FACTS and UX-SILENCE-TYPED-1 classes use fixed product copy (not scraped from press HTML).

## Other responses

- `402`: License Required
- `429`: Rate Limit Reached

---

[API](https://skmtc.dev/caleralabs/apis/financesec-api-reference.md) · [All operations](https://skmtc.dev/caleralabs/apis/financesec-api-reference/llms.txt) · [OpenAPI document](https://skmtc.dev/caleralabs/apis/financesec-api-reference/revisions/fed76f2ec6e5?raw)