# Investor Tool Finance API > Public company financials, valuations, quarterly statements, historical prices and watchlists. No login, API key or direct database access required. Base URL: https://finance.mannhowie.com ## Read-only MCP connection Connect a remote MCP client to https://finance.mannhowie.com/api/mcp using Streamable HTTP, authentication None. The endpoint supports current MCP and stateless 2025 Streamable HTTP clients. All tools are stored-data reads with no imports, refreshes, arbitrary SQL or mutations. POST carries read-only protocol messages; GET may return 405 because persistent SSE sessions are not used. No database credentials or browser access are needed. Client/account/workspace setup is still required. - list_companies: Find stored tickers by ticker or company name. Returns a bounded page with nextOffset. Reads stored data only; never imports or refreshes a company. - list_watchlists: List visible saved watchlists and their ticker memberships. Use to identify a cohort before querying financial metrics. Reads saved data only; never refreshes memberships. - query_financials: Read selected annual or quarterly financial facts for stored tickers, with period limits, dates, currency and units. Reads only requested financial columns and required FX; never loads price history or triggers imports/refreshes. Cash flows retain reported signs. Null and missing reasons mean unavailable, never zero. - query_ratios: Read the same current ratio-table values or annual ratio history as the website using its shared calculator, labels and formatting. Stored data only; no refreshes or writes. Includes formulas, denominator guards, period selection and estimate flags by default. Current values may use TTM or an annual fallback; CAGR and reinvestment rate use annual data. Missing cash/debt/annual SBC can use the website zero-input assumptions with missingInputs flags. Formula catalog: pe: marketCap / netIncome; evEbit: (marketCap + longTermDebt + currentDebt - cash) / operatingIncome; evRevenue: (marketCap + longTermDebt + currentDebt - cash) / revenue; fcfYield: (operatingCashFlow - abs(capitalExpenditure) - sbc) / marketCap; dividendYield: abs(dividendsPaid) / marketCap; revenue3yCagr: (annualRevenue / annualRevenueThreeFiscalYearsEarlier)^(1/3) - 1; ebit3yCagr: (annualOperatingIncome / annualOperatingIncomeThreeFiscalYearsEarlier)^(1/3) - 1; grossMargin: grossProfit / revenue; operatingMargin: operatingIncome / revenue; fcfConversion: (operatingCashFlow - abs(capitalExpenditure) - sbc) / operatingIncome; roic: (operatingIncome - taxProvision) / investedCapital; reinvestmentRate: (annualInvestedCapital - previousStoredAnnualInvestedCapital) / (annualOperatingIncome - annualTaxProvision); netDebtEbit: (longTermDebt + currentDebt - cash) / operatingIncome - get_shareholder_returns: Read cash dividends and gross share repurchases for consecutive fiscal years and calculate per-company totals and contribution percentages in USD millions. Default ends at latest reported completed year; throughYears can include completed but unreported years. Missing values/years remain explicit. Exact combined totals and percentages are null unless all requested companies are complete; observed subtotals are partial, not estimates. Reads stored data only. query_financials accepts tickers, metrics, interval, limit, from/to, currency and unit. query_ratios accepts tickers, selected ratios, period=current or annual, limit, currency and includeDefinitions. It returns the same web-app calculator values, shared formulas, formatting and estimate flags; its explicit missing-input assumptions follow the app rather than treating all omissions identically. get_shareholder_returns batches up to 20 tickers with optional throughYears (e.g. {"AVGO":2026}); do not count multiple share classes of the same issuer as separate companies. Retrieve data before rendering a chart. ## Select metrics and financial interval [Five annual dividend and repurchase records](https://finance.mannhowie.com/api/financials/AAPL/statements?metrics=dividendsPaid,stockRepurchase&interval=annual&limit=5¤cy=usd): choose metrics from the published field enum, interval=annual or quarterly, limit=1–200, optional from/to period-end dates, currency=usd or local, unit=millions or whole. Share counts always remain shares. Responses contain only selected fields and period identifiers; database reads omit price/security history. Signed cash flows remain signed, and null means missing. For example, use interval=quarterly&limit=20 for up to twenty quarters. ## Dividends and gross buybacks: compact requests Use the small shareholder-returns view for this task. The default financial history contains unrelated metadata; view=summary contains no annual cash-flow metrics. - [Dated ten-company JSON, including missing-data flags](https://finance.mannhowie.com/data/shareholder-returns-2026-11-22.json): snapshot from 22 November 2026, not a live feed. Includes observed chart segments; exact contributions remain null where the combined denominator is incomplete. - [AAPL: FY2022–2026](https://finance.mannhowie.com/api/financials/AAPL/statements?view=shareholder-returns&years=5&throughYear=2026) - [MSFT: FY2022–2026](https://finance.mannhowie.com/api/financials/MSFT/statements?view=shareholder-returns&years=5&throughYear=2026) - [GOOG: FY2021–2025](https://finance.mannhowie.com/api/financials/GOOG/statements?view=shareholder-returns&years=5&throughYear=2025) - [NVDA: FY2022–2026](https://finance.mannhowie.com/api/financials/NVDA/statements?view=shareholder-returns&years=5&throughYear=2026) - [AMZN: FY2021–2025](https://finance.mannhowie.com/api/financials/AMZN/statements?view=shareholder-returns&years=5&throughYear=2025) - [TSM: FY2021–2025](https://finance.mannhowie.com/api/financials/TSM/statements?view=shareholder-returns&years=5&throughYear=2025) - [AVGO: FY2022–2026](https://finance.mannhowie.com/api/financials/AVGO/statements?view=shareholder-returns&years=5&throughYear=2026) - [META: FY2021–2025](https://finance.mannhowie.com/api/financials/META/statements?view=shareholder-returns&years=5&throughYear=2025) - [TSLA: FY2021–2025](https://finance.mannhowie.com/api/financials/TSLA/statements?view=shareholder-returns&years=5&throughYear=2025) - [SPCX: FY2021–2025](https://finance.mannhowie.com/api/financials/SPCX/statements?view=shareholder-returns&years=5&throughYear=2025) If a web reader cannot open a constructed URL directly, follow these explicit links from /api/docs or this guide. A successful HTTP request does not guarantee that every reader permits it. Retrieve data before generating a visualisation and embed the JSON; a preview runtime may block its own network requests. ## Discovery - [API directory](https://finance.mannhowie.com/api): JSON operation index - [OpenAPI 3.1](https://finance.mannhowie.com/api/openapi.json): request parameters and response schemas - [API documentation and Swagger UI](https://finance.mannhowie.com/api/docs) ## Data endpoints - [Enumerate stored companies](https://finance.mannhowie.com/api/companies?limit=100): Public financial universe, excluding archived companies. No upstream calls. Page with offset and limit; total is the filtered count. - [List visible saved watchlists and all members](https://finance.mannhowie.com/api/watchlists): Returns saved public lists and their ticker memberships. Visibility and manual membership match the website. - [Query company financials, valuations and price history](https://finance.mannhowie.com/api/financials/AAPL?storedOnly=1&view=history): Use view=history for annual cash-flow metrics. view=summary annual rows contain date anchors only, without dividendsPaid or stockRepurchase. Raw cash outflows are signed; dividends is absolute dividendsPaid and netStockBuyback subtracts issuance (not gross repurchases). For compact annual cash returns use the statements endpoint with view=shareholder-returns. - [Read annual and quarterly statements, prices and FX in original units](https://finance.mannhowie.com/api/financials/AAPL/statements?view=shareholder-returns&years=5): Stored data only; never imports or refreshes. Statement amounts are whole field-metadata currency units (falling back to period currency); share counts are shares. Honor per-field retract/unavailable flags. Prices are monthly observations in each row currency, with shareBasis and ordinarySharesPerQuote describing the security basis. FX rates are USD per currency unit. The default full view does not convert or round. The optional shareholder-returns view uses absolute dividendsPaid and gross stockRepurchase, converts each field using its currency metadata and existing period-end FX policy, and scales to USD millions. It never subtracts issuance or substitutes net financing flow. Missing/retracted fields or FX produce null totals, with observed subtotals and missing reasons. Do not silently extend the window backward to replace missing years. Null fields mean unavailable. For general queries provide metrics, interval, limit and optional from/to dates. Series and shareholder-returns select only financial columns and required FX at the database boundary; neither reads price, description or security history. These are selected financial facts, not a database dump. - [Search Yahoo Finance for equity and ETF symbols](https://finance.mannhowie.com/api/search?q=apple): Searches upstream Yahoo; results may not yet exist in stored data. - [Get lightweight market-cap snapshots for up to 200 symbols](https://finance.mannhowie.com/api/watchlists/quotes?tickers=AAPL,MSFT&storedOnly=1): Returns company identity and ttm.marketCap in USD millions. This is not a full live price quote; local currency market caps are null. Missing symbols can return placeholders. - [Get watchlist snapshots and the largest company history](https://finance.mannhowie.com/api/watchlists/start?tickers=AAPL,MSFT&storedOnly=1): Only the selectedTicker has complete financials; other stocks are placeholders. Query financials individually for comparisons. - [Read S&P 500 price index history](https://finance.mannhowie.com/api/benchmark?frequency=monthly): Cached ^GSPC close prices, not total returns; check asOf, stale and refreshFailed. ## Query workflow 1. Enumerate /api/companies (follow nextOffset until null) or /api/watchlists to find stored tickers. Use /api/search?q=... for Yahoo discovery. 2. GET /api/financials/{ticker}?storedOnly=1&view=summary for comparisons; use view=history for annual metrics, historical valuations and share prices. Fetch each company separately with modest concurrency (e.g. 4 requests). 3. For cash dividends and gross buybacks use /api/financials/{ticker}/statements?view=shareholder-returns&years=5. Totals are positive USD millions; missing fields stay null. Default ends at latest reported completed fiscal year; use throughYear to include a completed but unreported year. observed subtotals are partial, not five-year estimates. Compute exact cross-company percentages only when every company is complete. For raw quarterly or annual facts, monthly prices and FX use /api/financials/{ticker}/statements. It reads stored data only, in whole original currency units and shares; honor per-field currency overrides and retract/unavailable flags. 4. Financial presentation metrics are in millions of display currency; company.marketCap is in whole units. Use metadata and price currency fields. Ratios may fall back to annual data. Null means unavailable, not zero. 5. Cite quote timestamps, financialFreshness, period dates, coverage and source information. Data is cached and coverage varies by ticker; do not promise real-time quotes or complete historical coverage. ## Errors and access 400 invalid input; 404 ticker missing; 410 archived; 502 upstream failure; 503 store/benchmark unavailable. Responses are JSON with an error string. Stored-only misses do not import; omit storedOnly or set 0 to allow the financial endpoint's normal Yahoo import/refresh behavior. Do not retry 4xx blindly; back off on 429/5xx. Browser clients may use public GET/HEAD/OPTIONS with CORS. Authentication, admin and cron endpoints are not part of this public data API.