FinancialFilings

Experimental endpoint — the response schema may change without an API version bump.

Returns standardized financial KPIs for a company as a structured document: a company envelope containing periods, each holding its Income Statement, Balance Sheet and Cash Flow statements, each holding line_items.

When several filings report the same period, the candidates are ranked and one statement is selected. A filing the company reports its own financials in beats one it does not, such as an employee benefit plan's Form 11-K or a filing notice. A statement in the currency the company reports in beats an off-currency one, which is usually a subsidiary's filing that resolved to the parent. A complete statement beats a fragment, such as the single restated line in an amendment. Only then does the most recently published filing win. A selected statement denominated in a currency other than the company's carries currency_mismatch: true.

Currency is as presented, and is never converted. currency is the currency the statement is denominated in as the filer presented it - the presentation currency, not the functional currency, which we do not capture. No figure in this payload is ever translated into another currency at any rate, and value being in absolute units makes values comparable across scales, not across currencies. A company that re-presents in a new currency therefore produces a series whose units change partway through, with no restatement of the earlier years:...

When to use this tool: Use to get standardized financial line items (income statement, balance sheet, cash flow) for a company. Data is deduplicated across filings — the most recently published filing wins. SOURCING: attribute every figure to its fiscal period + period_end_date and reporting currency. GROUNDEDNESS (critical): report ONLY values present in the periods this call returns. If period_count is 0 or periods is empty, FinancialFilings has no structured financials for this company yet (common for US/SEC issuers — structured data is currently ESEF/EU-derived and being expanded). Do NOT stop and do NOT estimate — FALL BACK to the filing: call filings_list for this id filtered with type (or types) to an annual report (e.g. 10-K, 20-F, or the local annual type) with ordering='-release_datetime' and page_size=10, take the NEWEST row (do not gate on processing_status — it can be null, and null means unknown), retrieve it with filings_markdown_retrieve, and read the figures directly from the filing body — citing the filing type, date, and fiscal period. Never estimate, recall a figure from training knowledge, or attach a citation to a number you did not read from a tool result this session. PROVENANCE: treat a figure as as-reported ONLY when raw_value AND scale are BOTH non-null. If either is missing there is no as-reported pair, so you cannot assert the figure was read off the page — do not present it as sourced from the filing. An arithmetic tie between totals does NOT establish provenance: a computed figure is chosen to make the totals tie. To verify a figure, take source_filing.id (or the sources entry with is_selected: true, field filing_id) — it is already in this response, so no filings_list call is needed — and read it with filings_markdown_retrieve (no processing_status check first: the field is not on this response; a not-found error means no Markdown is available for that filing — do not promise it will appear). LINE ITEM CODES: line_items takes exact lower-case snake_case codes, comma-separated (not ;); an unknown code is a 400 naming it. The codes most often guessed wrong: net_income -> net_income_loss, operating_income -> operating_income_loss, total_debt -> total_debt_bs, free_cash_flow -> levered_free_cash_flow_cf, capital_expenditure -> capital_expenditure_cf, operating_cash_flow -> cash_from_operations, eps -> basic_eps / diluted_eps, cash -> cash_and_equivalents. Not sure of a code? Omit line_items to get every line item.

When NOT to use this tool: Don't use for filing documents or markdown content — use filings_list + filings_markdown_retrieve. Don't use without resolving the company ID first via companies_list.

Examples:

• Munich Re 2024 income statement -> id=, fiscal_year=2024, statement_type='IS' (Use depth + parent_code to render Capital IQ-style hierarchy)

• Compare EBITDA across 3 companies -> id=, statement_type='IS', line_items='ebitda' (Call in parallel for each company. Always show currency.)

[Server current date: 2026-10-09 — treat this as today.]

Retrieve a paginated list of companies.

When to use this tool: Use as the first step to resolve a company name, ticker, or partial match to a FinancialFilings internal ID. Required before calling any per-company tool (financials, filings, watchlist). CONFIRM the match — state the resolved company's full name and country before reporting data ("Apple" can surface "Apple Hospitality REIT"). PEER / SCREENING LISTS: include ONLY companies whose requested data you actually retrieved this session; if a candidate's data comes back empty, mark it "no data available" or drop it — never invent a figure to complete the list. A short honest list beats a long fabricated one.

When NOT to use this tool: Don't use if you already have a company ID from a previous call. Don't use for ISIN lookups — use isins_retrieve instead.

Examples:

• Find Apple -> search="Apple" (Inspect results — 'Apple Inc.' vs 'Apple Hospitality REIT')

• German automotive companies -> countries="DE", sector="C" (ISIC Section C = Manufacturing)

[Server current date: 2026-10-09 — treat this as today.]

Calculates the expected release window for the next annual report based on historical filing patterns.

[Server current date: 2026-10-09 — treat this as today.]

Reconcile a list of your identifiers against our coverage in one request.

Each row may carry any mix of isin, lei, cik, ticker and name, plus an optional opaque ref echoed back so you can join results to your source rows. Results are returned in input order.

Resolution order — ISIN, LEI, CIK, ticker, venue ticker, name. First hit wins, but every identifier you supply is evaluated: if two of them resolve to different companies the row comes back ambiguous with identifier_conflict and both in candidates, rather than us silently picking one.

A name alone never returns matched. No matter how close the match, a name-only row caps at ambiguous and hands you candidates to choose from. Names are not identifiers, and asserting a match on one is how filings end up attached to the wrong issuer.

Venue-ticker matches are qualified, not asserted. A ticker that only resolves through our security-listing data is cross-checked against the name you supplied. If they disagree you get ambiguous + name_disagrees; if you supplied no name we cannot corroborate at all, so you get matched carrying security_listing_unverified — trust that bucket accordingly.

Billing — one request is one call against your quota, whatever the row count. Rows we do not cover are not billed differently from rows we do.

Maximum 500 rows per request. Up to 50 rows per request reach the name lookup; beyond that a row carrying only a name returns not_covered with `name_t...

When to use this tool: Use when the user hands you a list of identifiers — a spreadsheet column, a portfolio, a peer set — and you need FinancialFilings IDs for all of them. One request covers up to 500 rows and costs one call against quota regardless of row count, so it is far cheaper than a companies_list search per name. Pass an opaque ref per row to join the results back to the user's own rows. Act only on rows whose status is matched; for ambiguous, ask the user to choose from candidates rather than picking one yourself.

When NOT to use this tool: Don't use for a single company — companies_list (name/ticker) or isins_retrieve (ISIN) is one hop and returns richer match context. Don't send more than 50 name-only rows in one request: rows past that cap return not_covered with name_tier_skipped, so split name-heavy batches.

Examples:

• Here are 40 tickers from my portfolio — pull their latest filings -> rows=[{"ref": "row-1", "ticker": "GOOG", "name": "Alphabet Inc."}, ...] (Resolve every ID in one call, then fan out to filings_list per matched row)

• Do you cover these ISINs? -> rows=[{"isin": "US5949181045"}, {"isin": "US0378331005"}] (not_covered means no coverage — say so; never substitute a near match)

[Server current date: 2026-10-09 — treat this as today.]

Retrieve detailed information for a single company by its internal ID.

When to use this tool: Use to get full company metadata (LEI, description, address and city, social links, stock exchanges, indices) after resolving the ID via companies_list.

When NOT to use this tool: Don't use for financial data — use companies_financials_retrieve. Don't use just to confirm a company exists — companies_list already returns enough for identification.

Examples:

• What's the LEI for ASML? -> id= (Returns lei field)

[Server current date: 2026-10-09 — treat this as today.]

Retrieve the 11 standardized disclosure types (categories) defined by the FRCF.

[Server current date: 2026-10-09 — treat this as today.]

Retrieve a paginated list of regulatory filings.

When to use this tool: Use to search and filter regulatory filings across companies. Supports filtering by company, filing type, category, country, date range. Returns metadata — not filing content. VIEW: both views carry processing_status. view='full' adds more metadata fields and is larger, so pass it only when you need those fields. Never gate filing selection on processing_status: a null value means unknown, not "no markdown". LINKS for a human: viewer_url, except when processing_status is PENDING/QUEUED/PROCESSING/FAILED/SKIPPED and file_extension is not PDF/HTML/HTM/XHTML — that page is empty, so give the raw file link (document_url on default rows, document on view=full rows); if it is null, say no file link is available yet. A null status is not a reason to switch.

When NOT to use this tool: Don't use to get filing content — use filings_markdown_retrieve after getting the filing ID. Don't use for financial KPIs — use companies_financials_retrieve.

Examples:

• Apple's most recent 10-K -> company=, type='10-K', ordering='-release_datetime', page_size=1 (type takes ONE filing-type code and is jurisdiction-specific; types takes a comma-separated list. For cross-jurisdiction queries filter by category / categories (numeric FilingCategory ids) instead.)

• All insider transactions at Tesla in the last 30 days -> company=, type='DIRS', release_datetime_from='T00:00:00Z' (release_datetime_from is a date-TIME (YYYY-MM-DDTHH:MM:SSZ). Compute the cutoff from the current date given in this tool's description — never hardcode one.)

[Server current date: 2026-10-09 — treat this as today.]

Retrieve the raw processed content of a single filing in Markdown format.

When to use this tool: Use to get the full text of a filing as Markdown. Supports pagination via offset/limit for long documents. Start with offset=0 and repeat with increasing offsets until the truncation marker is gone, you have found what you were asked for, or you have made 10 calls — whichever comes first. Stop at the cap and say the document was truncated rather than paginating a long filing indefinitely against the request budget.

When NOT to use this tool: Don't use to search for filings — use filings_list first. Not every filing has Markdown content. If a filings_list row shows a processing_status other than "COMPLETED", that filing has no Markdown available (it may still be processing, or may never get any) — if the user asked for THAT filing (e.g. the latest), say so rather than silently answering from an older one. If the field is null or absent, that means unknown — call this tool anyway; a not-found error means no Markdown is available for that filing (do not promise it will appear), while any other error is about access or availability.

Examples:

• Show me Apple's 10-K risk factors -> filing_id=, offset=0, limit=50000 (Summarize specific sections — don't dump the whole document)

  Returns the full processed Markdown content of a filing in pageable chunks. For long filings, call this tool repeatedly with increasing offset values until the response no longer contains the truncation marker. Use a limit of 50000 chars (default) for most LLM context windows; the per-call cap is 150000 chars for the whole result (Claude.ai's documented tool-result ceiling), so a full-size slice is trimmed by the length of the header.

[Server current date: 2026-10-09 — treat this as today.]

Search a filing's processed Markdown for query and return ONLY the matching passages with their character offsets — use this INSTEAD of paging a long filing to find a specific figure, line item, or section (e.g. query='total revenue'). Case-insensitive. Each hit shows ~440 chars of context and an offset you can pass to filings_markdown_retrieve to read more around it.

[Server current date: 2026-10-09 — treat this as today.]

Retrieve detailed information for a single filing by its ID.

When to use this tool: Use to get full metadata for a single filing — source URL, PDF link, viewer URL, classification confidence, fiscal period. Call after filings_list when you need details beyond the list view. SHAREABLE LINKS: when a human needs to open the filing, hand them a PUBLIC link — viewer_url (the interactive web page) or document (the raw PDF/ZIP). NEVER give a user an /api/... URL — including the paginated next/previous links — those require credentials and 403 for an unauthenticated person. Filing CONTENT for you (the model) comes from filings_markdown_retrieve(filing_id), not from a URL.

When NOT to use this tool: Don't use for the actual filing content — use filings_markdown_retrieve. Don't use to search for filings — use filings_list.

Examples:

• Show me the source PDF for this filing -> id= (Returns document (raw PDF/ZIP URL) and proxy_url (rendered))

• Send me a link to read this filing -> id= (Share viewer_url (public web page) — never the /api/ markdown URL)

[Server current date: 2026-10-09 — treat this as today.]

Retrieve a paginated list of all available filing types.

When to use this tool: Call when the user names a form or report type that is not in the filing-type table in the instructions, to find its FinancialFilings code before filtering filings_list. A regulator's own form name (10-Q, 8-K, 6-K) is not a code: it goes on filings_list source_filing_type.

[Server current date: 2026-10-09 — treat this as today.]

The full 30-code filing-type taxonomy (codes + categories). Read before filtering filings by type — especially for ESG, governance, M&A, dividends, transcripts, or any type beyond 10-K / IR / ER / MDA / DIRS.

[Server current date: 2026-10-09 — treat this as today.]

The ISIC industry hierarchy (sections/divisions/groups/classes) and how to screen peers. Read for any sector, industry, or peer-comparison query, then screen with companies_list(sector=...).

[Server current date: 2026-10-09 — treat this as today.]

When and how to fall back to filings_markdown_retrieve for values the normalized financials dataset doesn't carry, including processing_status caveats (a hint, not a gate) and pagination.

[Server current date: 2026-10-09 — treat this as today.]

Search and resolve ISINs (International Securities Identification Numbers) to companies.

[Server current date: 2026-10-09 — treat this as today.]

Retrieve details for a specific ISIN.

When to use this tool: Use to resolve an ISIN (12-character code like US0378331005) to a company. Fastest path when the user provides an ISIN directly.

When NOT to use this tool: Don't use for name or ticker lookups — use companies_list with the search parameter instead.

Examples:

• Look up US0378331005 -> code='US0378331005' (Returns the company associated with this ISIN)

[Server current date: 2026-10-09 — treat this as today.]