Filing Search

Filing search

GET/api/v2/filing-search

Coverage: US / CN / JP
Billing: 100 cr / thousand calls

Search SEC filings and Chinese and Japanese financial reports for facts buried in footnotes, tables and narrative disclosures. Semantic and keyword search returns original passages with filing context.

Filing search is state of the art on deep-research benchmarks — see how we measure it.

Beyond standard financial metrics: Find segment data, contractual commitments and operating details beyond fixed metric lists.
Verifiable source evidence: Review matching passages, sections, filing types and dates.
Fact Search: 10× the data in standard financial statements. Precisely search numbers throughout filings and inspect their original context. Use MCP filing search to retrieve reported facts and passages together. Explore Drillr MCP’s SOTA benchmark results. On this REST endpoint the facts partition requires include_facts=true; the default response returns passages only.

Same engine as MCP: this endpoint and the MCP filing_search tool run the same unified search service and return the same two partitions — passages (matching filing-text passages, always present, this endpoint's core) and facts (structured as-reported facts, not returned by default — requires include_facts=true; only companies the fact index covers have data, an empty facts partition is normal — it does not mean the company has no data, and the answer usually sits in passages).

Corpus start: the Japanese corpus effectively begins with 2024-01 (earlier years match only sporadically) and the Chinese corpus currently concentrates on recent reporting seasons — searches over earlier report periods can return empty for this reason; that is a corpus boundary, not evidence the company never disclosed.

Query parameters

Parameter	Type	Required	Description
query	string	required	Keywords or natural language (Chinese / English / Japanese); the body text is tokenized and indexed in the original language of the filing (US `en` / JP `ja` / CN `zh`, the same as the `language` response field).
ticker	string	required	A single canonical ticker. Results are routed by the company behind the ticker, so passages filed under the same company's other tickers (share classes, historical codes) can match and are returned with their own `ticker`. Cross-company or cross-market search is not supported, so query multiple companies with separate calls.
form_type	string	optional	Each market's native type, in the source encoding (US: SEC form names; JP: EDINET numeric codes / TDnet labels; CN: `annual_report` and the like). Accepts multiple comma-separated values. Default: all types within the retention window.
from	string	optional	`YYYY-MM`. Start of the reporting-period axis: a passage matches when the reporting period it belongs to overlaps [`from`, `to`]. This is not a filing-date axis — the filing-date range is always the retention window and is not exposed as a parameter.
to	string	optional	`YYYY-MM`, the end of the report period axis (with `from` it forms the interval used for the overlap test).
limit	int	optional	Maximum 50; caps the row count of each partition — `passages` and `facts` — separately. Default: 10.
include_facts	bool	optional	Whether to also return the structured `facts` partition. The default `false` returns only `passages` (this endpoint’s core answer); with `true`, facts can still be an empty array — only companies the fact index covers have data, which is normal. Accepts only `true` / `false`. Default: false.

Response fields

Field	Type	Description
passages	object[]	The matching-passage partition, always present, ordered by `score` descending; per-item fields in the “Passages — per-item fields” table below
facts	object[]	The structured as-reported facts partition, not returned by default (always an empty array when `include_facts` is omitted or `false`); requires `include_facts=true`; only companies the fact index covers have data, an empty partition is normal (the answer usually sits in `passages`), ordered by relevance; per-item fields in the “Facts — per-item fields” table below

Passages — per-item fields

Column	Type	Description
ticker	string	Canonical ticker of the filing containing the passage. Take `ticker` + `form_type` + `filing_date` to `/filings` for the official document; multiple filings can share the same date and type, so this combination is not unique; passages carry no stable id
market	string	Market code: `US` / `CN` / `JP`
form_type	string	The filing's type, in the market's native encoding (US: SEC form names; JP: EDINET numeric codes / TDnet labels; CN: `annual_report` and the like)
filing_date	date	Filing date of the filing the passage belongs to: the date it became public on the official channel
language	string	The language of the matching text: `en` / `zh` / `ja` (= mapped from market)
section	string	The section heading as written (for example `Share Repurchase Program`); null when the passage has no heading; not guaranteed to be a normalized Item number (for example `Item 1A. Risk Factors`)
snippet	string	The passage body; tables inside are converted to markdown and carried along; maximum 4000 characters, truncated beyond that. Does not contain the full document; some CN / JP passages are short (header- or caption-level fragments) — when a snippet cannot stand on its own, use the filing coordinates with `/filings` for the original text
score	number	Relevance; no absolute scale; comparable only within this partition

Facts — per-item fields

Column	Type	Description
fact_id	string	Hash id of the fact row
metric	string	The metric name as printed in the filing (for example `Revenues — Data Center`)
value	number	The numeric value; null when the as-reported figure is not a plain number — read `printed_value` then
printed_value	string	The figure as printed (for example `$89,300`)
unit	string	The unit of scale (for example `million`)
currency	string	The currency (for example `USD`)
fiscal_year	int	Fiscal year
fiscal_period	string	`Q1` / `Q2` / `Q3` / `Q4` / `H` / `9M` / `FY` — granularity, not recency
period_start	date	Report-period start (a calendar date, not a fiscal label)
period_end	date	Report-period end (a calendar date)
xbrl_concept	string	The XBRL concept (for example `us-gaap:Revenues`); often null for non-US filings
form_type	string	The filing's type, in the market's native encoding
filing_date	date	Filing date of the filing the fact comes from; the engine's fact rows currently carry no filing date (`published_at` is null) — null then, and `accession` with `/filings` locates the filing
accession	string	The filing's accession number (the official document locator)
score	number	Relevance; no absolute scale; comparable only within this partition

Request

curl -H "X-API-KEY: $DRILLR_API_KEY" \
  "https://gateway.drillr.ai/api/v2/filing-search?ticker=AAPL&query=share+repurchase&form_type=10-K&from=2025-01&to=2025-12&include_facts=true"

Response · 200

{
  "data": {
    "passages": [
      {
        "ticker": "AAPL",
        "market": "US",
        "form_type": "10-K",
        "filing_date": "2025-10-31",
        "language": "en",
        "section": "Share Repurchase Program",
        "snippet": "Share Repurchase Program During 2025, the Company repurchased 402 million shares of its common stock for $89.3 billion…",
        "score": 0.0472
      }
    ],
    "facts": [
      {
        "fact_id": "f1f97ecc9ad979fc",
        "metric": "Repurchases of Common Stock",
        "value": 89300,
        "printed_value": "$89,300",
        "unit": "million",
        "currency": "USD",
        "fiscal_year": 2025,
        "fiscal_period": "FY",
        "period_start": "2024-09-29",
        "period_end": "2025-09-27",
        "xbrl_concept": "us-gaap:PaymentsForRepurchaseOfCommonStock",
        "form_type": "10-K",
        "filing_date": "2025-10-31",
        "accession": "0000320193-25-000079",
        "score": 0.0311
      }
    ]
  }
}

No key yet? Create one under API Keys — it is shown once, so store it where your shell can read it. Connecting an agent over MCP instead? That signs in through the browser and needs no key at all.

Authentication, conventions, rate limits and error shapes are the same for every endpoint — they live on REST API.