FinancialFilings

**Cost:** 1 credit per request. Match a list of your identifiers to our companies in one request. Each row can carry any mix of `isin`, `lei`, `cik`, `ticker` and `name`, plus an optional `ref` that is echoed back so you can join results to your rows. Results come back in input order. **Resolution order:** ISIN, LEI, CIK, ticker, venue ticker, name. The first hit wins, but every identifier you send is checked: if two point to different companies, the row is `ambiguous` with `identifier_conflict` and both in `candidates`. **A name alone never returns `matched`.** A name-only row is at best `ambiguous`, with candidates to choose from. **Tickers are checked against your `name`.** Tickers are reused across exchanges, so your name can pick the company that holds the ticker on another venue. A row matched only through a venue ticker is `ambiguous` + `name_disagrees` when the name disagrees, and `matched` + `security_listing_unverified` when you sent no name. If other companies hold the same ticker elsewhere, the row carries `multiple_tickers` and lists them in `candidates`. Add a country code (`WDI.DE`) to pin the exchange. **Billing:** one request is one call, whatever the row count. Up to 500 rows per request. Up to 50 rows that need a name lookup get one, within 25 seconds; rows resolved by an identifier don't count. Past either limit, a name-only row returns `not_covered` with `name_tier_skipped`, so split large name-heavy batches. **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-11-01 — treat this as today.]

companies_resolve_create

**Cost:** 1 credit per request. 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=<company_id from companies_list> (Returns lei field) [Server current date: 2026-11-01 — treat this as today.]

companies_retrieve

**Cost:** 40 credits per request. **Experimental:** the response may change without an API version bump. Returns a company's standardized income statement, balance sheet and cash flow statement: `periods`, each holding its `statements`, each holding `line_items`. Use `depth` and `parent_code` on each line item to rebuild the statement hierarchy. **One statement per period.** When several filings report the same fiscal year, period and statement type, one is selected. A filing with the company's own financials beats one without (such as an employee benefit plan's report), the company's reporting currency beats another currency, and a complete statement beats a fragment. Only then does the latest filing win. A selected statement in a currency other than the company's carries `currency_mismatch: true`. **Currency is never converted.** `currency` is the currency the company presented in. A company that switches currency does not restate earlier years, so compare `currency.code` across periods before aggregating. A line item with its own `currency` comes from a dual-currency filing. **Values.** `value` and `raw_value` are exact decimal strings: parse them with a decimal type. `raw_value` and `scale` are `null` when a figure was computed rather than read off the page. `confidence` is set only where an independent check re-derived the figure and agreed: `null` means unjudged, not low confidence. `source_page` is the page of the filing's PDF a value read from that PDF is printed... **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=<id>, fiscal_year=2024, statement_type='IS' (Use depth + parent_code to render Capital IQ-style hierarchy) - Compare EBITDA across 3 companies -> id=<id>, statement_type='IS', line_items='ebitda' (Call in parallel for each company. Always show currency.) [Server current date: 2026-11-01 — treat this as today.]

companies_financials_retrieve

**Cost:** 1 credit per request. 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=<filing_id> (Returns document (raw PDF/ZIP URL) and proxy_url (rendered)) - Send me a link to read this filing -> id=<filing_id> (Share viewer_url (public web page) — never the /api/ markdown URL) [Server current date: 2026-11-01 — treat this as today.]

filings_retrieve

**Cost:** 6 credits per request (12 for premium filing types). Retrieve the raw processed content of a single filing in Markdown format. **Large filings.** An annual report can run to several hundred thousand tokens. Every response carries `X-Total-Chars`, the full document's length in characters. Pass `offset` and/or `limit` (characters) to read one window instead of the whole document; while characters remain after the window, the response also carries `X-Next-Offset`. To find the part you need first, use `GET /filings/{id}/markdown/search/?q=`. Each call, whole or windowed, is billed as one Markdown request. Through the MCP server, which pages large filings in chunks, a filing's Markdown is billed once per day. **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=<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-11-01 — treat this as today.]

filings_markdown_retrieve

**Cost:** 1 credit per request. 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-11-01 — treat this as today.]

isins_retrieve

Search ONE filing's processed Markdown for `query` and return ONLY the matching passages with their character offsets (e.g. query='going concern'). Use it INSTEAD of paging a long filing. Best for what only the document has: disclosures, risk and policy language, commitments, auditor and going-concern wording, and the sentence around a number. FOR A COMPANY-AND-PERIOD LINE ITEM — revenue, assets, cash flow, EPS and the rest — CALL companies_financials_retrieve FIRST: it returns those as structured values with their period and currency, which grepping a document cannot give you. STAY HERE INSTEAD when the question is what a PARTICULAR filing reported. That tool picks ONE statement per fiscal year, period and statement type across every filing that reports them, so a later restatement can come back in place of the filing you named — a wrong citation rather than a missing one. AND COME BACK HERE whenever that call does not answer: no coverage, an empty line item, or a refusal for your plan. A value that is absent or unavailable there is not an absent fact, and the figure is usually in the document. 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-11-01 — treat this as today.]

filings_markdown_search

Search ONE query across SEVERAL filings in a single call — use this instead of calling filings_markdown_search once per filing when you are checking the same term across a set (e.g. the same disclosure across a company's filings, or across peers). SAME RULE AS THE SINGLE-FILING TOOL: for a company-and-period line item, call companies_financials_retrieve first — per company, not as a sweep here, which costs a read per filing. Stay here when the question is what a PARTICULAR filing reported: that tool may answer with a later restatement of the period instead. And come back here whenever it does not answer — no coverage, an empty line item, or a refusal for your plan; unavailable there is not absent. Case-insensitive. Returns per-filing hits with character offsets you can pass to filings_markdown_retrieve. Outcomes are reported SEPARATELY — matched, no match, searched only in part, and not searched — so you can tell a real absence from a filing that was truncated or never read. A filing can be BOTH matched and only partly searched — hits found before the byte cap are real, the tail past it is unknown. Max 20 filings per call. This searches only the filings you name — it does NOT search the whole corpus, so a 'no match' result says nothing about filings outside your list. [Server current date: 2026-11-01 — treat this as today.]

filings_markdown_search_batch