Filings
TOOLfiling_search
Search one company’s filings and get two partitions in one call: structured as-reported facts, and the filing text itself.
- Coverage
- US / CN / JP
- Billing
- Per call · 0.1 cr / call
Input parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | required | Natural-language query — a metric, a concept or a section name. Run a few phrasings rather than one broad one. |
| ticker | string | required | One ticker, canonical or historical. Resolve company names with ticker_lookup first. |
| period_start | date | optional | Calendar start date, YYYY-MM-DD. Calendar, not fiscal; a fiscal period’s dates are in financial_statements. |
| period_end | date | optional | Calendar end date, YYYY-MM-DD. Must not precede period_start. |
| as_of | date | optional | Publication cutoff, YYYY-MM-DD. Rows with no publication date still appear — not a strict point-in-time snapshot. |
| top_k | int | optional | 1–30. Counts rows per partition, so the last fact group may be partial. Default 10. |
| period_type | string | optional | instant or duration. |
| fiscal_period | string | string[] | optional | Q1, Q2, Q3, Q4, H, 9M or FY, or a list of those. Granularity, not recency. |
Example
Arguments
{
"query": "data center revenue",
"ticker": "NVDA",
"fiscal_period": "FY",
"top_k": 2
}Response
## Facts
## Group 1 · Data Center
### 1.1 · fact_id: `f1f97ecc9ad979fc`
value: **115,186 million currency USD**
metric: Revenues — Data Center — Data Center
period: FY2025 · 2024-01-29 → 2025-01-26
context: Data Center · Year Ended Jan 26, 2025 (In millions)
xbrl_concept: `us-gaap:Revenues`
source: 10-K · 2026-02-25 · accession `0001045810-26-000021`
## Passages
---
[1] SIGNATURE
Filing: 8-K | 2026-05-20 | FY2027 Q1 | (2026-01-31 ~ 2026-04-30)
… Under the previous sub-markets, Data Center compute revenue was a record
$60.4 billion, up 77% from a year ago and up 18% sequentially. Data Center
networking revenue was a record $14.8 billion, up 199% from a year ago …Trimmed: One fact group and one passage shown; the passage is cut mid-paragraph.
Limits
| Limit | Value | Past it |
|---|---|---|
| top_k | 1–30, default 10 | Rows per partition |
| Passages rendered | 10 most relevant | Header says "(top 10 of N)" |
| Tickers per call | 1 | Call once per company |
Errors
Invalid arguments are refused before the tool runs; the rest arrive as a tool failure whose text is the message. The four shapes are on MCP server.
| When | You get | Do |
|---|---|---|
| Ticker not resolvable | "Algorithm API error: 400 … could not be resolved" | Resolve with ticker_lookup, pass the canonical symbol |
| Facts empty | Normal — passages still returned | Read Passages |
| Both partitions empty | "No structured facts and no filing passages matched" | Rephrase, widen the period |
| Bad date or top_k | Invalid arguments | YYYY-MM-DD; 1–30 |
| period_start after period_end | "period_start must be on or before period_end" | Swap them |
Notes
- An empty Facts partition is normal and does not mean no data. The fact index covers a subset of companies; the passage corpus covers thousands. When Facts is empty, the figure is usually in Passages.
- Restatement lineage — whether a figure was later revised, and from what — exists only in Facts. No single passage carries it.
- There is no "latest" parameter. Period filters match by interval overlap, so pass an explicit window for the most recent figure.
Endpoint, client setup and billing are common to all tools. For details, please refer to MCP server.