> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beliefstate.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# get_company_facts

> Get company facts

**Get company facts** · \$0.02 per call (x402, USDC)

Retrieves retained financial facts, company references, segment metrics, operating KPIs and management guidance for one ticker. Select record\_type; use fiscal\_year/fiscal\_quarter for fiscal periods and date\_field=report for issuance. Returns typed quantities, units, basis, qualifications, filing/capture clocks and exact source support. Guidance is a forecast; reported tolerances and computed bounds stay separate. Resolve empty metric/dimension matches using available\_issuer\_selectors; missing matches do not prove no disclosure. Use get\_brief for investor views. Coverage is bounded. Issuer reads launch no paid extraction; current archive reads recheck stale metadata. as\_of and pinned reads never refresh. Continue with the returned cursor or next\_offset and unchanged snapshot, cutoff and filters.

## Input parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `cursor` | string | No | Archive continuation token; reuse with snapshot ID/hash, as\_of and unchanged filters. max length 4096 |
| `ticker` | string | Yes | |
| `as_of` | string | No | Availability cutoff, separate from event/period filters. Historical reads never refresh. |
| `snapshot_id` | string | No | Pin continuation to the returned snapshot ID; reuse with snapshot\_hash and as\_of. |
| `snapshot_hash` | string | No | |
| `filters_sha256` | string | No | Reuse the returned filter hash unchanged with continuation pages. |
| `offset` | integer | No | min 0; max 10000000 |
| `limit` | integer | No | Matching typed observations per page; default32. min 1; max 100 |
| `max_snapshot_age_hours` | number | No | Requested verification-age tolerance: default1hour for retained archives,24hours for closing-price references. Record dates and publication cadence are separate. max 87600 |
| `date_from` | string | No | Inclusive native date lower bound, selected by date\_field. |
| `date_to` | string | No | Inclusive native date upper bound, selected by date\_field. |
| `date_field` | "period" \| "report" | No | Date meaning; defaults to period for facts/macro/holdings/returns, event for insider trades, observation for options/short volume, scheduled for calendar. |
| `metrics` | array of string | No | |
| `taxonomy` | string | No | max length 128 |
| `unit` | string | No | max length 64 |
| `family` | "financial" \| "market\_reference" | No | |
| `period_start` | string | No | Exact reported fact period start; distinguish quarterly and annual facts with the same end date. |
| `reported_quarters` | integer | No | min 0; max 4 |
| `record_type` | "financial\_fact" \| "financial\_statement" \| "company\_reference" \| "segment\_metric" \| "operating\_kpi" \| "management\_guidance" | No | Select financial\_fact, financial\_statement, company\_reference, segment\_metric, operating\_kpi or management\_guidance. Issuer metrics use selected admitted SEC disclosures, not complete history; guidance is a forecast, not an actual result. |
| `basis` | "GAAP" \| "IFRS" \| "non\_gaap" \| "operational" \| "unknown" | No | Accounting or operating basis; requires an issuer-metric record\_type. |
| `dimension` | string | No | Issuer-reported segment, product or geography label substring; requires an issuer-metric record\_type. max length 128 |
| `period_label` | string | No | Exact returned fiscal period label; requires an issuer-metric record\_type. Use for guidance targets whose calendar dates are unknown; date\_field=report instead filters issuance dates. max length 128 |
| `fiscal_year` | integer | No | Issuer's stated fiscal year; requires an issuer-metric record\_type. Does not imply calendar-year dates. min 1900; max 2200 |
| `fiscal_quarter` | integer | No | Issuer's stated fiscal quarter, 1 through 4; use with fiscal\_year for requested fiscal periods. min 1; max 4 |

## Transports

* **MCP:** `tools/call` with name `get_company_facts` at `https://beliefstate.ai/mcp` (account access) or `https://beliefstate.ai/v1/research/mcp` (wallet access). See [MCP integration](https://docs.beliefstate.ai/guides/mcp-server.md).
* **x402 HTTP:** `POST https://beliefstate.ai/v1/research/get_company_facts` with the arguments as a JSON body. An unpaid request returns an HTTP 402 payment quote.

## Example request

### MCP

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_company_facts",
    "arguments": {
      "ticker": "NVDA"
    }
  }
}
```

### x402 HTTP

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
curl --request POST \
  --url 'https://beliefstate.ai/v1/research/get_company_facts' \
  --header 'Content-Type: application/json' \
  --data '{"ticker":"NVDA"}'
```

The example shows request shape only. Identifiers are placeholders, not records.

## Related

* [All research tools](https://docs.beliefstate.ai/tools/index.md)

*Contract version: 2026-11-08. Input parameters and tool metadata come from the
shared executable catalog. REST API version: v1.*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.