{"openapi":"3.0.0","info":{"title":"StockFit API","version":"1.0.0","description":"<img src=\"/docs/logo_text.svg\" alt=\"StockFit\" height=\"64\" style=\"margin-bottom: 12px\" />\n\nStockFit is not a market data API. No prices, no quotes, no adjusted estimates.\n\nIt is structured intelligence from SEC filings: normalized financials, institutional ownership flows, ETF exposure analysis, filing event timelines, and AI-classified business models. All sourced from official XBRL filings. Fully traceable to source documents. Updated daily.\n\n## Start here: build an investment research view in 3 calls\n\n**1. Get the company profile**\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  \"https://api.stockfit.io/v1/api/company/details?symbol=AAPL\"\n```\n\n```javascript\nconst profile = await fetch(\n  \"https://api.stockfit.io/v1/api/company/details?symbol=AAPL\",\n  { headers: { Authorization: \"Bearer YOUR_TOKEN\" } }\n).then(r => r.json());\n// { name: \"Apple Inc.\", sector: \"Technology\", fiscalYearEndMonth: 9, ... }\n```\n\n**2. Pull 3 years of financials**\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  \"https://api.stockfit.io/v1/api/financials/income-statement?symbol=AAPL&period=annual&limit=3\"\n```\n\n```javascript\nconst financials = await fetch(\n  \"https://api.stockfit.io/v1/api/financials/income-statement?symbol=AAPL&period=annual&limit=3\",\n  { headers: { Authorization: \"Bearer YOUR_TOKEN\" } }\n).then(r => r.json());\n// [{ period: \"2025-09-26\", facts: { revenue: 416161000000, netIncome: 112010000000, ... } }, ...]\n```\n\n**3. See who owns it**\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  \"https://api.stockfit.io/v1/api/ownership/institutional-holders?symbol=AAPL&pageSize=5\"\n```\n\n```javascript\nconst holders = await fetch(\n  \"https://api.stockfit.io/v1/api/ownership/institutional-holders?symbol=AAPL&pageSize=5\",\n  { headers: { Authorization: \"Bearer YOUR_TOKEN\" } }\n).then(r => r.json());\n// { data: [{ managerName: \"BlackRock, Inc.\", shares: 1157054556, pctOfShares: 7.87 }, ...] }\n```\n\nFinancial structure. Ownership concentration. Decision-ready in seconds. Get your API token from the [StockFit dashboard](https://developer.stockfit.io).\n\n## Go deeper\n\nThe 3 calls above give you fundamentals. These give you the edge:\n\n- **Research summary** (`/api/company/research-summary`): profile + earnings snapshot + key metrics in one call (Starter)\n- **Ownership summary** (`/api/ownership/summary`): institutional concentration, top holders, beneficial owners, insider count (Pro)\n- **Fund exposure** (`/api/fund/reverse-lookup`): which ETFs and mutual funds hold this stock, sorted by position size (Starter)\n- **Filing timeline** (`/api/filings/timeline`): recent filings + predicted next filings + earnings date (Pro)\n- **Business model** (`/api/company/business-model`): AI-derived economic structure — revenue model, pricing power, competitive advantages (Pro)\n\n## Core capabilities\n\n**Financial structure** — normalized income statements, balance sheets, cash flow. Quarterly, annual, TTM. Growth rates, Piotroski & Altman Z scores, sector-aware metrics, chart-ready data.\n\n**Capital flows** — institutional holders (13F), beneficial owners (13D/G), insider transactions (Form 3/4/5). Quarter-over-quarter change tracking, portfolio view, share class data.\n\n**Fund intelligence** — ETF and mutual fund holdings, overlap analysis, fund flows, fee history (N-1A), actual performance (N-CSR), structural analysis, AI exposure models.\n\n**Filing intelligence** — 8-K event classification, predicted filing calendar, S-1 offering pipeline, section text extraction (Risk Factors, MD&A), filing search and statistics.\n\n## Also included\n\n- **Company**: profiles, AI peer comparables, competitive advantages, operating levers, business model analysis\n- **Executives**: officer compensation vs TSR, governance flags, company-selected KPIs\n- **Screeners**: filter by AI-classified business model, pricing power, capital intensity\n- **Earnings**: EPS history, quality metrics, margin trajectories, predicted dates, calendar\n- **Symbol lookup**: search, batch lookups, cross-reference identifiers (CIK, CUSIP, EIN)\n\n## AI Integration (MCP)\n\nStockFit supports the [Model Context Protocol](https://modelcontextprotocol.io) with **OAuth 2.1** authentication. Sign in once in a browser — your AI client handles tokens automatically. No API keys to copy or rotate. Works with Claude Desktop, Claude Code, Cursor, VS Code, ChatGPT, and any MCP-compatible client.\n\n```json\n{\n  \"mcpServers\": {\n    \"stockfit\": {\n      \"type\": \"http\",\n      \"url\": \"https://api.stockfit.io/mcp\"\n    }\n  }\n}\n```\n\nSame config for everyone — no API key needed. Your client opens a browser the first time you connect, you sign in, and tokens refresh automatically after that.\n\nFull per-client setup (Claude Desktop, Claude Code, Cursor, VS Code): [developer.stockfit.io/mcp](https://developer.stockfit.io/mcp).\n\n## What you can build\n\n| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | |\n|---------|---|\n| **See what ETFs actually own under the hood** | Look through ETF holdings, detect overlap, and understand true exposure across funds. |\n| **Map institutional ownership in real time** | Track what top 13F filers own, how positions changed, and where capital is concentrating or exiting. |\n| **Track the IPO pipeline from filings, not headlines** | Monitor S-1 activity, offering terms, 8-K events, and predicted filing calendars directly from SEC data. |\n| **Screen by business model, not just ratios** | Filter companies by AI-classified business model, pricing power, capital intensity, and margin structure. |\n| **Compare any two companies side by side** | Pull normalized financials, peers, and ownership for AAPL vs MSFT in parallel. No joins needed. |\n| **Build LLM apps on structured SEC data** | Feed normalized financials, business models, and filing-derived insights into AI systems without preprocessing. |\n\n## More use cases\n\n- **Predict earnings before they're announced.** Combine filing calendars, margin trends, and quality signals to anticipate earnings setups.\n- **Detect insider behavior that actually matters.** Flag executive-level buys, cluster activity, and unusual trading patterns.\n- **Run due diligence directly from filings.** Surface governance risks, ownership structures, and filing inconsistencies without manual parsing.\n\n## Why StockFit API exists\n\nMost APIs give you data. We give you structure.\nMost APIs give you prices. We give you the drivers behind them.\nMost APIs require joins across dozens of endpoints. We compress research into a few calls.\n\n- Not market data — no prices, quotes, or real-time feeds\n- Not trading signals — no buy/sell indicators or technical analysis\n- Not adjusted estimates — no analyst consensus or forward guidance\n\nStockFit is the structured layer between raw EDGAR and your application.\n\n## Authentication\n\nAll requests require a Bearer token passed in the `Authorization` header:\n\n```\nAuthorization: Bearer your_token_here\n```\n\nTokens are issued per account and tied to a subscription tier. You can manage your API tokens from the [StockFit dashboard](https://developer.stockfit.io).\n\n## Rate Limiting\n\nRequests are rate-limited on two levels:\n\n| Limit | Window | How it works |\n|-------|--------|--------------|\n| **Per-minute** | Sliding 60-second window | Requests older than 60 seconds are dropped from the window continuously |\n| **Per-day** | Calendar day (resets at midnight UTC) | Hard daily cap that resets at 00:00 UTC |\n\nEvery response includes rate limit headers:\n\n| Header | Description |\n|--------|-------------|\n| `X-RateLimit-Limit-Minute` | Your per-minute request limit |\n| `X-RateLimit-Remaining-Minute` | Requests remaining in the current minute window |\n| `X-RateLimit-Limit-Day` | Your daily request limit |\n| `X-RateLimit-Remaining-Day` | Requests remaining today (resets at midnight UTC) |\n\nWhen a rate limit is exceeded, the API returns HTTP `429 Too Many Requests`. Rate limits vary by subscription tier.","contact":{"name":"StockFit"}},"tags":[{"name":"Symbol Lookup","description":"Individual and batch symbol lookups, search, cross-reference identifiers, and former name search"},{"name":"Symbol Lists","description":"Paginated symbol listing, exchanges, sectors, industries, and industry groups"},{"name":"Screeners","description":"Filter stocks and ETFs by AI-derived structural characteristics"},{"name":"Company","description":"Company details, AI-classified peer comparables, and AI-enriched business model analysis"},{"name":"Executives","description":"Executive officers, compensation vs performance analysis, governance flags, and company-selected KPIs (DEF 14A)"},{"name":"Financials","description":"Financial statements (income, balance sheet, cash flow), growth rates, sector-aware key metrics, financial health scores, and chart-ready data"},{"name":"SEC Filings","description":"SEC filings search, 8-K event categorization, filing statistics, and predicted filing calendar"},{"name":"Earnings","description":"EPS history, earnings snapshots, multi-year trends with CAGR & margin trajectories, earnings quality metrics, and earnings calendar"},{"name":"ETF/MF","description":"Fund profiles, holdings, portfolio composition, fund flows, portfolio changes, overlap analysis, fund health, fee analysis, service providers, structural analysis, AI exposure models, and chart-ready data. Covers both ETFs and mutual funds."},{"name":"Insider Transactions","description":"Officer and director stock transactions (Form 4/5)"},{"name":"Ownership","description":"Institutional holders (13F) and beneficial owners (13D/G)"}],"servers":[{"url":"https://api.stockfit.io/v1","description":"Production"}],"components":{"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message","example":"Error description goes here"}},"required":["error"]},"FactSources":{"type":"object","description":"Map of SEC accession number to the filing's metadata and the list of curated fact names that filing supplied to this period. Combines provenance (which filing supplied each value) with the audit trail of restatements. Facts synthesized from other facts in the same period (e.g. `grossProfit = revenue - costOfRevenue`) are absent from this map and instead listed under `derived`. Q4 values reconstructed from cumulative period facts use a self-documenting synthetic key — `Q4-Recon-FY-9M`, `Q4-Recon-FY-H1-Q3`, or `Q4-Recon-FY-Q1-Q2-Q3` — with `type: \"Q4-Recon\"` and no `dateFiled` (the matching 10-K's `dateFiled` is on the period entry's top-level `dateFiled` field). **Pruning rules**: non-amendment filings that supplied no surviving fact value are dropped (their existence is already conveyed by the period's top-level `dateFiled`). **Amendment filings (`/A`) are always included even when their facts were all superseded by a later amendment** — their `facts` may be empty, but their existence is itself the audit signal needed to reconstruct point-in-time data between filing dates. Combine `sources[accession].facts` (which values came from this filing) with `sources[accession].dateFiled` (when each became public) to reconstruct point-in-time data and detect restatements.","additionalProperties":{"type":"object","required":["type","amendment","facts"],"properties":{"type":{"type":"string","description":"SEC form type: `10-K`, `10-K/A`, `10-Q`, `10-Q/A`, `20-F`, `20-F/A`, `40-F`, `40-F/A`, or `Q4-Recon` for a synthetic Q4 reconstruction.","example":"10-K"},"dateFiled":{"type":"string","format":"date","description":"SEC acceptance date of this filing (YYYY-MM-DD). Absent for `Q4-Recon` entries — they're synthetic, not real filings.","example":"2024-11-01"},"amendment":{"type":"boolean","description":"True for /A amendment filings; false for originals and Q4-Recon synthetic entries.","example":false},"facts":{"type":"object","description":"Map of curated fact name to metadata about this filing's contribution. Empty object `{}` means this filing supplied the value first (or didn't change it from the prior filing). `{ \"before\": <number> }` means this filing changed the value — `before` is what the immediately-prior filing in the chain had for this fact. Walk the chronological filings forward to reconstruct the value at any point in time, or follow `before` backward to recover any historical value. Re-tagging with an identical value is omitted (no entry added). May be empty (`{}`) for amendment (`/A`) filings whose values were all unchanged or superseded by a later amendment — the source entry is preserved so the amendment timeline remains visible.","additionalProperties":{"type":"object","properties":{"before":{"type":"number","description":"Value of this fact in the immediately-prior filing that supplied it. Present only when this filing CHANGED the value. Absent when this filing was the first to supply it (no prior)."}}},"example":{"revenue":{},"netIncome":{"before":99800000000}}}}},"example":{"0000320193-22-000108":{"type":"10-K","dateFiled":"2022-10-28","amendment":false,"facts":{"revenue":{},"costOfRevenue":{},"netIncome":{},"eps":{}}},"0000320193-23-000063":{"type":"10-K","dateFiled":"2023-02-15","amendment":true,"facts":{"interestExpense":{"before":2931000000}}}}},"DerivedFacts":{"type":"array","description":"Names of facts whose values were calculated rather than taken directly from the source filing — for example, `grossProfit` synthesized from `revenue` minus `costOfRevenue` when the company did not tag gross profit explicitly, or every fact in a `period=ttm` response (summed across 4 quarters, or carried from the latest quarter for instant items).","items":{"type":"string"},"example":["grossProfit","ebit","ebitda","totalDebt","workingCapital","freeCashFlow"]},"SymbolInfo":{"type":"object","properties":{"symbol":{"type":"string","description":"Ticker symbol","example":"AAPL"},"name":{"type":"string","description":"Company or fund name","example":"Apple Inc."},"cik":{"type":"integer","description":"SEC Central Index Key","example":320193},"seriesId":{"type":"integer","description":"Series ID (0 for stocks, non-zero for ETF/mutual fund series sharing a CIK)","example":0},"exchange":{"type":"string","description":"Primary exchange","example":"NASDAQ"},"type":{"type":"string","description":"Security type","example":"stock","enum":["stock","etf","mf"]}}},"SymbolProfile":{"allOf":[{"$ref":"#/components/schemas/SymbolInfo"},{"type":"object","properties":{"sector":{"type":"string","description":"Business sector derived from SIC code","example":"Technology","nullable":true},"industry":{"type":"string","description":"Industry classification derived from SIC code","example":"Consumer Electronics","nullable":true},"industryGroup":{"type":"string","description":"High-value industry group (Semiconductors, Software & SaaS, Pharma & Biotech, Aerospace & Defense, Automotive, Airlines, Oil & Gas, Fintech & Payments). Null if company is not in one of these groups.","example":"Software & SaaS","nullable":true},"compositeFigi":{"type":"string","nullable":true,"description":"Bloomberg Composite FIGI","example":"BBG000B9XRY4"},"ein":{"type":"integer","nullable":true,"description":"Employer Identification Number","example":942404110},"formerNames":{"type":"array","items":{"type":"string"},"description":"Historical company names","example":["APPLE COMPUTER INC"]},"status":{"type":"string","description":"Symbol status","example":"operating","enum":["operating","delisted"]},"delistedAt":{"type":"string","format":"date","description":"Date when the symbol was first detected as delisted (ISO 8601). Null while operating.","example":"2024-06-15","nullable":true}}}]},"CompanyDetails":{"type":"object","properties":{"name":{"type":"string","description":"The company name","example":"Apple Inc."},"cik":{"type":"integer","description":"The Central Index Key (CIK)","example":320193},"sic":{"type":"string","description":"Standard Industrial Classification code","example":"3571"},"industry":{"type":"string","description":"Industry classification","example":"Consumer Electronics"},"industryGroup":{"type":"string","description":"High-value industry group classification, or null","example":"Software & SaaS","nullable":true},"sector":{"type":"string","description":"Sector classification","example":"Technology"},"description":{"type":"string","description":"AI-generated company description, periodically updated.","example":"Apple Inc. designs, manufactures, and markets smartphones, personal computers..."},"fiscalYearEndMonth":{"type":"integer","description":"Fiscal year end month (1-12)","example":9},"fiscalYearEndDay":{"type":"integer","description":"Fiscal year end day","example":30},"exchanges":{"type":"array","items":{"type":"string"},"description":"List of exchanges where the company is listed","example":["NASDAQ"]},"address":{"type":"string","description":"Company street address","example":"One Apple Park Way"},"city":{"type":"string","description":"Company city","example":"Cupertino"},"state":{"type":"string","description":"Company state","example":"CA"},"zip":{"type":"string","description":"Company ZIP code","example":"95014"},"country":{"type":"string","description":"Company country","example":"US"},"phone":{"type":"string","description":"Company phone number","example":"(408) 996-1010"},"type":{"type":"string","nullable":true,"description":"Security type","example":"stock"},"webUrl":{"type":"string","nullable":true,"description":"Company website URL"},"investorRelationsUrl":{"type":"string","nullable":true,"description":"Investor relations page URL"},"logoUrl":{"type":"string","nullable":true,"description":"Company logo URL"},"ipoDate":{"type":"string","format":"date","nullable":true,"description":"IPO / first-effective date (YYYY-MM-DD), derived from the earliest SEC Form EFFECT filing for this CIK. Null when no EFFECT filing has been observed (e.g. companies that listed before EDGAR full-text coverage).","example":"2021-04-14"},"employees":{"type":"object","nullable":true,"description":"Total number of employees from the most recent `dei:EntityNumberOfEmployees` XBRL fact (typically reported on the 10-K cover page, annual cadence). **Coverage is sparse** — only ~2% of SEC filers structurally tag this fact in XBRL. Most filers disclose headcount as prose in 10-K Item 1 (Business) without machine-readable tagging, so `employees` is `null` for the majority of companies including some megacaps (AAPL, MSFT, AMZN, GOOGL, META, TSLA all currently report null). When non-null, `asOf` indicates how stale the count is — annual filers update this once per year, so a count from a year ago is normal.","properties":{"count":{"type":"integer","description":"Reported employee headcount.","example":3182},"asOf":{"type":"string","format":"date","description":"Period-end date (YYYY-MM-DD) of the filing this count was reported in.","example":"2025-12-31"}}}}},"MarginTrajectory":{"type":"object","description":"Margin trajectory comparing current value vs 3 years ago with directional classification","properties":{"latest":{"type":"number","nullable":true,"description":"Current margin percentage","example":46.2},"threeYearAgo":{"type":"number","nullable":true,"description":"Margin percentage 3 years ago","example":43.3},"direction":{"type":"string","nullable":true,"enum":["expanding","compressing","stable"],"description":"Directional classification based on ±1 percentage point threshold","example":"expanding"}}},"EtfChange":{"type":"object","description":"A portfolio holding that was added, removed, or reweighted between two reporting periods","properties":{"changeType":{"type":"string","enum":["added","removed","reweighted"],"description":"Type of change","example":"added"},"cusip":{"type":"string","nullable":true,"description":"CUSIP identifier","example":"037833100"},"name":{"type":"string","description":"Holding name","example":"Apple Inc"},"pctVal":{"type":"number","nullable":true,"description":"Current portfolio weight percentage","example":6.82},"valueUsd":{"type":"number","nullable":true,"description":"Current USD value","example":4250000000},"balance":{"type":"number","nullable":true,"description":"Current share count","example":18500000},"prevPctVal":{"type":"number","nullable":true,"description":"Previous portfolio weight percentage","example":6.15},"prevValueUsd":{"type":"number","nullable":true,"description":"Previous USD value","example":3800000000},"prevBalance":{"type":"number","nullable":true,"description":"Previous share count","example":17200000},"mappedSymbol":{"type":"string","nullable":true,"description":"Mapped ticker symbol (if available)","example":"AAPL"}}},"FilingInfo":{"type":"object","description":"A single SEC filing. Fields that do not apply to a given filing type (e.g. `items` for non-8-K, `periodEndDate` for Form 4/144) are omitted from the response rather than returned as null.","required":["type","accessionNumber","url","dateFiled","xbrl","amendment"],"properties":{"type":{"type":"string","description":"SEC form type","example":"8-K"},"accessionNumber":{"type":"string","description":"SEC accession number","example":"0000320193-23-000106"},"url":{"type":"string","description":"URL to the filing document","example":"https://www.sec.gov/Archives/edgar/data/320193/000032019323000106/aapl-20230930.htm"},"dateFiled":{"type":"string","description":"Date the filing was submitted to the SEC (YYYY-MM-DD)","example":"2023-11-02"},"xbrl":{"type":"boolean","description":"Whether the filing includes XBRL data","example":true},"amendment":{"type":"boolean","description":"Whether this filing is an amendment","example":false},"periodEndDate":{"type":"string","description":"Period end date for the report (YYYY-MM-DD). Omitted for filings without a reporting period (Form 144, 4, etc).","example":"2023-09-30"},"documents":{"type":"array","items":{"type":"string"},"description":"Ordered list of slide/exhibit filenames (images >= 50KB). To get the full URL, replace the filename in the filing `url` with the document filename. Omitted when no extractable documents are present.","example":["g230399ex99_2p1g1.jpg","g230399ex99_2p2g1.jpg"]},"title":{"type":"string","description":"Descriptive title of the filing. Omitted when the filing has no meaningful title.","example":"APPLE INC ANNUAL REPORT 2023"},"items":{"type":"array","items":{"type":"string"},"description":"Extracted item identifiers. For 10-K/10-Q: section numbers (e.g. \"1A\", \"7\"). For 8-K: SEC item codes (e.g. \"2.02\", \"9.01\"). For S-1: section keys (e.g. \"risk-factors\"). Omitted when no items are extracted. Use `/api/filings/item` to retrieve the full content of any listed item.","example":["1","1A","7","7A","8"]},"events":{"type":"array","items":{"type":"string"},"description":"Developer-friendly event type names for 8-K filings. Omitted for non-8-K filings. See the `event` parameter for the full enum.","example":["earnings","financial_exhibits"]}}},"ExposureModel":{"type":"object","nullable":true,"description":"AI-classified structural characteristics of an ETF. Null if not yet generated.","properties":{"main":{"$ref":"#/components/schemas/ExposureModelMain"},"holdings":{"type":"array","items":{"$ref":"#/components/schemas/ExposureModelHolding"},"description":"Key holdings with their portfolio role"},"peers":{"type":"array","items":{"$ref":"#/components/schemas/ExposureModelPeer"},"description":"Comparable ETFs with overlap analysis"},"peerComparison":{"type":"object","nullable":true,"description":"Framework for comparing this ETF to peers","properties":{"basis":{"type":"array","items":{"type":"string"},"description":"Dimensions to compare on"},"doNotCompareOn":{"type":"array","items":{"type":"string"},"description":"Dimensions that are not meaningful for comparison"},"notes":{"type":"string","description":"Additional comparison context"}}},"useCases":{"type":"array","items":{"$ref":"#/components/schemas/ExposureModelUseCase"},"description":"Best uses, bad uses, and failure modes"}}},"ExposureModelMain":{"type":"object","description":"Core structural characteristics of the ETF","properties":{"summary":{"$ref":"#/components/schemas/ExposureModelSummary"},"mandate":{"$ref":"#/components/schemas/ExposureModelMandate"},"portfolioConstruction":{"$ref":"#/components/schemas/ExposureModelPortfolioConstruction"},"exposures":{"$ref":"#/components/schemas/ExposureModelExposures"},"implementation":{"$ref":"#/components/schemas/ExposureModelImplementation"},"distributionsAndTaxes":{"$ref":"#/components/schemas/ExposureModelDistributions"},"costsAndLeakage":{"$ref":"#/components/schemas/ExposureModelCosts"},"sensitivities":{"$ref":"#/components/schemas/ExposureModelSensitivities"},"provenance":{"$ref":"#/components/schemas/ExposureModelProvenance"},"updatedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the model was last generated","example":"2025-12-15T08:30:00.000Z"}}},"ExposureModelSummary":{"type":"object","description":"High-level classification of what this ETF provides","properties":{"primaryExposure":{"type":"string","description":"One-line description of the primary exposure","example":"Broad US total stock market"},"strategyType":{"type":"string","enum":["index","rules-based","active","derivatives-overlay","multi-asset","other"],"description":"Investment strategy classification","example":"index"},"whoIsItFor":{"type":"array","items":{"type":"string"},"description":"Target investor profiles","example":["Long-term buy-and-hold investors","Core equity allocation"]},"whatItIsNot":{"type":"array","items":{"type":"string"},"description":"Common misconceptions about what this ETF does NOT provide","example":["Not a dividend-focused fund","Not hedged against currency risk"]}}},"ExposureModelMandate":{"type":"object","description":"Investment mandate and universe definition","properties":{"objective":{"type":"string","description":"Stated investment objective","example":"Track the CRSP US Total Market Index"},"benchmark":{"type":"object","nullable":true,"description":"Benchmark index information","properties":{"name":{"type":"string","example":"CRSP US Total Market Index"},"provider":{"type":"string","nullable":true,"example":"CRSP"},"type":{"type":"string","enum":["index","custom","none"],"example":"index"}}},"universe":{"type":"object","description":"Investable universe","properties":{"assetClass":{"type":"string","enum":["equity","fixed-income","commodity","multi-asset","volatility","crypto","other"],"example":"equity"},"geography":{"type":"array","nullable":true,"items":{"type":"string"},"example":["US"]},"instruments":{"type":"array","items":{"type":"string","enum":["cash-equities","bonds","futures","options","swaps","other-etfs","cash","other"]},"example":["cash-equities"]}}},"constraints":{"type":"array","items":{"type":"string"},"description":"Investment constraints or restrictions"}}},"ExposureModelPortfolioConstruction":{"type":"object","description":"How the portfolio is built and maintained","properties":{"selection":{"type":"array","items":{"type":"string"},"description":"Security selection methodology"},"weighting":{"type":"string","enum":["market-cap","equal","fundamental","factor-score","risk-parity","duration-weighted","custom","active-discretion","unknown"],"example":"market-cap"},"rebalancing":{"type":"object","properties":{"frequency":{"type":"string","enum":["daily","weekly","monthly","quarterly","semiannual","annual","ad-hoc","unknown"],"example":"quarterly"},"triggers":{"type":"array","items":{"type":"string"},"description":"Events that trigger rebalancing outside the regular schedule"}}},"concentrationNotes":{"type":"array","items":{"type":"string"},"description":"Notes about portfolio concentration characteristics"}}},"ExposureModelExposures":{"type":"object","description":"Risk drivers and factor exposures","properties":{"riskDrivers":{"type":"array","items":{"type":"string"},"description":"Primary sources of risk and return","example":["US equity market beta","Small-cap tilt"]},"factorTilts":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Factor tilts relative to market-cap weighting"},"kpiMappings":{"type":"object","description":"Key metrics for monitoring this exposure","properties":{"primaryMetrics":{"type":"array","items":{"type":"string"}},"supportingMetrics":{"type":"array","items":{"type":"string"}}}}}},"ExposureModelImplementation":{"type":"object","description":"How the strategy is implemented","properties":{"replication":{"type":"string","enum":["physical-full","physical-sampled","synthetic","fund-of-funds","active","unknown"],"example":"physical-full"},"derivativesUsage":{"type":"object","nullable":true,"properties":{"used":{"type":"boolean"},"why":{"type":"array","nullable":true,"items":{"type":"string"}},"instruments":{"type":"array","nullable":true,"items":{"type":"string","enum":["options","futures","swaps","forwards","other"]}}}},"securitiesLending":{"type":"object","nullable":true,"properties":{"enabled":{"type":"boolean"},"whoKeepsRevenue":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}}},"liquidityNotes":{"type":"array","items":{"type":"string"}}}},"ExposureModelDistributions":{"type":"object","description":"Distribution and tax characteristics","properties":{"distributionProfile":{"type":"string","enum":["low","moderate","high","variable","unknown"],"example":"moderate"},"taxNotes":{"type":"array","items":{"type":"string"}},"capitalGainsRisk":{"type":"string","enum":["low","medium","high","unknown"],"example":"low"}}},"ExposureModelCosts":{"type":"object","description":"Cost structure and tracking difference drivers","properties":{"expenseRatioNotes":{"type":"string","description":"Context about the expense ratio","example":"At 0.03%, one of the lowest-cost broad market ETFs"},"implicitCosts":{"type":"array","items":{"type":"string"},"description":"Non-fee costs (spread, market impact, etc.)"},"trackingDifferenceDrivers":{"type":"array","items":{"type":"string"},"description":"What causes tracking difference vs the benchmark"}}},"ExposureModelSensitivities":{"type":"object","description":"What external factors affect this ETF","properties":{"macro":{"type":"array","items":{"type":"string"},"description":"Macroeconomic sensitivities","example":["Interest rates","USD strength"]},"market":{"type":"array","items":{"type":"string"},"description":"Market structure sensitivities"},"portfolioMechanics":{"type":"array","items":{"type":"string"},"description":"Sensitivities from portfolio construction mechanics"}}},"ExposureModelProvenance":{"type":"object","description":"Model confidence and data sources","properties":{"confidence":{"type":"string","enum":["high","medium","low"],"example":"high"},"sources":{"type":"array","items":{"type":"string","enum":["prospectus","SAI","index-methodology","issuer-website","holdings-data","factsheet","inferred"]},"example":["prospectus","holdings-data"]}}},"ExposureModelHolding":{"type":"object","description":"A key holding with its portfolio role","properties":{"label":{"type":"string","description":"Holding name or bucket label","example":"Apple Inc"},"role":{"type":"string","enum":["core","driver","hedge","overlay","other"],"description":"Role in the portfolio","example":"core"},"notes":{"type":"string","nullable":true,"description":"Additional context about this holding"}}},"ExposureModelPeer":{"type":"object","description":"A comparable ETF with overlap analysis","properties":{"tier":{"type":"string","enum":["primary","secondary"],"description":"Comparison tier","example":"primary"},"symbol":{"type":"string","description":"Peer ETF ticker","example":"ITOT"},"name":{"type":"string","nullable":true,"description":"Peer ETF name","example":"iShares Core S&P Total U.S. Stock Market ETF"},"relation":{"type":"string","description":"Relationship to this ETF","example":"direct-substitute"},"rationale":{"type":"array","items":{"type":"string"},"description":"Why this is a peer"},"exposureOverlap":{"type":"object","nullable":true,"properties":{"level":{"type":"string","enum":["high","medium","low","unknown"],"example":"high"},"notes":{"type":"string"}}},"kpiMappings":{"type":"object","nullable":true,"properties":{"primaryMetrics":{"type":"array","items":{"type":"string"}},"supportingMetrics":{"type":"array","items":{"type":"string"}}}},"substitutionNotes":{"type":"string","nullable":true,"description":"Notes about substitutability"}}},"ExposureModelUseCase":{"type":"object","description":"A use case or failure mode for this ETF","properties":{"type":{"type":"string","enum":["best","bad","failure"],"description":"Whether this is a good use case, bad use case, or failure mode","example":"best"},"text":{"type":"string","description":"Description of the use case","example":"Core US equity holding for a long-term diversified portfolio"}}},"KeyMetricsGeneral":{"type":"object","description":"General financial metrics emitted for every company. Combines the GENERAL_VIEW chart definitions with manually-added ratios in the service layer so this block is a superset of the traditional financial-ratio set.","properties":{"revenue":{"type":"number","nullable":true,"description":"Total revenue (USD). Top-line sales from business operations.","example":281724000000},"netIncome":{"type":"number","nullable":true,"description":"Net income (USD). Profit after all expenses, taxes, and costs.","example":101832000000},"grossMargin":{"type":"number","nullable":true,"description":"Gross Margin (%) — `100 × grossProfit / revenue`. Pricing power after direct production costs.","example":68.82},"operatingMargin":{"type":"number","nullable":true,"description":"Operating Margin (%) — `100 × operatingIncome / revenue`. Profitability after operating expenses.","example":45.62},"profitMargin":{"type":"number","nullable":true,"description":"Profit Margin (%) — `100 × netIncome / revenue`. Bottom-line margin after all costs.","example":36.15},"debtToEquity":{"type":"number","nullable":true,"description":"Debt-to-Equity (ratio) — `longTermDebt / stockholdersEquity`. Financial leverage; lower means less risk.","example":0.126},"quickRatio":{"type":"number","nullable":true,"description":"Quick Ratio — `(cash + netReceivables) / currentLiabilities`. Conservative short-term liquidity test.","example":0.71},"currentRatio":{"type":"number","nullable":true,"description":"Current Ratio — `currentAssets / currentLiabilities`. Above 1.0x is healthy short-term solvency.","example":1.35},"roa":{"type":"number","nullable":true,"description":"Return on Assets (%) — `100 × netIncome / avg(assets, prevAssets)`. Asset profitability; uses textbook averaging.","example":18},"roe":{"type":"number","nullable":true,"description":"Return on Equity (%) — `100 × netIncome / avg(stockholdersEquity, prev)`. Return to shareholders.","example":33.28},"roic":{"type":"number","nullable":true,"description":"Return on Invested Capital (%) — `100 × NOPAT / avg(investedCapital)` where `NOPAT = operatingIncome × (1 − taxRate)` (taxRate clamped 0–35%) and `investedCapital = totalDebt + equity − cash`. Strips out leverage effects.","example":31.9},"eps":{"type":"number","nullable":true,"description":"Earnings per Share (USD/share). Curated diluted EPS fact.","example":13.7},"ebitda":{"type":"number","nullable":true,"description":"EBITDA (USD). Curated fact, falls back to `operatingIncome + D&A` when not directly tagged.","example":123803000000},"freeCashFlow":{"type":"number","nullable":true,"description":"Free Cash Flow (USD). Curated fact, falls back to `operatingCashFlow + capitalExpenditure` (CapEx is usually negative in cash flow statement).","example":71611000000},"fcfMargin":{"type":"number","nullable":true,"description":"FCF Margin (%) — `100 × freeCashFlow / revenue`. Cash conversion efficiency.","example":25.42},"fcfNetIncome":{"type":"number","nullable":true,"description":"FCF / Net Income (%) — `100 × freeCashFlow / netIncome`. Earnings quality; >100% means cash exceeds reported profit.","example":70.32},"assetTurnover":{"type":"number","nullable":true,"description":"Asset Turnover (ratio) — `annualizedRevenue / avg(assets)`. Quarterly revenue is multiplied by 4 before division.","example":0.498},"interestCoverage":{"type":"number","nullable":true,"description":"Interest Coverage (ratio) — `operatingIncome / abs(interestExpense)`. Above 3x is comfortable.","example":53.9},"netDebt":{"type":"number","nullable":true,"description":"Net Debt (USD) — `totalDebt − cash`. Negative means cash exceeds debt.","example":18964000000},"netDebtEbitda":{"type":"number","nullable":true,"description":"Net Debt / EBITDA (ratio). Primary leverage metric; below 2x is conservative.","example":0.153},"investedCapital":{"type":"number","nullable":true,"description":"Invested Capital (USD) — `totalDebt + stockholdersEquity − cash`. Capital base used as the ROIC denominator.","example":362443000000},"sbcRevenue":{"type":"number","nullable":true,"description":"Stock-Based Comp / Revenue (%) — `100 × stockBasedCompensation / revenue`. Dilution cost intensity.","example":4.25},"dividendPayout":{"type":"number","nullable":true,"description":"Dividend Payout (%) — `100 × abs(cashDividendsPaid) / netIncome`. Share of profits returned as dividends.","example":23.65},"netShareChange":{"type":"number","nullable":true,"description":"Net Share Change (%) — `100 × (sharesOutstanding − prev) / prev`. Negative = net buybacks, positive = dilution.","example":0},"cashRatio":{"type":"number","nullable":true,"description":"Cash Ratio — `cash / currentLiabilities`. Most conservative liquidity measure.","example":0.214},"operatingCashFlowRatio":{"type":"number","nullable":true,"description":"Operating Cash Flow Ratio — `operatingCashFlow / currentLiabilities`. Ability to cover short-term obligations from operations.","example":0.964},"receivablesTurnover":{"type":"number","nullable":true,"description":"Receivables Turnover (ratio) — `revenue / avg(accountsReceivable)`. Collection efficiency.","example":4.44},"payablesTurnover":{"type":"number","nullable":true,"description":"Payables Turnover (ratio) — `costOfRevenue / avg(accountsPayable)`. Payment cadence.","example":3.53},"inventoryTurnover":{"type":"number","nullable":true,"description":"Inventory Turnover (ratio) — `costOfRevenue / avg(inventory)`. Inventory efficiency.","example":80.43},"fixedAssetTurnover":{"type":"number","nullable":true,"description":"Fixed Asset Turnover (ratio) — `revenue / avg(propertyPlantAndEquipmentNet)`. Revenue per dollar of fixed assets.","example":1.65},"financialLeverageRatio":{"type":"number","nullable":true,"description":"Financial Leverage Ratio — `assets / stockholdersEquity`. Total assets per dollar of equity.","example":1.8},"longTermDebtToCapitalRatio":{"type":"number","nullable":true,"description":"Long-Term Debt / Total Capital — `longTermDebt / (longTermDebt + stockholdersEquity)`.","example":0.112},"freeCashFlowOperatingCashFlowRatio":{"type":"number","nullable":true,"description":"FCF / OCF — `freeCashFlow / operatingCashFlow`. Cash conversion after CapEx.","example":0.526},"capitalExpenditureCoverageRatio":{"type":"number","nullable":true,"description":"CapEx Coverage — `operatingCashFlow / capitalExpenditure`. Ability to fund CapEx from operations.","example":2.11},"pretaxProfitMargin":{"type":"number","nullable":true,"description":"Pretax Profit Margin (decimal) — `incomeBeforeTax / revenue`. Returned as a decimal (NOT a percentage).","example":0.439},"effectiveTaxRate":{"type":"number","nullable":true,"description":"Effective Tax Rate (decimal) — `incomeTaxExpense / incomeBeforeTax`. Returned as a decimal.","example":0.176},"revenuePerShare":{"type":"number","nullable":true,"description":"Revenue per Share (USD/share) — `revenue / dilutedShares`.","example":37.74},"netIncomePerShare":{"type":"number","nullable":true,"description":"Net Income per Share (USD/share) — `netIncome / dilutedShares`. Distinct from `eps` (curated fact).","example":13.64},"operatingCashFlowPerShare":{"type":"number","nullable":true,"description":"Operating Cash Flow per Share (USD/share).","example":18.24},"freeCashFlowPerShare":{"type":"number","nullable":true,"description":"Free Cash Flow per Share (USD/share).","example":9.59},"cashPerShare":{"type":"number","nullable":true,"description":"Cash per Share (USD/share) — `cash / dilutedShares`.","example":4.05},"bookValuePerShare":{"type":"number","nullable":true,"description":"Book Value per Share (USD/share) — `stockholdersEquity / dilutedShares`.","example":46.01}}},"KeyMetricsSector":{"type":"object","description":"Sector-specific metrics — empty `{}` if the company's SIC doesn't map to a known sector view. The sector that triggered each emission is annotated in parentheses at the start of every description (e.g. \"(Banking) ...\"). Some keys appear in multiple sectors with the same name but slightly different formulas; the description spells out the variation when it matters.","properties":{"affo":{"type":"number","nullable":true,"description":"(REIT) Adjusted Funds From Operations (USD) — `FFO + capitalExpenditure` (CapEx negative in cash flow statement, so this subtracts maintenance CapEx).","example":5800000000},"allowancePctAr":{"type":"number","nullable":true,"description":"(Wholesale) Allowance / Accounts Receivable (%) — credit loss reserve coverage.","example":1.5},"allowanceToLoans":{"type":"number","nullable":true,"description":"(Banking) Allowance for Credit Losses / Total Loans (%). Reserve coverage ratio.","example":1.4},"aroCurrent":{"type":"number","nullable":true,"description":"(Mining) Asset Retirement Obligation — current portion (USD).","example":120000000},"aroNoncurrent":{"type":"number","nullable":true,"description":"(Mining) Asset Retirement Obligation — non-current portion (USD).","example":4500000000},"assetTurnover":{"type":"number","nullable":true,"description":"(Manufacturing, Transportation, Wholesale) Revenue / avg(Total Assets), annualized for quarterly periods.","example":1.05},"bondingCapacity":{"type":"number","nullable":true,"description":"(Construction) Letters of Credit Outstanding / Revenue (%). Proxy for bonding-capacity utilization.","example":8.2},"bookValueGrowth":{"type":"number","nullable":true,"description":"(Insurance) Period-over-period growth in stockholders' equity (%). The core compounding metric for insurers.","example":11.5},"capexDda":{"type":"number","nullable":true,"description":"(Mining) CapEx / DD&A (ratio). Below 1x signals reserve depletion or underinvestment.","example":1.1},"capexDepreciation":{"type":"number","nullable":true,"description":"(Agriculture, Manufacturing, Transportation, Utilities) CapEx / Depreciation (ratio). >1x = expanding capacity, <1x = underinvesting.","example":1.25},"capexRevenue":{"type":"number","nullable":true,"description":"(Manufacturing, Telecom, Transportation, Utilities) CapEx / Revenue (%). Capital intensity.","example":17},"ccc":{"type":"number","nullable":true,"description":"(Agriculture, Construction, Manufacturing, Wholesale) Cash Conversion Cycle (days) — `DIO + DSO − DPO` (Construction omits DIO; values annualized for quarterly periods).","example":32},"cipRatio":{"type":"number","nullable":true,"description":"(Construction) Construction in Progress / Total Assets (%). Active project pipeline relative to asset base.","example":6.4},"combinedRatio":{"type":"number","nullable":true,"description":"(Insurance) Combined Ratio (%) — Loss Ratio + Expense Ratio. Below 100% means underwriting profit.","example":97.3},"contractAssetRatio":{"type":"number","nullable":true,"description":"(Construction) Costs in Excess of Billings / Revenue (%). Unbilled work performed.","example":4.2},"contractLiabilityRatio":{"type":"number","nullable":true,"description":"(Construction) Billings in Excess of Costs / Revenue (%). Customer prepayments.","example":5.8},"dacRatio":{"type":"number","nullable":true,"description":"(Insurance) Deferred Acquisition Costs / Premiums Earned (%). Capital tied up in policy acquisition.","example":11.2},"daysInventory":{"type":"number","nullable":true,"description":"(Agriculture, Manufacturing, Retail-Trade) Days Inventory Outstanding — `inventory / COGS × 365`. Lower means quicker stock movement.","example":28},"debtEbitda":{"type":"number","nullable":true,"description":"(Telecom) Total Debt / EBITDA (ratio). Below 3x is healthy.","example":2.6},"debtEquity":{"type":"number","nullable":true,"description":"(Agriculture, Construction, Mining, Utilities) Total Debt (or Long-Term Debt fallback) / Stockholders' Equity (ratio).","example":0.85},"debtToAssets":{"type":"number","nullable":true,"description":"(REIT) Total Debt / Total Assets (%). Healthy REIT range is 30–50%.","example":38},"debtToEquity":{"type":"number","nullable":true,"description":"(Transportation) Total Debt / Stockholders' Equity (ratio).","example":1.4},"dio":{"type":"number","nullable":true,"description":"(Wholesale) Days Inventory Outstanding (days) — annualized.","example":22},"dividendCoverage":{"type":"number","nullable":true,"description":"(Telecom, Utilities) Operating Cash Flow / Dividends Paid (ratio). Above 1.5x is healthy.","example":1.8},"dividendPayout":{"type":"number","nullable":true,"description":"(Telecom, Utilities) Dividends Paid / Net Income (%). Telecoms/utilities often pay 60–80%.","example":65},"dpo":{"type":"number","nullable":true,"description":"(Construction, Manufacturing, Wholesale) Days Payable Outstanding — `accountsPayable / COGS × 365` (annualized for quarterly).","example":45},"dso":{"type":"number","nullable":true,"description":"(Construction, Manufacturing, Services, Wholesale) Days Sales Outstanding — `receivables / revenue × 365` (annualized for quarterly).","example":82.16},"ebitdaMargin":{"type":"number","nullable":true,"description":"(Mining, Services, Telecom, Transportation) EBITDA / Revenue (%).","example":43.94},"efficiencyRatio":{"type":"number","nullable":true,"description":"(Banking) Non-Interest Expense / (Net Interest Income + Non-Interest Income) (%). Below 60% is efficient.","example":55.2},"expenseRatio":{"type":"number","nullable":true,"description":"(Insurance) Policy Acquisition Costs / Premiums Earned (%).","example":28.4},"ffo":{"type":"number","nullable":true,"description":"(REIT) Funds From Operations (USD) — `netIncome + D&A`. Key REIT cash-generation metric.","example":6500000000},"ffoPerShare":{"type":"number","nullable":true,"description":"(REIT) FFO / Shares Outstanding (USD/share). REIT equivalent of EPS.","example":4.32},"floatSize":{"type":"number","nullable":true,"description":"(Insurance) Policy Reserves (USD). GAAP proxy for insurance float.","example":95000000000},"floatYield":{"type":"number","nullable":true,"description":"(Insurance) Net Investment Income / avg(Investments) (%). Float deployment efficiency.","example":3.8},"grossMargin":{"type":"number","nullable":true,"description":"(Agriculture, Manufacturing, Mining, Services, Telecom, Transportation, Wholesale) Gross Profit / Revenue (%) — falls back to `(revenue − COGS) / revenue` when grossProfit isn't tagged.","example":68.82},"incomePerStore":{"type":"number","nullable":true,"description":"(Retail-Trade) Net Income / Store Count (USD per store).","example":850000},"insuranceLeverage":{"type":"number","nullable":true,"description":"(Insurance) Total Assets / Stockholders' Equity (ratio). Capital amplification through borrowed capital.","example":4.2},"interestCoverage":{"type":"number","nullable":true,"description":"(Agriculture, Construction, Mining, REIT, Transportation, Utilities) Operating Income / Interest Expense (ratio). Construction/Mining use complex fallbacks via `interestCoverageComplex` (substitutes net interest income when expense isn't tagged).","example":5.2},"interestExpense":{"type":"number","nullable":true,"description":"(Banking) Interest Expense (USD). Cost of deposits and borrowings.","example":12000000000},"interestIncome":{"type":"number","nullable":true,"description":"(Banking) Interest Income (USD). Revenue from loans and securities.","example":28000000000},"inventoryPerStore":{"type":"number","nullable":true,"description":"(Retail-Trade) Inventory / Store Count (USD per store).","example":2400000},"inventoryRevenue":{"type":"number","nullable":true,"description":"(Retail-Trade) Inventory / Revenue (%). Capital tied up in stock.","example":12.5},"inventoryTurnover":{"type":"number","nullable":true,"description":"(Agriculture, Manufacturing, Retail-Trade, Wholesale) COGS / avg(Inventory) (ratio). Wholesale uses annualized COGS.","example":7.5},"investmentIncome":{"type":"number","nullable":true,"description":"(Insurance) Net Investment Income (or Interest Income fallback) (USD). Returns from float.","example":22000000000},"loanToDeposit":{"type":"number","nullable":true,"description":"(Banking) Loans / Deposits (ratio). Above 100% means reliance on wholesale funding.","example":0.78},"lossRatio":{"type":"number","nullable":true,"description":"(Insurance) Policyholder Benefits and Claims / Premiums Earned (%).","example":65.4},"netInterestIncome":{"type":"number","nullable":true,"description":"(Banking) Net Interest Income (USD) — `interestIncome − interestExpense`. Core profitability driver.","example":16000000000},"netMargin":{"type":"number","nullable":true,"description":"(Services, Wholesale) Net Income / Revenue (%).","example":36.15},"netProfitMargin":{"type":"number","nullable":true,"description":"(Insurance) Net Income / Revenue (%).","example":14.2},"nim":{"type":"number","nullable":true,"description":"(Banking) Net Interest Margin (% — actually expressed in basis points by the formatter, but value is `100 × (interestIncome − interestExpense) / avg(assets)`). Banks typically target 250–350 bps.","example":3.2},"ocfRevenue":{"type":"number","nullable":true,"description":"(Mining) Operating Cash Flow / Revenue (%). Operating efficiency.","example":35},"operatingMargin":{"type":"number","nullable":true,"description":"(Agriculture, Manufacturing, Mining, Services, Telecom, Transportation, Utilities, Wholesale) Operating Income / Revenue (%). Mining and Wholesale fall back to `(revenue − costAndExpenses) / revenue` when operatingIncome isn't tagged.","example":45.62},"operatingRatio":{"type":"number","nullable":true,"description":"(Transportation) Operating Expenses / Revenue (%). Lower is better — key railroad/airline metric.","example":62},"payoutRatio":{"type":"number","nullable":true,"description":"(REIT) Cash Dividends Paid / FFO (%). REITs must distribute 90%+ of taxable income.","example":78},"ppeIntensity":{"type":"number","nullable":true,"description":"(Agriculture, Construction, Mining) PP&E Net / Total Assets (%). Capital tied up in equipment and infrastructure.","example":28},"premiumGrowth":{"type":"number","nullable":true,"description":"(Insurance) YoY growth in Premiums Earned (or Revenue fallback) (%).","example":8.5},"provisionToLoans":{"type":"number","nullable":true,"description":"(Banking) Provision for Credit Losses / avg(Loans) (%). Proxy for net charge-off intensity.","example":0.4},"reserveRatio":{"type":"number","nullable":true,"description":"(Insurance) Policy Reserves / Premiums Earned (ratio). Claims coverage adequacy.","example":2.8},"retainage":{"type":"number","nullable":true,"description":"(Construction) Contract Receivable Retainage / Revenue (%). Cash held back until project completion.","example":4.1},"revenueGrowth":{"type":"number","nullable":true,"description":"(Telecom) YoY revenue growth (%). Tracks subscriber/ARPU/share gains.","example":4.2},"revenuePerStore":{"type":"number","nullable":true,"description":"(Retail-Trade) Revenue / Store Count (USD per store).","example":8500000},"roa":{"type":"number","nullable":true,"description":"(Agriculture, Banking, Insurance, Mining, Transportation, Wholesale) Net Income / avg(Assets) (%). Mining/Wholesale annualize quarterly net income (×4) before dividing.","example":18},"roe":{"type":"number","nullable":true,"description":"(Banking, Insurance, Services, Utilities) Net Income / avg(Stockholders' Equity) (%).","example":33.28},"sgaRevenue":{"type":"number","nullable":true,"description":"(Retail-Trade, Services) SG&A / Revenue (%). Overhead efficiency.","example":11.67},"storeCount":{"type":"number","nullable":true,"description":"(Retail-Trade) Total store count (count). Curated fact.","example":4800},"underwritingIncome":{"type":"number","nullable":true,"description":"(Insurance) Underwriting Income (USD). Curated fact, falls back to `premiumsEarned − claims − acquisitionCosts`.","example":3200000000},"warrantyReserve":{"type":"number","nullable":true,"description":"(Manufacturing) Warranty Liability / Revenue (%). Quality / warranty-term proxy.","example":1.8},"workingCapitalRatio":{"type":"number","nullable":true,"description":"(Construction) Current Assets / Current Liabilities (ratio). Bonding-capacity proxy.","example":1.6}}},"KeyMetricsIndustry":{"type":"object","description":"Industry-specific metrics — empty `{}` when the company's industry doesn't map to one of the eight specialized industry views (Semiconductor, Software & SaaS, Pharma & Biotech, Aerospace & Defense, Automotive, Airlines, Oil & Gas, Fintech). The triggering industry is annotated in parentheses on every description.","properties":{"billings":{"type":"number","nullable":true,"description":"(Software & SaaS) Billings Proxy (USD) — `revenue + (deferredRevenue − prevDeferredRevenue)`. Approximates total invoiced amount; growing faster than revenue signals expanding backlog.","example":288697000000},"capexToDepreciation":{"type":"number","nullable":true,"description":"(Automotive) CapEx / D&A (ratio). >1x means expanding factory/EV capacity.","example":1.4},"capexToRevenue":{"type":"number","nullable":true,"description":"(Airlines, Oil & Gas) CapEx / Revenue (%). Fleet/well investment intensity.","example":13},"cashRunwayQuarters":{"type":"number","nullable":true,"description":"(Pharma & Biotech) Quarters of cash remaining at current burn — `cash / abs(operatingCashFlow)` (only emitted when OCF is negative). Below 4 triggers dilutive fundraising risk.","example":6.5},"daToRevenue":{"type":"number","nullable":true,"description":"(Aerospace & Defense) D&A / Revenue (%). Capital recovery burden on each revenue dollar.","example":4},"debtToEbitda":{"type":"number","nullable":true,"description":"(Aerospace & Defense, Airlines, Oil & Gas) Long-Term Debt (or Total Debt fallback) / EBITDA (ratio).","example":2.5},"debtToEquity":{"type":"number","nullable":true,"description":"(Automotive) Long-Term Debt (or Total Debt) / Stockholders' Equity (ratio).","example":1.6},"deferredRevenue":{"type":"number","nullable":true,"description":"(Software & SaaS) Current Deferred Revenue / Liabilities (USD). Prepaid subscription revenue yet to be recognized.","example":64555000000},"deferredRevenueGrowth":{"type":"number","nullable":true,"description":"(Software & SaaS) YoY growth in Deferred Revenue (%). Accelerating growth signals strong bookings momentum.","example":12.11},"dividendPayout":{"type":"number","nullable":true,"description":"(Oil & Gas) Cash Dividends / Net Income (%). Above 80% leaves no buffer for commodity price drops.","example":50},"ebitdaMargin":{"type":"number","nullable":true,"description":"(Airlines, Oil & Gas) EBITDA / Revenue (%). Primary profitability metric for fleet/extraction businesses where D&A distorts net income.","example":18},"fcfConversion":{"type":"number","nullable":true,"description":"(Semiconductor, Aerospace & Defense) FCF / Net Income (ratio). Above 1x = earnings backed by real cash; below 1x flags working-capital drains or heavy CapEx cycles.","example":1.05},"fcfMargin":{"type":"number","nullable":true,"description":"(Semiconductor, Software & SaaS, Pharma & Biotech, Automotive, Airlines, Oil & Gas, Fintech) FCF / Revenue (%).","example":25.42},"grossMargin":{"type":"number","nullable":true,"description":"(Fintech) Gross Profit / Revenue (%). Separates pure-software fintech (70–80%) from payment processors with interchange costs (40–60%).","example":78.5},"interestCoverage":{"type":"number","nullable":true,"description":"(Aerospace & Defense, Airlines) Operating Income / abs(Interest Expense) (ratio).","example":6.5},"inventoryTurnover":{"type":"number","nullable":true,"description":"(Automotive) COGS / avg(Inventory) (ratio). Higher signals vehicle demand strength.","example":8},"rdToRevenue":{"type":"number","nullable":true,"description":"(Semiconductor, Software & SaaS, Pharma & Biotech, Aerospace & Defense, Automotive, Fintech) Research & Development / Revenue (%).","example":11.53},"remainingPerformanceObligations":{"type":"number","nullable":true,"description":"(Software & SaaS) RPO (USD). Total contracted revenue not yet recognized; growing RPO signals future revenue visibility.","example":375000000000},"sbcToRevenue":{"type":"number","nullable":true,"description":"(Semiconductor, Software & SaaS, Pharma & Biotech, Fintech) Stock-Based Compensation / Revenue (%).","example":4.25},"sgaToRevenue":{"type":"number","nullable":true,"description":"(Software & SaaS, Fintech) SG&A / Revenue (%). Declining as revenue scales is the hallmark of operating leverage.","example":11.67}}},"EconSource":{"type":"object","description":"Per-claim citation. A URL to an authoritative SEC filing, the section the claim is drawn from, a verbatim quote machine-verified against the filing text, and the derived publisher host.","required":["url","source","publisher","section","quote"],"properties":{"url":{"type":"string","format":"uri","description":"HTTPS URL to the cited document (SEC EDGAR 10-K / 10-Q / 8-K, investor presentation, earnings call, or website)","example":"https://www.sec.gov/Archives/edgar/data/320193/000032019324000123/aapl-20240928.htm"},"source":{"type":"string","description":"Document kind","enum":["10-K","investor-presentation","earnings-call","website"]},"publisher":{"type":"string","description":"URL host, derived server-side (e.g., `www.sec.gov`).","example":"www.sec.gov"},"section":{"type":"string","description":"Named location within the document (e.g., `Item 7 MD&A`, `Note 3 — Revenue`, `Recent Developments`).","example":"Item 1. Business — AppLovin Platform"},"quote":{"type":"string","description":"Verbatim excerpt (20–400 characters) copied word-for-word from the cited section. Machine-verified at generation time."},"validated":{"type":"boolean","description":"Present and `false` only when the URL could not be re-fetched at verification time (e.g., 403/429/timeout). Absent ≡ fully verified."}}},"ExposureSource":{"type":"object","description":"Per-claim citation for an ETF exposure-model claim. Verbatim quote is machine-verified against the pre-fetched filing text at generation time.","required":["url","source","publisher","section","quote"],"properties":{"url":{"type":"string","format":"uri","description":"HTTPS URL to the cited SEC filing or issuer page","example":"https://www.sec.gov/Archives/edgar/data/1100663/000168386324004127/primary_doc.htm"},"source":{"type":"string","description":"Document kind","enum":["prospectus","N-CSR","N-CSRS","N-CEN","N-PORT","issuer-website"]},"publisher":{"type":"string","description":"URL host, derived server-side (e.g., `www.sec.gov`).","example":"www.sec.gov"},"section":{"type":"string","description":"Named location within the document (e.g., `Principal Investment Strategies`, `Principal Investment Risks`, `Expense Example`).","example":"Principal Investment Strategies"},"quote":{"type":"string","description":"Verbatim excerpt (20–400 characters). Machine-verified at generation time."},"validated":{"type":"boolean","description":"Present and `false` only when the URL could not be re-fetched at verification time. Absent ≡ fully verified."}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your StockFit API token"}}},"security":[{"bearerAuth":[]}],"paths":{"/api/company/details":{"get":{"tags":["Company"],"summary":"Company details","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns company profile including description, SIC industry/sector classification, fiscal year end, exchange listings, and contact address.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Detailed company information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyDetails"}}}},"400":{"description":"Invalid parameters or company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/company/details-batch":{"get":{"tags":["Company"],"summary":"Batch company details","description":"![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns company profiles for multiple symbols in a single request. Same data as `/details` but keyed by symbol. Maximum 50 symbols per request.\n","parameters":[{"in":"query","name":"symbols","required":true,"schema":{"type":"string","minLength":1,"maxLength":100},"description":"Comma-separated list of stock ticker symbols (max 50)","example":"AAPL,MSFT,GOOGL"}],"responses":{"200":{"description":"Map of symbol to company details","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CompanyDetails"}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/company/research-summary":{"get":{"tags":["Company"],"summary":"Research summary","description":"![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nCompressed research endpoint: returns company profile, earnings snapshot (EPS, margins, returns, health scores, predicted dates),\nand sector-aware key metrics in a single call. Replaces 3 separate API calls.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","schema":{"type":"integer"},"description":"Company CIK number. Alternative to `symbol` - provide one or the other."}],"responses":{"200":{"description":"Combined research summary","content":{"application/json":{"schema":{"type":"object","properties":{"profile":{"$ref":"#/components/schemas/CompanyDetails"},"snapshot":{"type":"object","description":"Earnings snapshot with EPS, margins, returns, health scores, and predicted dates. Same shape as `/api/earnings/snapshot`.","properties":{"symbol":{"type":"string","example":"AAPL"},"period":{"type":"string","description":"Fiscal period end date (YYYY-MM-DD)","example":"2025-09-26"},"fiscalYear":{"type":"integer","example":2025},"fiscalPeriod":{"type":"string","enum":["FY","Q1","Q2","Q3","Q4","TTM"],"example":"FY"},"eps":{"type":"number","nullable":true,"example":7.49},"epsDiluted":{"type":"number","nullable":true,"example":7.46},"netIncome":{"type":"number","nullable":true,"example":112010000000},"revenue":{"type":"number","nullable":true,"example":416161000000},"grossMargin":{"type":"number","nullable":true,"example":46.91},"operatingMargin":{"type":"number","nullable":true,"example":31.97},"netMargin":{"type":"number","nullable":true,"example":26.92},"roe":{"type":"number","nullable":true,"example":171.42},"roic":{"type":"number","nullable":true,"example":88.61},"freeCashFlow":{"type":"number","nullable":true,"example":98767000000},"fcfToNetIncome":{"type":"number","nullable":true,"example":88.18},"revenueGrowth":{"type":"number","nullable":true,"example":0.0643},"epsGrowth":{"type":"number","nullable":true,"example":0.2259},"netIncomeGrowth":{"type":"number","nullable":true,"example":0.195},"piotroskiFScore":{"type":"integer","example":8},"altmanZScore":{"type":"number","nullable":true,"example":null},"altmanZone":{"type":"string","nullable":true,"enum":["safe","grey","distress",null],"example":null},"nextEarningsDate":{"type":"string","nullable":true,"example":"2026-04-30"},"nextFilingDate":{"type":"string","nullable":true,"example":"2026-05-01"}}},"keyMetrics":{"type":"object","nullable":true,"description":"Sector-aware key metrics for the latest period. Same shape as `/api/financials/key-metrics` — see `KeyMetricsGeneral`, `KeyMetricsSector`, and `KeyMetricsIndustry` for the full per-key catalog.","properties":{"period":{"type":"string","format":"date","example":"2025-06-30"},"fiscalYear":{"type":"integer","example":2025},"fiscalPeriod":{"type":"string","enum":["FY","Q1","Q2","Q3","Q4","TTM"],"example":"FY"},"sector":{"type":"string","nullable":true,"example":"Services"},"sectorId":{"type":"string","nullable":true,"description":"One of: `agriculture`, `banking`, `construction`, `insurance`, `manufacturing`, `mining`, `reit`, `retail-trade`, `services`, `telecom`, `transportation`, `utilities`, `wholesale`, or `null`.","example":"services"},"industry":{"type":"string","nullable":true,"example":"Software Publishers"},"industryId":{"type":"string","nullable":true,"description":"One of: `semiconductor`, `software`, `pharma`, `aerospace`, `automotive`, `airlines`, `oil-gas`, `fintech`, or `null`.","example":"software"},"general":{"$ref":"#/components/schemas/KeyMetricsGeneral"},"sectorMetrics":{"$ref":"#/components/schemas/KeyMetricsSector"},"industryMetrics":{"$ref":"#/components/schemas/KeyMetricsIndustry"}}}}},"example":{"profile":{"name":"MICROSOFT CORP","cik":789019,"description":"## Business Overview\nMicrosoft develops and sells **software, cloud services, and devices**, led by **Azure**, **Microsoft 365**, **Windows**, and **Dynamics 365**, plus **LinkedIn** and **Xbox**. Revenue is primarily **recurring (subscriptions/consumption)** with additional **licensing, advertising, and hardware** sales. \n\n## Market Position\nMicrosoft is a global leader in **cloud infrastructure/platform services** and **enterprise productivity** with a large installed base and broad distribution across consumers and enterprises. Key differentiators include deep integration across **Azure + Windows + Microsoft 365 + security**, a large partner ecosystem, and extensive developer tooling (e.g., **GitHub**). \n\n## Key Segments\nMicrosoft reports three operating segments: **Productivity and Business Processes**, **Intelligent Cloud**, and **More Personal Computing**.","sic":"7372","sector":"Services","industry":"Software Publishers","industryGroup":"Software & SaaS","fiscalYearEndMonth":6,"fiscalYearEndDay":30,"exchanges":["Nasdaq"],"address":"ONE MICROSOFT WAY","city":"REDMOND","state":"WA","zip":"98052-6399","country":null,"phone":"425-882-8080","webUrl":"https://www.microsoft.com","investorRelationsUrl":"https://www.microsoft.com/en-us/investor/default","logoUrl":null,"type":"stock","ipoDate":"2020-05-20"},"snapshot":{"symbol":"MSFT","period":"2025-06-30","fiscalYear":2025,"fiscalPeriod":"FY","eps":13.7,"epsDiluted":13.64,"netIncome":101832000000,"revenue":281724000000,"grossMargin":68.82,"operatingMargin":45.62,"netMargin":36.15,"roe":33.28,"roic":31.9,"freeCashFlow":71611000000,"fcfToNetIncome":70.32,"revenueGrowth":0.1493,"epsGrowth":0.1551,"netIncomeGrowth":0.1554,"piotroskiFScore":6,"altmanZScore":2.5,"altmanZone":"grey","nextEarningsDate":"2026-04-29","nextFilingDate":"2026-04-29"},"keyMetrics":{"period":"2025-06-30","fiscalYear":2025,"fiscalPeriod":"FY","sector":"Services","sectorId":"services","industry":"Software Publishers","industryId":"software","general":{"revenue":281724000000,"netIncome":101832000000,"grossMargin":68.8237423861652,"operatingMargin":45.62195624085985,"profitMargin":36.146015248967075,"debtToEquity":0.12562922332951942,"quickRatio":0.7091659703437239,"currentRatio":1.3534464445042416,"roa":18.004784443662558,"roe":33.280824111537434,"roic":31.896602768520527,"eps":13.7,"ebitda":123803000000,"freeCashFlow":71611000000,"fcfMargin":25.418849654271558,"fcfNetIncome":70.3226883494383,"assetTurnover":0.49811256703260176,"interestCoverage":53.89014675052411,"netDebt":18964000000,"netDebtEbitda":0.15317884057736889,"investedCapital":362443000000,"sbcRevenue":4.250259118853913,"dividendPayout":23.648754811846963,"netShareChange":0,"cashRatio":0.2142,"operatingCashFlowRatio":0.9642,"receivablesTurnover":4.4426,"payablesTurnover":3.533,"inventoryTurnover":80.4313,"fixedAssetTurnover":1.6545,"financialLeverageRatio":1.8022,"longTermDebtToCapitalRatio":0.1116,"freeCashFlowOperatingCashFlowRatio":0.5259,"capitalExpenditureCoverageRatio":2.1094,"pretaxProfitMargin":0.4388,"effectiveTaxRate":0.1763,"revenuePerShare":37.7393,"netIncomePerShare":13.6413,"operatingCashFlowPerShare":18.2401,"freeCashFlowPerShare":9.5929,"cashPerShare":4.0512,"bookValuePerShare":46.0119},"sectorMetrics":{"grossMargin":68.8237423861652,"operatingMargin":45.62195624085985,"ebitdaMargin":43.94478283710298,"netMargin":36.146015248967075,"sgaRevenue":11.669932274140649,"roe":33.280824111537434,"dso":82.15946280757053},"industryMetrics":{"rdToRevenue":11.531853871164687,"sgaToRevenue":11.669932274140649,"sbcToRevenue":4.250259118853913,"fcfMargin":25.418849654271558,"deferredRevenue":64555000000,"deferredRevenueGrowth":12.10968705498246,"billings":288697000000,"remainingPerformanceObligations":375000000000}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/company/stock-splits":{"get":{"tags":["Company"],"summary":"Stock splits (per company)","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns the full history of stock splits for a single company, sourced from XBRL footnote disclosures (`us-gaap:StockholdersEquityNoteStockSplitConversionRatio1` and its pre-2015 predecessor `us-gaap:StockholdersEquityNoteStockSplitConversionRatio`) in 10-K and 10-Q filings. Each event carries the split date, the conversion ratio, the type (`forward` or `reverse`), and provenance fields tying back to the original SEC filing.\n\n## Coverage\n\n- Forward and reverse splits since the XBRL mandate (post-2009; reliably tagged from 2011 onward).\n- Both types ride the same XBRL field — forwards report ratios `> 1` (e.g. `4.0` for a 4-for-1), reverses report fractional ratios (e.g. `0.05` for a 1-for-20).\n- Roughly 2,500 distinct US companies have at least one tagged split event.\n- Pre-2010 splits are out of scope (predates XBRL).\n\n## Caveats\n\n- **`firstDisclosedAt` is not the announcement date.** It's when the structured XBRL fact first became available in an SEC filing. Some filers tag the split in the very next 10-Q (≈30-90 days lag); others wait until the annual 10-K (up to ~12 months). For real-time corporate-action use cases, pair with a dedicated corporate-actions feed.\n- **`date` semantics vary by filer.** Most filers tag the ex-date / payable date, but a minority tag the announcement date or the record date. Cross-check against an authoritative source for time-sensitive backtests.\n- **Noop disclosures excluded.** Rows with `ratio = 1` (informational disclosures with no actual share-count change) are filtered out.\n\nResults are ordered by split date descending. No pagination — even the most prolific splitter has fewer than ten events on record.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"List of stock split events ordered by date (most recent first). Empty array if the company has no recorded splits.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["date","ratio","type","accession","firstDisclosedAt"],"properties":{"date":{"type":"string","format":"date","description":"The split date as tagged in the XBRL footnote (typically the ex-date or payable date; see caveats in the endpoint description). Format YYYY-MM-DD.","example":"2020-08-28"},"ratio":{"type":"number","description":"The conversion ratio. For a forward split, the number of post-split shares received per pre-split share (e.g. `4` for a 4-for-1 split). For a reverse split, the fractional equivalent (e.g. `0.05` for a 1-for-20 reverse split — 20 old shares become 1 new share).\n\nTo compute the post-split share count from a pre-split count: `postSplit = preSplit × ratio`.\n","example":4},"type":{"type":"string","enum":["forward","reverse"],"description":"Split direction, derived from `ratio`:\n\n| Value | Meaning |\n|-------|---------|\n| `forward` | `ratio > 1` — share count increases, per-share price decreases. Typical of large-caps managing share price after a long run-up. |\n| `reverse` | `ratio < 1` — share count decreases, per-share price increases. Often used by small-caps to maintain exchange listing requirements (e.g. NASDAQ minimum bid price). |\n","example":"forward"},"accession":{"type":"string","description":"SEC accession number of the filing where this split was first disclosed in XBRL. Use this with the SEC EDGAR full-text search to retrieve the exact source filing.","example":"0000320193-20-000096"},"firstDisclosedAt":{"type":"string","format":"date","description":"SEC acceptance date (YYYY-MM-DD) of the filing referenced by `accession` — the earliest date this split was machine-readable from EDGAR. Note this lags the actual split date by anywhere from weeks to months depending on the filer's reporting cadence.","example":"2020-10-30"}}}},"example":[{"date":"2020-08-28","ratio":4,"type":"forward","accession":"0000320193-20-000096","firstDisclosedAt":"2020-10-30"},{"date":"2014-06-06","ratio":7,"type":"forward","accession":"0001193125-14-277160","firstDisclosedAt":"2014-07-23"}]}}},"400":{"description":"Invalid parameters or symbol not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/company/delisted":{"get":{"tags":["Company"],"summary":"List delisted companies","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nPaginated list of delisted public companies (stocks no longer listed on Nasdaq, NYSE, or NYSE Arca), sorted by delisting date with the most recent first. Each entry's `delistedAt` is sourced from the company's SEC Form 25-NSE filing — the exchange's official \"Notification of Removal from Listing\" — which carries an authoritative signature date. Companies may continue filing with the SEC during deregistration or after moving to OTC; that is reflected accurately here.\n","parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1},"description":"Page number (1-indexed)"},{"in":"query","name":"pageSize","schema":{"type":"integer","default":100,"minimum":1,"maximum":1000},"description":"Number of results per page"}],"responses":{"200":{"description":"Paginated list of delisted companies, newest delistings first","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer","example":1},"pageSize":{"type":"integer","example":100},"totalPages":{"type":"integer","example":1},"totalResults":{"type":"integer","example":81},"data":{"type":"array","items":{"$ref":"#/components/schemas/SymbolProfile"}}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/company/recent-stock-splits":{"get":{"tags":["Company"],"summary":"Recent stock splits (market-wide)","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nCross-company feed of recent stock splits across the entire SEC EDGAR universe, ordered by split date descending. Each entry attaches the company's primary ticker and name. Sourced from the same XBRL footnote disclosures as `/api/company/stock-splits` — see that endpoint for data-source details and caveats.\n\nUse this to monitor corporate-action activity at the market level (e.g. screening for upcoming split-driven trades, surfacing reverse-split candidates that signal listing-compliance pressure).\n\n## Notes\n\n- **Lookback window** is configurable via `days` (default 90, max 365). The window applies to the split date itself, not the disclosure date.\n- **`firstDisclosedAt` lag.** XBRL splits are tagged in the next 10-K/10-Q after the event, so very recent splits may not yet appear here. A split executed today typically surfaces within 30-90 days. For real-time corporate-action use cases, pair with a dedicated corporate-actions feed.\n- **Reverse splits dominate the feed.** ~1,300 of the ~2,500 covered companies do reverse splits (often nano/micro-caps maintaining exchange listing requirements), versus ~1,200 doing forward splits. Filter by `type` client-side if you want only forwards.\n- **Noop disclosures excluded.** Rows with `ratio = 1` (informational disclosures with no actual share-count change) are filtered out.\n","parameters":[{"in":"query","name":"days","required":false,"schema":{"type":"integer","minimum":1,"maximum":365,"default":90},"description":"Lookback window in days, applied to the split date. Default 90.","example":90},{"in":"query","name":"page","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1},"description":"Page number (1-indexed)","example":1},{"in":"query","name":"pageSize","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Number of results per page","example":20}],"responses":{"200":{"description":"Paginated list of recent stock splits, newest first.","content":{"application/json":{"schema":{"type":"object","required":["page","pageSize","totalPages","totalResults","data"],"properties":{"page":{"type":"integer","example":1},"pageSize":{"type":"integer","example":20},"totalPages":{"type":"integer","example":7},"totalResults":{"type":"integer","example":131},"data":{"type":"array","items":{"type":"object","required":["cik","date","ratio","type","accession","firstDisclosedAt"],"properties":{"symbol":{"type":"string","nullable":true,"description":"The company's primary ticker symbol. Null if the company has no listed ticker (rare — typically delisted issuers still filing with the SEC).","example":"TSLA"},"name":{"type":"string","nullable":true,"description":"Company name as registered with the SEC.","example":"Tesla, Inc."},"cik":{"type":"integer","description":"SEC Central Index Key (always present, even when `symbol` is null).","example":1318605},"date":{"type":"string","format":"date","description":"The split date as tagged in the XBRL footnote (typically the ex-date or payable date). Format YYYY-MM-DD.","example":"2022-08-05"},"ratio":{"type":"number","description":"The conversion ratio. `> 1` for forward splits (e.g. `3` = 3-for-1), `< 1` for reverse splits (e.g. `0.05` = 1-for-20). Compute post-split share count as `preSplit × ratio`.","example":3},"type":{"type":"string","enum":["forward","reverse"],"description":"Split direction, derived from `ratio`:\n\n| Value | Meaning |\n|-------|---------|\n| `forward` | `ratio > 1` — share count increases, per-share price decreases. |\n| `reverse` | `ratio < 1` — share count decreases, per-share price increases. |\n","example":"forward"},"accession":{"type":"string","description":"SEC accession number of the filing where this split was first disclosed in XBRL.","example":"0000950170-22-019867"},"firstDisclosedAt":{"type":"string","format":"date","description":"SEC acceptance date (YYYY-MM-DD) of the filing referenced by `accession`. Lags the split date by weeks to months.","example":"2022-10-24"}}}}}},"example":{"page":1,"pageSize":20,"totalPages":7,"totalResults":131,"data":[{"symbol":"TSLA","name":"Tesla, Inc.","cik":1318605,"date":"2022-08-05","ratio":3,"type":"forward","accession":"0000950170-22-019867","firstDisclosedAt":"2022-10-24"},{"symbol":"GOOGL","name":"Alphabet Inc.","cik":1652044,"date":"2022-07-15","ratio":20,"type":"forward","accession":"0001652044-23-000016","firstDisclosedAt":"2023-02-03"}]}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/company/economic-model":{"get":{"tags":["Company"],"summary":"Full audit-grade economic model (lazy-generated)","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\n## 🔒 Audit-grade by construction\n\n**Every claim in this response — except peer identity — is defensible in an IC meeting or audit.** Most competing \"AI fundamentals\" APIs return plausible-sounding prose you cannot verify. This endpoint is different. For each claim you get:\n\n- 🔗 a clickable URL to the exact authoritative document (SEC EDGAR 10-K / 10-Q / 8-K),\n- 📄 the document section the claim is drawn from (e.g., `Item 7 MD&A`, `Note 3 — Revenue`),\n- 💬 a **verbatim quote** from that section (20–400 characters, copied word-for-word),\n- ✅ **machine-verified at generation time** — we fetch the filing, strip HTML, and confirm the quote literally appears in the document before we store it. Fabricated or paraphrased quotes are rejected and the model is regenerated.\n\nAn analyst can click a URL, jump to the section, `Ctrl-F` the quote, and have the source paragraph in front of them in ten seconds. No more \"trust me, the AI read the filing.\"\n\n## What's in the model\n\nOfferings, value delivery, monetization, cost structure, reinvestment, cash conversion, sensitivities, unit economics, capital allocation, management style, peers, operating levers, strategic initiatives, structural advantages, flywheels, and failure modes.\n\nPeers are an analytical judgment (the competitive landscape rarely names itself verbatim in a 10-K), so peers do not carry sources. Every other section and array item does.\n\n## Two possible response shapes\n\n### ✅ `200 OK` — model is ready\n\nReturns the full `EconomicModel` JSON. Stable and safe to cache client-side.\n\n### ⏳ `202 Accepted` — model is being generated\n\nThe model for this company has never been built. A background job has been queued (or one was already in flight).\n\n**Generation takes a few minutes.** The job fetches the company's latest 10-K, 10-Q, and 8-Ks directly from SEC EDGAR, passes them to the AI along with strict citation requirements, verifies every quote against the filing text, and writes the result.\n\n**Poll this same endpoint** with the same `symbol` — once the job completes you will start receiving the `200` response. A reasonable poll interval is every 30 seconds.\n\n```json\n{\n  \"status\": \"generating\",\n  \"jobId\": \"64abfe1234567890abcdef12\",\n  \"message\": \"Generating economic model — this can take a few minutes. Call this endpoint again to retrieve the result.\"\n}\n```\n\n## Deduplication\n\nIf a generation job is already in flight for this company — regardless of which account queued it — this endpoint returns the existing `jobId`. You will never queue two generations for the same company.\n\n## Cost\n\nGeneration runs server-side and does not count against your API request budget beyond the call to this endpoint.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Model is ready. Full economic model JSON with per-claim SEC-filing citations.","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","description":"High-level inventory of what the company sells.","properties":{"primaryOfferings":{"type":"array","items":{"type":"string"}},"secondaryOfferings":{"type":"array","items":{"type":"string"}}}},"valueDelivery":{"type":"object","description":"How the company creates value and who pays for it.","properties":{"offeringTypes":{"type":"array","items":{"type":"string"}},"customer":{"type":"object","properties":{"primaryPayerTypes":{"type":"array","items":{"type":"string"}},"demandDriver":{"type":"string"}}},"unitOfValue":{"type":"string"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/EconSource"}}}},"monetization":{"type":"object","description":"Revenue model, pricing mechanisms, pricing power, and revenue drivers.","properties":{"revenueModel":{"type":"string","description":"one-time | recurring | hybrid"},"pricingMechanisms":{"type":"array","items":{"type":"string"}},"priceSettingPower":{"type":"string","description":"price-taker | some | strong | regulated | unknown"},"primaryRevenueDrivers":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/EconSource"}}}},"costStructure":{"type":"object","description":"Variable and fixed cost drivers, margin mechanics, primary constraint.","properties":{"variableCostDrivers":{"type":"array","items":{"type":"string"}},"fixedCostDrivers":{"type":"array","items":{"type":"string"}},"marginDriverMechanisms":{"type":"array","items":{"type":"string"}},"primaryConstraint":{"type":"string"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/EconSource"}}}},"reinvestment":{"type":"object","description":"Capital intensity and reinvestment orientation.","properties":{"capitalIntensity":{"type":"string","description":"asset-light | moderate | asset-heavy | regulated-asset-base | unknown"},"reinvestmentVehicles":{"type":"array","items":{"type":"string"}},"maintenanceVsGrowth":{"type":"string","description":"mostly-maintenance | balanced | mostly-growth | unknown"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/EconSource"}}}},"cashConversion":{"type":"object","description":"Working-capital profile and cash-flow timing.","properties":{"workingCapitalProfile":{"type":"string","description":"negative | neutral | positive | seasonal | unknown"},"cashTimingNotes":{"type":"string"},"keyBalanceSheetSensitivities":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/EconSource"}}}},"sensitivities":{"type":"object","description":"What moves top line, margin, and balance sheet.","properties":{"topLineSensitivities":{"type":"array","items":{"type":"string"}},"marginSensitivities":{"type":"array","items":{"type":"string"}},"balanceSheetSensitivities":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/EconSource"}}}},"unitEconomics":{"type":"object","description":"Per-unit revenue drivers, variable costs, and marginal margin.","properties":{"unit":{"type":"string"},"revenueDrivers":{"type":"array","items":{"type":"string"}},"variableCosts":{"type":"array","items":{"type":"string"}},"marginalMargin":{"type":"string","description":"low | mid | high"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/EconSource"}}}},"capitalAllocation":{"type":"object","description":"Capital-allocation priorities, historical pattern, and metrics to watch.","properties":{"priorities":{"type":"array","items":{"type":"string"}},"historicalPattern":{"type":"string"},"watchMetrics":{"type":"array","nullable":true,"items":{"type":"string"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/EconSource"}}}},"managementStyle":{"type":"object","description":"Management orientation and strategy notes.","properties":{"orientation":{"type":"string","description":"growth-first | margin-first | balanced | capital-return"},"strategyNotes":{"type":"string"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/EconSource"}}}},"provenance":{"type":"object","description":"Whole-model confidence and a deduped list of the source kinds cited across the model.","properties":{"confidence":{"type":"string","description":"low | medium | high"},"sources":{"type":"array","items":{"type":"string"}}}},"offerings":{"type":"array","description":"Structured list of each product or service with monetization, economics notes, KPIs, and citations.","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","description":"product | service | platform | bundle"},"category":{"type":"string","nullable":true},"targetCustomer":{"type":"string","nullable":true},"revenueRole":{"type":"string","description":"core | growth | adjacent | legacy | other"},"monetization":{"type":"object","nullable":true,"properties":{"model":{"type":"string"},"pricingUnit":{"type":"string","nullable":true}}},"economicsNotes":{"type":"object","nullable":true,"properties":{"marginProfile":{"type":"string","nullable":true},"keyCostDrivers":{"type":"array","nullable":true,"items":{"type":"string"}},"keyGrowthDrivers":{"type":"array","nullable":true,"items":{"type":"string"}}}},"kpiMappings":{"type":"object","nullable":true,"properties":{"primaryMetrics":{"type":"array","nullable":true,"items":{"type":"string"}},"supportingMetrics":{"type":"array","nullable":true,"items":{"type":"string"}}}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/EconSource"}}}}},"operatingLevers":{"type":"array","description":"Named operating levers with directionality (↑ lever → ↑ revenue, etc.) and the metrics they map to.","items":{"type":"object","properties":{"lever":{"type":"string"},"directionality":{"type":"string"},"mapsToMetrics":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/EconSource"}}}}},"peers":{"type":"object","description":"AI-identified peers split into primary (close economic analogs) and secondary (broader comparables), plus a comparison framework. **Peers do NOT carry per-item sources** — peer identification is an analytical judgment.","properties":{"primary":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"name":{"type":"string","nullable":true},"relation":{"type":"string","description":"direct-competitor | closest-economic-analog | adjacent-competitor | substitute | customer | supplier | platform-ecosystem | benchmark-only | other"},"rationale":{"type":"array","items":{"type":"string"}},"comparableSegments":{"type":"array","nullable":true,"items":{"type":"string"}},"kpiMappings":{"type":"object","nullable":true,"properties":{"primaryMetrics":{"type":"array","items":{"type":"string"}},"supportingMetrics":{"type":"array","items":{"type":"string"}}}},"comparisonNotes":{"type":"string","nullable":true}}}},"secondary":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"relation":{"type":"string"},"rationale":{"type":"array","items":{"type":"string"}}}}},"comparisonFramework":{"type":"object","nullable":true,"properties":{"basis":{"type":"array","items":{"type":"string"}},"doNotCompareOn":{"type":"array","items":{"type":"string"}},"notes":{"type":"string"}}}}},"strategicInitiatives":{"type":"array","description":"Named initiatives with stage, expected impact, time horizon, affected levers, metrics to watch, and citations.","items":{"type":"object","properties":{"initiative":{"type":"string"},"category":{"type":"string"},"rationale":{"type":"string"},"financialImpact":{"type":"string"},"stage":{"type":"string","description":"announced | early | scaling | mature"},"impactLevel":{"type":"string","description":"minor | moderate | major"},"timeHorizon":{"type":"string","description":"short | medium | long"},"affectsLevers":{"type":"array","nullable":true,"items":{"type":"string"}},"watchMetrics":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/EconSource"}}}}},"structuralAdvantages":{"type":"array","description":"Moat elements with type, mechanism, persistence, affected levers, and citations.","items":{"type":"object","properties":{"advantage":{"type":"string"},"type":{"type":"string","description":"network-effect | switching-cost | scale-economy | data-advantage | brand | regulatory-moat | distribution | ip-patents | other"},"mechanism":{"type":"string"},"persistence":{"type":"string","description":"weak | moderate | strong"},"affectsLevers":{"type":"array","items":{"type":"string"}},"watchMetrics":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/EconSource"}}}}},"flywheels":{"type":"array","description":"Causal loops (growth / margin / defensibility) with ordered steps and citations.","items":{"type":"object","properties":{"name":{"type":"string"},"loop":{"type":"array","items":{"type":"string"}},"impact":{"type":"string","description":"growth | margin | defensibility"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/EconSource"}}}}},"failureModes":{"type":"array","description":"Risks that could break the business model, with mechanism, metrics to watch, and citations.","items":{"type":"object","properties":{"risk":{"type":"string"},"mechanism":{"type":"string"},"watchMetrics":{"type":"array","nullable":true,"items":{"type":"string"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/EconSource"}}}}}}}}}},"202":{"description":"Model generation has been queued (or one is already in flight). Poll the same URL for the finished result.","content":{"application/json":{"schema":{"type":"object","required":["status","jobId","message"],"properties":{"status":{"type":"string","enum":["generating"],"example":"generating"},"jobId":{"type":"string","description":"ID of the background job","example":"64abfe1234567890abcdef12"},"message":{"type":"string","example":"Generating economic model — this can take a few minutes. Call this endpoint again to retrieve the result."}}}}}},"400":{"description":"Invalid parameters or company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/earnings/eps-history":{"get":{"tags":["Earnings"],"summary":"EPS history","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns earnings per share over time with basic and diluted EPS, net income, share counts, and year-over-year growth.\nData is sourced from SEC XBRL filings (10-K and 10-Q). Periods are sorted most recent first.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"Stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"period","required":false,"schema":{"type":"string","enum":["annual","quarter","ttm"],"default":"annual"},"description":"Reporting period. `ttm` returns trailing twelve months (single entry)."},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":80,"default":10},"description":"Maximum number of periods to return (may be clamped by subscription tier)"}],"responses":{"200":{"description":"Array of EPS history entries sorted most recent first","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string","description":"Fiscal period end date (YYYY-MM-DD)","example":"2024-09-28"},"fiscalYear":{"type":"integer","description":"The company's fiscal year (handles non-December year-ends — AAPL FY ends Sep, COST FY ends Aug).","example":2025},"fiscalPeriod":{"type":"string","enum":["FY","Q1","Q2","Q3","Q4","TTM"],"description":"The fiscal period type. `FY` for annual, `Q1`-`Q4` for quarterly, `TTM` for trailing-twelve-months.","example":"FY"},"eps":{"type":"number","nullable":true,"description":"Basic earnings per share","example":6.08},"epsDiluted":{"type":"number","nullable":true,"description":"Diluted earnings per share","example":6.04},"netIncome":{"type":"number","nullable":true,"description":"Net income in USD","example":93736000000},"sharesOutstanding":{"type":"number","nullable":true,"description":"Basic shares outstanding","example":15408095000},"sharesOutstandingDiluted":{"type":"number","nullable":true,"description":"Diluted weighted average shares outstanding","example":15515175000},"epsGrowth":{"type":"number","nullable":true,"description":"Year-over-year EPS growth as a decimal (0.11 = 11%)","example":0.1068}}}}}}},"400":{"description":"Invalid parameters or symbol not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/earnings/dividend-history":{"get":{"tags":["Earnings"],"summary":"Dividend history","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns dividend history for the given company symbol. Includes dividend per share (total dividends / shares outstanding),\npayout ratio (dividends / net income), dividend coverage (operating cash flow / dividends), and year-over-year growth.\nNon-dividend-paying companies return null values. Data is sourced from SEC XBRL filings (10-K and 10-Q).\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"Stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"period","required":false,"schema":{"type":"string","enum":["annual","quarter","ttm"],"default":"annual"},"description":"Reporting period. `ttm` returns trailing twelve months (single entry)."},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":40,"default":10},"description":"Maximum number of periods to return (may be clamped by subscription tier)"}],"responses":{"200":{"description":"Array of dividend history entries sorted most recent first","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string","description":"Fiscal period end date (YYYY-MM-DD)","example":"2024-09-28"},"fiscalYear":{"type":"integer","description":"The company's fiscal year (handles non-December year-ends — AAPL FY ends Sep, COST FY ends Aug).","example":2025},"fiscalPeriod":{"type":"string","enum":["FY","Q1","Q2","Q3","Q4","TTM"],"description":"The fiscal period type. `FY` for annual, `Q1`-`Q4` for quarterly, `TTM` for trailing-twelve-months.","example":"FY"},"dividendPerShare":{"type":"number","nullable":true,"description":"Dividend per share (total dividends / weighted average shares outstanding)","example":0.99},"totalDividendsPaid":{"type":"number","nullable":true,"description":"Total cash dividends paid in USD","example":15234000000},"payoutRatio":{"type":"number","nullable":true,"description":"Payout ratio as a decimal (dividends / net income). Above 1.0 means paying more than earned.","example":0.1625},"dividendCoverage":{"type":"number","nullable":true,"description":"Dividend coverage ratio (operating cash flow / dividends). Below 1.0 is unsustainable.","example":7.77},"dividendGrowth":{"type":"number","nullable":true,"description":"Year-over-year dividend per share growth as a decimal (0.05 = 5%)","example":0.0408}}}}}}},"400":{"description":"Invalid parameters or symbol not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/earnings/snapshot":{"get":{"tags":["Earnings"],"summary":"Earnings snapshot","description":"![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nOne-call executive summary of a company's latest annual earnings. Includes core EPS, margins, returns,\ncash quality, year-over-year growth, financial health scores (Piotroski F-Score, Altman Z-Score),\nand predicted next earnings/filing dates.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"Stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Comprehensive earnings snapshot for the latest annual period","content":{"application/json":{"schema":{"type":"object","properties":{"symbol":{"type":"string","example":"AAPL"},"period":{"type":"string","description":"Fiscal period end date (YYYY-MM-DD)","example":"2024-09-28"},"fiscalYear":{"type":"integer","description":"The company's fiscal year (handles non-December year-ends — AAPL FY ends Sep, COST FY ends Aug).","example":2025},"fiscalPeriod":{"type":"string","enum":["FY","Q1","Q2","Q3","Q4","TTM"],"description":"The fiscal period type. `FY` for annual, `Q1`-`Q4` for quarterly, `TTM` for trailing-twelve-months.","example":"FY"},"eps":{"type":"number","nullable":true,"description":"Basic earnings per share","example":6.08},"epsDiluted":{"type":"number","nullable":true,"description":"Diluted earnings per share","example":6.04},"netIncome":{"type":"number","nullable":true,"description":"Net income in USD","example":93736000000},"revenue":{"type":"number","nullable":true,"description":"Total revenue in USD","example":391035000000},"grossMargin":{"type":"number","nullable":true,"description":"Gross margin as a percentage","example":46.23},"operatingMargin":{"type":"number","nullable":true,"description":"Operating margin as a percentage","example":31.51},"netMargin":{"type":"number","nullable":true,"description":"Net profit margin as a percentage","example":23.97},"roe":{"type":"number","nullable":true,"description":"Return on equity as a percentage","example":127.15},"roic":{"type":"number","nullable":true,"description":"Return on invested capital as a percentage","example":57.42},"freeCashFlow":{"type":"number","nullable":true,"description":"Free cash flow in USD","example":108807000000},"fcfToNetIncome":{"type":"number","nullable":true,"description":"Free cash flow to net income ratio as a percentage (>100% = strong cash conversion)","example":116.09},"revenueGrowth":{"type":"number","nullable":true,"description":"Year-over-year revenue growth as a decimal (0.02 = 2%)","example":0.0202},"epsGrowth":{"type":"number","nullable":true,"description":"Year-over-year EPS growth as a decimal","example":0.1068},"netIncomeGrowth":{"type":"number","nullable":true,"description":"Year-over-year net income growth as a decimal","example":0.0843},"piotroskiFScore":{"type":"integer","description":"Piotroski F-Score (0-9). Higher is better. Measures financial strength using 9 binary criteria covering profitability, leverage, and operating efficiency.","minimum":0,"maximum":9,"example":6},"altmanZScore":{"type":"number","nullable":true,"description":"Altman Z-Score for bankruptcy risk. >2.99 = safe, 1.81-2.99 = grey zone, <1.81 = distress.","example":5.72},"altmanZone":{"type":"string","nullable":true,"enum":["safe","grey","distress"],"description":"Altman Z-Score classification","example":"safe"},"nextEarningsDate":{"type":"string","nullable":true,"description":"Predicted next earnings call date (YYYY-MM-DD) or null if unknown","example":"2026-04-24"},"nextFilingDate":{"type":"string","nullable":true,"description":"Predicted next SEC filing date (YYYY-MM-DD) or null if unknown","example":"2026-05-01"}}}}}},"400":{"description":"Invalid parameters or symbol not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/earnings/trends":{"get":{"tags":["Earnings"],"summary":"Earnings trends","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nMulti-year earnings analytics: compound annual growth rates (CAGR), margin trajectories with directional classification,\nmargin volatility, and earnings quality metrics. Computed from up to 12 years of annual SEC filing data.\n\nThis endpoint provides derived analytics that go beyond raw financial statements — margin trajectory direction\n(expanding, compressing, stable), multi-year CAGR across revenue/net income/EPS/FCF, and quality ratios\nlike FCF-to-net-income and interest coverage.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"Stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Multi-year earnings trends and derived analytics","content":{"application/json":{"schema":{"type":"object","properties":{"symbol":{"type":"string","example":"AAPL"},"latestPeriod":{"type":"string","description":"Most recent fiscal period end date","example":"2024-09-28"},"margins":{"type":"object","description":"Margin trajectories comparing current vs 3 years ago with directional classification","properties":{"gross":{"$ref":"#/components/schemas/MarginTrajectory"},"operating":{"$ref":"#/components/schemas/MarginTrajectory"},"net":{"$ref":"#/components/schemas/MarginTrajectory"}}},"netMarginStdDev":{"type":"number","nullable":true,"description":"Standard deviation of net margins across all available history (percentage points). Lower = more predictable earnings.","example":2.3},"netMarginStdDevRecent":{"type":"number","nullable":true,"description":"Standard deviation of net margins over the last 5 years (percentage points). Null if same as full history or insufficient data.","example":1.1},"historicalMaxNetMargin":{"type":"number","nullable":true,"description":"Highest net margin ever recorded (percentage)","example":26.3},"cagr":{"type":"object","description":"Compound annual growth rates. Null if insufficient data for the requested window.","properties":{"revenue3yr":{"type":"number","nullable":true,"description":"3-year revenue CAGR (percentage)","example":7.8},"revenue5yr":{"type":"number","nullable":true,"description":"5-year revenue CAGR (percentage)","example":9.2},"netIncome3yr":{"type":"number","nullable":true,"description":"3-year net income CAGR (percentage)","example":5.4},"netIncome5yr":{"type":"number","nullable":true,"description":"5-year net income CAGR (percentage)","example":10.1},"eps3yr":{"type":"number","nullable":true,"description":"3-year EPS CAGR (percentage)","example":8.6},"eps5yr":{"type":"number","nullable":true,"description":"5-year EPS CAGR (percentage)","example":12.3},"freeCashFlow3yr":{"type":"number","nullable":true,"description":"3-year free cash flow CAGR (percentage)","example":6.9}}},"quality":{"type":"object","description":"Earnings quality metrics from the latest annual period","properties":{"fcfToNetIncome":{"type":"number","nullable":true,"description":"Free cash flow / net income as a percentage. >100% = cash earnings exceed accrual earnings.","example":116.1},"interestCoverage":{"type":"number","nullable":true,"description":"Operating income / interest expense. Higher = safer debt servicing.","example":28.5},"debtToOperatingIncome":{"type":"number","nullable":true,"description":"Total debt / operating income. Lower = faster theoretical payoff.","example":0.7},"roe":{"type":"number","nullable":true,"description":"Return on equity as a percentage","example":127.2}}}}}}}},"400":{"description":"Invalid parameters or symbol not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/earnings/chart/eps":{"get":{"tags":["Earnings"],"summary":"EPS chart","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nChart-ready EPS and net income data over time. Use `series` for absolute values (EPS, Net Income)\nand `rates` for margin ratios (Net Margin). Periods are sorted ascending for direct charting.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"Stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"period","required":false,"schema":{"type":"string","enum":["annual","quarter"],"default":"annual"},"description":"Reporting period"},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":80,"default":10},"description":"Maximum number of periods (may be clamped by subscription tier)"}],"responses":{"200":{"description":"Series-oriented chart data with periods sorted ascending","content":{"application/json":{"schema":{"type":"object","properties":{"periods":{"type":"array","items":{"type":"string"},"description":"Fiscal period end dates sorted ascending","example":["2021-09-25","2022-09-24","2023-09-30","2024-09-28"]},"series":{"type":"array","description":"Absolute value series: EPS (Diluted) and Net Income. Each entry has a `name` and a `data` array parallel to `periods`.","items":{"type":"object","properties":{"name":{"type":"string","example":"EPS (Diluted)"},"data":{"type":"array","items":{"type":"number","nullable":true},"example":[5.61,6.11,6.13,6.04]}}}},"rates":{"type":"array","description":"Margin ratio series (Net Margin) expressed as decimals.","items":{"type":"object","properties":{"name":{"type":"string","example":"Net Margin"},"data":{"type":"array","items":{"type":"number","nullable":true},"example":[0.2588,0.2531,0.2619,0.2397]}}}}}}}}},"400":{"description":"Invalid parameters or symbol not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/earnings/chart/quality":{"get":{"tags":["Earnings"],"summary":"Earnings quality chart","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nChart-ready earnings quality data comparing net income against cash generation over time.\nUse `series` for absolute values (Net Income, Operating Cash Flow, Free Cash Flow) and\n`rates` for quality ratios (FCF/Net Income, OCF/Net Income). Periods are sorted ascending.\n\nA company with FCF consistently exceeding net income has high-quality earnings backed by real cash generation.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"Stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"period","required":false,"schema":{"type":"string","enum":["annual","quarter"],"default":"annual"},"description":"Reporting period"},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":80,"default":10},"description":"Maximum number of periods (may be clamped by subscription tier)"}],"responses":{"200":{"description":"Series-oriented chart data with periods sorted ascending","content":{"application/json":{"schema":{"type":"object","properties":{"periods":{"type":"array","items":{"type":"string"},"description":"Fiscal period end dates sorted ascending","example":["2021-09-25","2022-09-24","2023-09-30","2024-09-28"]},"series":{"type":"array","description":"Absolute value series: Net Income, Operating Cash Flow, Free Cash Flow. Each entry has a `name` and a `data` array parallel to `periods`.","items":{"type":"object","properties":{"name":{"type":"string","example":"Net Income"},"data":{"type":"array","items":{"type":"number","nullable":true},"example":[94680000000,99803000000,96995000000,93736000000]}}}},"rates":{"type":"array","description":"Quality ratio series: FCF / Net Income and OCF / Net Income as decimals. Values above 1.0 indicate strong cash conversion.","items":{"type":"object","properties":{"name":{"type":"string","example":"FCF / Net Income"},"data":{"type":"array","items":{"type":"number","nullable":true},"example":[0.9277,1.0111,1.1113,1.1609]}}}}}}}}},"400":{"description":"Invalid parameters or symbol not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/earnings/calendar":{"get":{"tags":["Earnings"],"summary":"Earnings calendar (batch)","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns approximate upcoming earnings dates for up to 50 symbols in a single request. Dates are predicted based on historical filing patterns and may differ from actual announcements.\n","parameters":[{"in":"query","name":"symbols","required":true,"schema":{"type":"string"},"description":"Comma-separated list of ticker symbols (max 50)","example":"AAPL,MSFT,GOOGL"}],"responses":{"200":{"description":"Map of symbols to earnings date predictions","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"object","properties":{"earningsDate":{"type":"string","nullable":true,"description":"Predicted earnings call date (YYYY-MM-DD) or null if unknown","example":"2026-04-24"},"filingDate":{"type":"string","nullable":true,"description":"Approximate date when the SEC filing (10-Q/10-K) is expected (YYYY-MM-DD) or null if unknown","example":"2026-05-01"}}}},"example":{"AAPL":{"earningsDate":"2026-04-24","filingDate":"2026-05-01"},"MSFT":{"earningsDate":"2026-04-22","filingDate":"2026-04-28"}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/earnings/upcoming":{"get":{"tags":["Earnings"],"summary":"Upcoming earnings (next N days)","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns companies expected to report earnings in the next N days (default 7, max 14), sorted by earnings date ascending. Dates are predicted from historical SEC filing patterns and may differ from actual announcements. Companies in their first year of reporting (no prior-year earnings 8-K) are not included.\n","parameters":[{"in":"query","name":"days","required":false,"schema":{"type":"integer","minimum":1,"maximum":14,"default":7},"description":"Look-ahead window in days. Capped at 14 to keep predictions accurate.","example":7},{"in":"query","name":"page","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number (1-indexed).","example":1},{"in":"query","name":"pageSize","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Results per page.","example":50}],"responses":{"200":{"description":"Paginated list of upcoming earnings.","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number (1-indexed).","example":1},"pageSize":{"type":"integer","description":"Number of results per page.","example":50},"totalPages":{"type":"integer","description":"Total number of pages.","example":3},"totalResults":{"type":"integer","description":"Total companies reporting in the window.","example":142},"data":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string","description":"Primary ticker symbol.","example":"AAPL"},"name":{"type":"string","description":"Company name.","example":"Apple Inc."},"exchanges":{"type":"array","items":{"type":"string"},"description":"Exchanges the company is listed on.","example":["Nasdaq"]},"earningsDate":{"type":"string","description":"Predicted earnings call date (YYYY-MM-DD).","example":"2026-05-01"},"filingDate":{"type":"string","description":"Predicted SEC filing availability date (YYYY-MM-DD).","example":"2026-05-08"},"filingType":{"type":"string","enum":["10-Q","10-K"],"description":"Expected filing type for the upcoming report.","example":"10-Q"}}}}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/earnings/date":{"get":{"tags":["Earnings"],"summary":"Earnings date","description":"![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns the approximate upcoming earnings date for a single stock. Dates are predicted based on historical filing patterns and may differ from actual announcements.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"Stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Earnings date for the symbol","content":{"application/json":{"schema":{"type":"object","properties":{"symbol":{"type":"string","example":"AAPL"},"earningsDate":{"type":"string","nullable":true,"description":"Predicted earnings call date (YYYY-MM-DD) or null if unknown","example":"2026-04-24"},"filingDate":{"type":"string","nullable":true,"description":"Approximate date when the SEC filing (10-Q/10-K) is expected to become available through the SEC (YYYY-MM-DD). The actual filing may appear earlier. Null if unknown.","example":"2026-05-01"}}}}}},"400":{"description":"Invalid parameters or symbol not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/executives/officers":{"get":{"tags":["Executives"],"summary":"Executive Officers","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns the CEO and up to 5 most recently seen Named Executive Officers (NEOs), extracted from DEF 14A proxy statements filed with the SEC.\n\n**Data source:** SEC XBRL-tagged DEF 14A filings. The structured executive compensation disclosure format was standardized by the SEC starting fiscal year 2022, so `firstSeen` does not necessarily represent the start date of the officer's tenure — it reflects the earliest DEF 14A filing in which the officer appeared in standardized XBRL data.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"List of executive officers","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Officer name as disclosed in the proxy statement","example":"Timothy D. Cook"},"role":{"type":"string","description":"`ceo` for the Principal Executive Officer, `officer` for other Named Executive Officers","enum":["ceo","officer"],"example":"ceo"},"firstSeen":{"type":"string","description":"Earliest DEF 14A filing date where this officer appeared (YYYY-MM-DD)","example":"2021-09-25"},"lastSeen":{"type":"string","description":"Most recent DEF 14A filing date where this officer appeared (YYYY-MM-DD)","example":"2024-09-28"}}}}}}},"400":{"description":"Invalid parameters or company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/executives/compensation":{"get":{"tags":["Executives"],"summary":"Compensation & Pay vs Performance","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns historical CEO and officer compensation alongside Total Shareholder Return (TSR) comparison, extracted from the SEC-mandated pay-versus-performance table in DEF 14A proxy statements.\n\n**Compensation fields explained:**\n\n| Field | Description |\n|-------|-------------|\n| `ceoTotalComp` | CEO total compensation as reported in the Summary Compensation Table — includes salary, bonus, stock awards (grant-date fair value), option awards, non-equity incentive plan compensation, pension value changes, and all other compensation |\n| `ceoActuallyPaidComp` | SEC-mandated \"Compensation Actually Paid\" (CAP) metric, introduced in 2022 — adjusts total compensation for actual changes in equity award values during the year, rather than using grant-date fair value. This better reflects what executives actually received |\n| `avgOfficerTotalComp` | Average total compensation for non-CEO Named Executive Officers (NEOs) |\n| `avgOfficerActuallyPaidComp` | Average CAP for non-CEO NEOs |\n\n**TSR fields explained:**\n\nTotal Shareholder Return is indexed to $100 at the start of the measurement period. A value of 178.45 means a $100 investment at the start would now be worth $178.45. The peer group TSR uses the company's self-selected peer group as disclosed in the proxy statement.\n\n**Data source:** SEC XBRL-tagged DEF 14A filings, pay-versus-performance table.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Annual compensation and TSR data","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"fiscalYear":{"type":"integer","example":2024},"ceoTotalComp":{"type":"number","nullable":true,"description":"CEO total compensation (Summary Compensation Table)","example":63208000},"ceoActuallyPaidComp":{"type":"number","nullable":true,"description":"CEO Compensation Actually Paid (equity-adjusted)","example":74608000},"avgOfficerTotalComp":{"type":"number","nullable":true,"description":"Average non-CEO NEO total compensation","example":27133000},"avgOfficerActuallyPaidComp":{"type":"number","nullable":true,"description":"Average non-CEO NEO Compensation Actually Paid","example":31425000},"companyTsr":{"type":"number","nullable":true,"description":"Company Total Shareholder Return (indexed to $100)","example":178.45},"peerGroupTsr":{"type":"number","nullable":true,"description":"Peer group TSR (indexed to $100, company-selected peer group)","example":165.23}}}}}}},"400":{"description":"Invalid parameters or company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/executives/governance":{"get":{"tags":["Executives"],"summary":"Governance Flags","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns corporate governance flags related to executive compensation practices, extracted from DEF 14A proxy statements.\n\nThese flags reveal important governance characteristics around insider trading and compensation award timing:\n\n| Flag | What it means |\n|------|---------------|\n| `insiderTradingPolicy` | Whether the company has formally adopted insider trading policies and procedures |\n| `mnpiConsideredInAwardTiming` | Whether the company considers Material Non-Public Information (MNPI) when timing equity award grants — a \"true\" response indicates the company is aware of the optics around granting awards before material announcements |\n| `awardTimingPredetermined` | Whether equity award grant dates are predetermined (e.g., on a fixed schedule) rather than discretionary — predetermined timing reduces the risk of \"spring-loading\" awards |\n| `mnpiDisclosureTimedForComp` | Whether the company times MNPI disclosures to affect compensation valuations — a \"true\" flag is a potential governance concern |\n\n**Data source:** SEC XBRL-tagged DEF 14A filings.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Governance flags (null if no DEF 14A governance data available)","content":{"application/json":{"schema":{"type":"object","nullable":true,"properties":{"insiderTradingPolicy":{"type":"boolean","nullable":true,"description":"Whether insider trading policies and procedures are adopted","example":true},"mnpiConsideredInAwardTiming":{"type":"boolean","nullable":true,"description":"Whether MNPI is considered when timing equity award grants","example":false},"awardTimingPredetermined":{"type":"boolean","nullable":true,"description":"Whether equity award timing is predetermined","example":true},"mnpiDisclosureTimedForComp":{"type":"boolean","nullable":true,"description":"Whether MNPI disclosure is timed to affect compensation valuation","example":false}}}}}},"400":{"description":"Invalid parameters or company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/executives/performance-measures":{"get":{"tags":["Executives"],"summary":"Company-Selected Performance Measures","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns the performance measures that the company itself selected as most important for evaluating executive compensation, extracted from the pay-versus-performance table in DEF 14A proxy statements.\n\nThese are the KPIs that the board and compensation committee have chosen to link to executive pay — they reveal what management is actually being held accountable for. Common examples include revenue growth, operating margin, return on invested capital, and total shareholder return.\n\nEach measure is reported per fiscal year, allowing tracking of how the company's self-selected performance metrics evolve over time.\n\n**Data source:** SEC XBRL-tagged DEF 14A filings, pay-versus-performance table (Company-Selected Measure).\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Company-selected performance measures by fiscal year","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"fiscalYear":{"type":"integer","example":2024},"measureName":{"type":"string","description":"Company-selected performance measure name","example":"Revenue Growth"},"measureValue":{"type":"number","nullable":true,"description":"The reported value for this measure","example":0.08}}}}}}},"400":{"description":"Invalid parameters or company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/filings/recent-offerings":{"get":{"tags":["SEC Filings"],"summary":"Recent S-1 offerings","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nCross-company endpoint — no symbol required. Returns the most recent S-1/S-1A offering\nper company, filtered to filings within the specified number of days. Useful for tracking\nupcoming IPOs and recent registration statements across the market.\n\nEach result includes the latest offering terms for that company. The `isPriced` flag indicates\nwhether the offering has a price range set (i.e. `priceRangeLow` is not null).\n","parameters":[{"in":"query","name":"days","required":false,"schema":{"type":"integer","minimum":1,"maximum":365,"default":90},"description":"Number of days to look back for recent offerings","example":90},{"in":"query","name":"page","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1},"description":"Page number (1-indexed)"},{"in":"query","name":"pageSize","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Number of offerings per page"}],"responses":{"200":{"description":"Paginated list of recent S-1 offerings across all companies","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer","example":1},"pageSize":{"type":"integer","example":20},"totalPages":{"type":"integer","example":3},"totalResults":{"type":"integer","example":47},"data":{"type":"array","items":{"type":"object","description":"Fields that aren't reported on a given S-1 are omitted rather than returned as null.","properties":{"cik":{"type":"integer","description":"SEC CIK number","example":1713445},"filedDate":{"type":"string","description":"Filing date (YYYY-MM-DD)","example":"2024-02-22"},"isPriced":{"type":"boolean","description":"Whether the offering has a price range set","example":true},"symbol":{"type":"string","description":"Primary ticker symbol. Omitted when the issuer has no ticker yet.","example":"RDDT"},"name":{"type":"string","description":"Company name. Omitted when unresolved.","example":"Reddit, Inc."},"sharesOffered":{"type":"integer","description":"Number of shares offered by the company. Omitted when unreported.","example":22000000},"priceRangeLow":{"type":"number","description":"Low end of proposed price range (USD). Omitted when unpriced.","example":31},"priceRangeHigh":{"type":"number","description":"High end of proposed price range (USD). Omitted when unpriced.","example":34},"proposedMaxOffering":{"type":"number","description":"Proposed maximum aggregate offering price (USD). Omitted when unreported.","example":748000000}}}}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/filings":{"get":{"tags":["SEC Filings"],"summary":"Search filings","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns SEC filings for a company, optionally filtered by form type or 8-K event type.\nResults are paginated and restricted by your subscription tier's historical data limit.\n\n**8-K Event Filtering:** Use the `event` parameter to filter 8-K filings by event type (automatically implies `type=8-K`).\nEach 8-K filing includes both raw `items` (SEC item codes) and developer-friendly `events` (enum names).\n\n**Item Extraction:** The `items` array lists extracted section identifiers for all form types (10-K, 10-Q, 20-F, 8-K, S-1).\nUse `/api/filings/item` to retrieve the full content of any listed item.\n\nThe `documents` array contains slide/exhibit image filenames (JPG, PNG, GIF, PDF) extracted from the filing. To build a document URL, replace the filename at the end of the filing `url` with the document filename.\n\nExample: Filing URL `.../d230399d8k.htm` + document `g230399ex99_2p10g1.jpg` → `.../g230399ex99_2p10g1.jpg`\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol. Provide either `symbol` or `cik`.","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"type","required":false,"schema":{"type":"string","enum":["10-K","10-Q","20-F","8-K","DEF 14A","DEFA14A","13D","13G","3","4","5","13F-HR","NPORT-P","N-CEN","EFFECT","25-NSE","ARS"]},"description":"SEC form type to filter by. If omitted, all filing types are returned.\nIgnored when `event` is provided (event implies type=8-K).\n\n| Type | Description |\n|------|-------------|\n| `10-K` | Annual report |\n| `10-Q` | Quarterly report |\n| `20-F` | Annual report for foreign private issuers |\n| `8-K` | Current report (key events) |\n| `DEF 14A` | Proxy statement |\n| `DEFA14A` | Additional proxy solicitation materials |\n| `13D` | Beneficial ownership (>5%, active) |\n| `13G` | Beneficial ownership (>5%, passive) |\n| `3` | Insider initial ownership |\n| `4` | Insider ownership changes |\n| `5` | Insider annual summary |\n| `13F-HR` | Institutional holdings (quarterly) |\n| `NPORT-P` | Fund portfolio holdings (monthly) |\n| `N-CEN` | Fund annual census report |\n| `EFFECT` | SEC notice of registration effectiveness (the first `EFFECT` per company is its IPO date) |\n| `25-NSE` | Exchange-filed notification of removal from listing (authoritative delisting; the `signatureDate` is the official delisting date) |\n| `ARS` | Annual Report to Shareholders (glossy/narrative companion to the 10-K) |\n","example":"10-K"},{"in":"query","name":"event","required":false,"schema":{"type":"string","enum":["material_agreement","agreement_termination","bankruptcy","mine_safety","acquisition_disposition","earnings","debt_obligation","debt_acceleration","restructuring","impairment","delisting","unregistered_sale","rights_modification","auditor_change","restatement","control_change","officer_change","bylaws_amendment","trading_suspension","ethics_amendment","shell_status_change","shareholder_vote","shareholder_nomination","abs_material","servicer_change","credit_enhancement","distribution_failure","securities_act_update","reg_fd","other","financial_exhibits"]},"description":"Filter 8-K filings by event type. Automatically implies `type=8-K`.\n\n| Event | SEC Item | Description |\n|-------|----------|-------------|\n| `earnings` | 2.02 | Earnings results |\n| `officer_change` | 5.02 | Officer or director departure/appointment |\n| `material_agreement` | 1.01 | Entry into material definitive agreement |\n| `acquisition_disposition` | 2.01 | Acquisition or disposition of assets |\n| `control_change` | 5.01 | Change in control of registrant |\n| `restatement` | 4.02 | Financial restatement |\n| `bankruptcy` | 1.03 | Bankruptcy or receivership |\n| `restructuring` | 2.05 | Exit or disposal activities |\n| `reg_fd` | 7.01 | Regulation FD disclosure |\n| `other` | 8.01 | Other events |\n| `financial_exhibits` | 9.01 | Financial statements and exhibits |\n","example":"earnings"},{"in":"query","name":"page","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1},"description":"Page number (1-indexed)"},{"in":"query","name":"pageSize","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Number of filings per page"}],"responses":{"200":{"description":"Paginated list of SEC filings","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer","example":1},"pageSize":{"type":"integer","example":25},"totalPages":{"type":"integer","example":8},"totalResults":{"type":"integer","example":189},"data":{"type":"array","items":{"$ref":"#/components/schemas/FilingInfo"}}}}}}},"400":{"description":"Invalid parameters or company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/filings/search-by-accession-number":{"get":{"tags":["SEC Filings"],"summary":"Filing by accession number","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns a single SEC filing identified by its accession number.\nThe filing must be within your subscription tier's historical data limit.\n\nThe `documents` array contains slide/exhibit image filenames (JPG, PNG, GIF, PDF) extracted from the filing. To build a document URL, replace the filename at the end of the filing `url` with the document filename.\n","parameters":[{"in":"query","name":"accessionNumber","required":true,"schema":{"type":"string"},"description":"The SEC accession number (e.g. 0000320193-23-000106)","example":"0000320193-23-000106"}],"responses":{"200":{"description":"The SEC filing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilingInfo"}}}},"400":{"description":"Invalid parameters or filing not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan, or filing is outside your plan's data limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/filings/latest":{"get":{"tags":["SEC Filings"],"summary":"Latest filings","description":"![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns the most recent SEC filings across all companies, sorted by filing date descending.\nLimited to the last 30 days. Includes the company's ticker symbol and name.\n\nUse the `event` parameter to find specific 8-K events across the entire market — for example,\n`event=earnings` returns all recent earnings announcements, `event=officer_change` returns\nall recent executive departures/appointments.\n","parameters":[{"in":"query","name":"type","required":false,"schema":{"type":"string","enum":["10-K","10-Q","20-F","8-K","DEF 14A","DEFA14A","13D","13G","3","4","5","13F-HR","NPORT-P","N-CEN","EFFECT","25-NSE","ARS"]},"description":"SEC form type to filter by. Ignored when `event` is provided.","example":"8-K"},{"in":"query","name":"event","required":false,"schema":{"type":"string","enum":["material_agreement","agreement_termination","bankruptcy","mine_safety","acquisition_disposition","earnings","debt_obligation","debt_acceleration","restructuring","impairment","delisting","unregistered_sale","rights_modification","auditor_change","restatement","control_change","officer_change","bylaws_amendment","trading_suspension","ethics_amendment","shell_status_change","shareholder_vote","shareholder_nomination","abs_material","servicer_change","credit_enhancement","distribution_failure","securities_act_update","reg_fd","other","financial_exhibits"]},"description":"Filter 8-K filings by event type. Automatically implies `type=8-K`.","example":"earnings"},{"in":"query","name":"page","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":1},"description":"Page number (1-indexed)"},{"in":"query","name":"pageSize","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Number of filings per page"}],"responses":{"200":{"description":"Paginated list of recent SEC filings with company info","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer","example":1},"pageSize":{"type":"integer","example":25},"totalPages":{"type":"integer","example":12},"totalResults":{"type":"integer","example":284},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/FilingInfo"},{"type":"object","properties":{"symbol":{"type":"string","description":"Primary ticker symbol. Omitted for filers without a resolved ticker (private issuers, funds).","example":"AAPL"},"companyName":{"type":"string","description":"Company name. Omitted when unresolved.","example":"Apple Inc."}}}]}}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/filings/stats":{"get":{"tags":["SEC Filings"],"summary":"Filing statistics","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns aggregate filing activity statistics for a company, including total counts by form type,\namendment rate, and XBRL coverage. Useful for understanding a company's SEC filing history\nand compliance patterns.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol. Provide either `symbol` or `cik`.","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Filing statistics","content":{"application/json":{"schema":{"type":"object","properties":{"totalFilings":{"type":"integer","description":"Total number of SEC filings for this company","example":342},"byType":{"type":"object","description":"Breakdown by form type","additionalProperties":{"type":"object","properties":{"count":{"type":"integer","description":"Number of filings of this type","example":89},"latest":{"type":"string","nullable":true,"description":"Date of most recent filing of this type (YYYY-MM-DD)","example":"2024-12-15"}}},"example":{"10-K":{"count":12,"latest":"2024-11-01"},"8-K":{"count":89,"latest":"2024-12-15"},"10-Q":{"count":35,"latest":"2024-08-02"}}},"amendments":{"type":"object","properties":{"count":{"type":"integer","description":"Number of amended filings","example":8},"rate":{"type":"number","description":"Amendment rate (amendments / total filings)","example":0.023}}},"xbrlCoverage":{"type":"number","description":"Fraction of filings with XBRL data","example":0.87}}}}}},"400":{"description":"Invalid parameters or company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/filings/calendar":{"get":{"tags":["SEC Filings"],"summary":"Filing calendar","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nPredicts upcoming periodic filing dates (10-K, 10-Q, DEF 14A) based on historical patterns\nfrom the last 5 years. Returns expected dates with confidence levels and the historical\nfiling pattern (typical months, average days after period end).\n\n**Confidence levels:**\n- `high` — Filing dates have been very consistent (±7 days standard deviation)\n- `medium` — Some variation in filing dates (±14 days)\n- `low` — Significant variation in filing dates\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol. Provide either `symbol` or `cik`.","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Filing calendar with predictions","content":{"application/json":{"schema":{"type":"object","properties":{"nextExpected":{"type":"array","description":"Predicted next filing dates, sorted chronologically","items":{"type":"object","properties":{"type":{"type":"string","description":"Filing form type","example":"10-Q"},"expectedDate":{"type":"string","description":"Predicted filing date (YYYY-MM-DD)","example":"2025-05-02"},"confidence":{"type":"string","enum":["high","medium","low"],"description":"Confidence in the prediction based on historical consistency","example":"high"},"basedOn":{"type":"string","description":"Most recent filing date used as the baseline (YYYY-MM-DD)","example":"2025-01-31"}}}},"historicalPattern":{"type":"object","description":"Historical filing patterns by form type","additionalProperties":{"type":"object","properties":{"typicalMonths":{"type":"array","items":{"type":"integer"},"description":"Months (1-12) when filings of this type are typically submitted","example":[2,5,8]},"avgDaysAfterPeriodEnd":{"type":"integer","description":"Average number of days between period end and filing date","example":30}}},"example":{"10-K":{"typicalMonths":[11],"avgDaysAfterPeriodEnd":32},"10-Q":{"typicalMonths":[2,5,8],"avgDaysAfterPeriodEnd":30}}}}}}}},"400":{"description":"Invalid parameters or company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/filings/offering":{"get":{"tags":["SEC Filings"],"summary":"S-1 offering history","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns S-1/S-1A offering filings for a company, ordered by filing date ascending.\nTracks the evolution of IPO terms across amended registration statements.\n\nPreliminary filings may have null values for price and share fields.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol. Provide either `symbol` or `cik`.","example":"RDDT"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":1713445},{"in":"query","name":"page","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1},"description":"Page number (1-indexed)"},{"in":"query","name":"pageSize","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"description":"Number of offerings per page"}],"responses":{"200":{"description":"Paginated list of S-1 offering filings","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer","example":1},"pageSize":{"type":"integer","example":10},"totalPages":{"type":"integer","example":1},"totalResults":{"type":"integer","example":3},"data":{"type":"array","items":{"type":"object","description":"Fields that aren't reported on a given S-1 amendment are omitted rather than returned as null.","properties":{"filedDate":{"type":"string","description":"Filing date (YYYY-MM-DD)","example":"2024-02-22"},"accessionNumber":{"type":"string","description":"SEC accession number","example":"0001713445-24-000042"},"sharesOffered":{"type":"integer","description":"Number of shares offered by the company. Omitted when unreported.","example":22000000},"sharesOfferedSelling":{"type":"integer","description":"Number of shares offered by selling stockholders. Omitted when unreported.","example":8400000},"priceRangeLow":{"type":"number","description":"Low end of proposed price range (USD). Omitted when unpriced.","example":31},"priceRangeHigh":{"type":"number","description":"High end of proposed price range (USD). Omitted when unpriced.","example":34},"proposedMaxOffering":{"type":"number","description":"Proposed maximum aggregate offering price (USD). Omitted when unreported.","example":748000000},"overallotmentShares":{"type":"integer","description":"Number of additional shares the underwriters may purchase. Omitted when unreported.","example":3300000},"useOfProceeds":{"type":"string","description":"Summary of intended use of offering proceeds. Omitted when unreported.","example":"General corporate purposes and working capital"}}}}}}}}},"400":{"description":"Invalid parameters or company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/filings/timeline":{"get":{"tags":["SEC Filings"],"summary":"Filing timeline","description":"![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nCompressed research endpoint: returns the 10 most recent filings, predicted future filing dates with confidence levels, and the predicted next earnings call date in a single call. Replaces three separate API calls (filings search + filings calendar + earnings calendar).\n\nThe 10-Q / 10-K entry in `predicted.nextExpected` is anchored on the same earnings prediction returned via `nextEarningsDate`, so the filing date and earnings date are internally consistent (e.g. 10-Q is filed ~1 day after the earnings call). Other recurring filing types (DEF 14A, ARS, etc.) are projected from historical filing intervals.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","schema":{"type":"integer"},"description":"Company CIK number. Alternative to `symbol` - provide one or the other."}],"responses":{"200":{"description":"Combined filing timeline","content":{"application/json":{"schema":{"type":"object","required":["recent","predicted","nextEarningsDate"],"properties":{"recent":{"type":"array","description":"The 10 most recent filings for the symbol, newest first. Each entry follows the standard `FilingInfo` shape — fields that don't apply to the form type (e.g. `periodEndDate` on Form 4, `items` on a 10-K) are omitted rather than null.","items":{"$ref":"#/components/schemas/FilingInfo"}},"predicted":{"type":"object","required":["nextExpected","historicalPattern"],"description":"Predicted future filings derived from historical cadence, plus the underlying cadence pattern itself for transparency.","properties":{"nextExpected":{"type":"array","description":"One entry per recurring filing type expected next. Sorted by `expectedDate` ascending. Includes 10-Q, 10-K, and any other periodic forms with at least 2 historical filings.","items":{"type":"object","required":["type","expectedDate","confidence","basedOn"],"properties":{"type":{"type":"string","description":"SEC form type","example":"10-Q"},"expectedDate":{"type":"string","format":"date","description":"Predicted filing date (YYYY-MM-DD), snapped to a weekday.","example":"2026-05-01"},"confidence":{"type":"string","enum":["high","medium","low"],"description":"Reliability of the prediction.\n* `high` — earnings-grounded (10-Q/10-K) or stdDev of historical intervals ≤ 7 days\n* `medium` — stdDev ≤ 14 days\n* `low` — stdDev > 14 days\n","example":"high"},"basedOn":{"type":"string","description":"Source of the prediction. For 10-Q / 10-K this is the literal string `earnings prediction (YYYY-MM-DD)` referencing the earnings call this filing is grounded on. For other types it is the most recent prior filing date (YYYY-MM-DD) used as the cadence anchor.\n","example":"earnings prediction (2026-04-30)"}}}},"historicalPattern":{"type":"object","description":"Per-form-type cadence summary. Keyed by SEC form type. Useful for understanding why the prediction was made and how stable the company's filing schedule is.","additionalProperties":{"type":"object","required":["typicalMonths","avgDaysAfterPeriodEnd"],"properties":{"typicalMonths":{"type":"array","description":"Months of the year (1-12) in which the company has historically filed this form type.","items":{"type":"integer","minimum":1,"maximum":12},"example":[1,2,4,5,7,8]},"avgDaysAfterPeriodEnd":{"type":"integer","description":"Average lag in days between the filing's reporting `period_end_date` and its `date_filed`. Can be negative for forms whose `period_end_date` is in the future relative to the filing date (e.g. proxy statements scheduled for an upcoming annual meeting).","example":34}}}}}},"nextEarningsDate":{"type":"string","format":"date","nullable":true,"description":"Predicted next earnings call date (YYYY-MM-DD), or `null` when no prior earnings 8-K exists. Same value as `/api/earnings/calendar` returns. The 10-Q / 10-K entry in `predicted.nextExpected` is grounded on this date, typically ±1 day for 10-Q and ±6-8 days for 10-K.","example":"2026-04-30"}}},"example":{"recent":[{"type":"144","accessionNumber":"0001969223-26-000420","url":"https://www.sec.gov/Archives/edgar/data/320193/0001969223-26-000420.txt","dateFiled":"2026-04-02","xbrl":true,"amendment":false},{"type":"144","accessionNumber":"0001959173-26-002757","url":"https://www.sec.gov/Archives/edgar/data/320193/0001959173-26-002757.txt","dateFiled":"2026-04-02","xbrl":true,"amendment":false},{"type":"13G","accessionNumber":"0000102909-26-000630","url":"https://www.sec.gov/Archives/edgar/data/320193/000010290926000630/primary_doc.xml","dateFiled":"2026-03-26","xbrl":true,"amendment":true,"periodEndDate":"2026-03-28"},{"type":"4","accessionNumber":"0001780525-26-000005","url":"https://www.sec.gov/Archives/edgar/data/320193/000178052526000005/wk-form4_1773786674.xml","dateFiled":"2026-03-17","xbrl":true,"amendment":false,"periodEndDate":"2026-03-18"},{"type":"3","accessionNumber":"0001780525-26-000003","url":"https://www.sec.gov/Archives/edgar/data/320193/000178052526000003/wk-form3_1772839848.xml","dateFiled":"2026-03-06","xbrl":true,"amendment":false,"periodEndDate":"2026-03-07"},{"type":"4","accessionNumber":"0001059235-26-000004","url":"https://www.sec.gov/Archives/edgar/data/320193/000105923526000004/xslF345X05/wk-form4_1772148856.xml","dateFiled":"2026-02-26","xbrl":false,"amendment":false,"periodEndDate":"2026-02-24"},{"type":"4","accessionNumber":"0001179864-26-000004","url":"https://www.sec.gov/Archives/edgar/data/320193/000117986426000004/xslF345X05/wk-form4_1772148791.xml","dateFiled":"2026-02-26","xbrl":false,"amendment":false,"periodEndDate":"2026-02-24"},{"type":"4","accessionNumber":"0001214128-26-000004","url":"https://www.sec.gov/Archives/edgar/data/320193/000121412826000004/xslF345X05/wk-form4_1772148758.xml","dateFiled":"2026-02-26","xbrl":false,"amendment":false,"periodEndDate":"2026-02-24"},{"type":"4","accessionNumber":"0001051401-26-000004","url":"https://www.sec.gov/Archives/edgar/data/320193/000105140126000004/xslF345X05/wk-form4_1772148721.xml","dateFiled":"2026-02-26","xbrl":false,"amendment":false,"periodEndDate":"2026-02-24"},{"type":"4","accessionNumber":"0001453149-26-000005","url":"https://www.sec.gov/Archives/edgar/data/320193/000145314926000005/xslF345X05/wk-form4_1772148681.xml","dateFiled":"2026-02-26","xbrl":false,"amendment":false,"periodEndDate":"2026-02-24"}],"predicted":{"nextExpected":[{"type":"10-Q","expectedDate":"2026-05-01","confidence":"high","basedOn":"earnings prediction (2026-04-30)"},{"type":"10-K","expectedDate":"2026-11-01","confidence":"high","basedOn":"2025-10-31"},{"type":"DEF 14A","expectedDate":"2027-01-09","confidence":"high","basedOn":"2026-01-08"}],"historicalPattern":{"10-K":{"typicalMonths":[10,11],"avgDaysAfterPeriodEnd":34},"10-Q":{"typicalMonths":[1,2,4,5,7,8],"avgDaysAfterPeriodEnd":34},"DEF 14A":{"typicalMonths":[1],"avgDaysAfterPeriodEnd":-51}}},"nextEarningsDate":"2026-04-30"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Professional plan required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/filings/item-list":{"get":{"tags":["SEC Filings"],"summary":"List extracted items for a filing","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\n> **Preview:** This endpoint is a preview of a planned feature for a future release. Item extraction is not yet enabled for the full filing universe — most filings will return an empty list until processing is complete.\n\nReturns the list of extracted items (sections) available for a given SEC filing.\nEach entry includes the item identifier, title, and content size — but not the actual content.\nUse `/api/filings/item` to retrieve the full content of a specific item.\n\n**Coverage note:** Item extraction is best-effort. SEC filings have no standardized HTML structure,\nso some items may be missing if the filing uses an unusual layout. Common items like Risk Factors (1A),\nMD&A (7), and Financial Statements (8) have the highest extraction success rate.\n8-K items are extracted from the filing body — not all 8-K filings contain structured item sections.\n","parameters":[{"name":"accessionNumber","in":"query","required":true,"schema":{"type":"string","minLength":10,"maxLength":25,"example":"0000320193-25-000079"},"description":"SEC accession number of the filing."}],"responses":{"200":{"description":"List of available items","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"item":{"type":"string","description":"Item identifier","example":"1A"},"title":{"type":"string","description":"Item title","example":"Risk Factors"},"charCount":{"type":"integer","description":"Content length in characters","example":84231}}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/filings/item":{"get":{"tags":["SEC Filings"],"summary":"Extract a single item from a filing","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\n> **Preview:** This endpoint is a preview of a planned feature for a future release. Item extraction is not yet enabled for the full filing universe — most filings will not have extracted items until processing is complete.\n\nReturns the full content of a single extracted item (section) from a SEC filing.\nContent is available as HTML (original formatting preserved) or plain text (tags stripped).\n\nUse `/api/filings/item-list` first to discover which items are available for a given filing.\n\n**Coverage note:** Item extraction is best-effort. SEC filings do not follow a standardized HTML structure —\nheadings, fonts, and layouts vary significantly across filers and filing agents. Our extractor uses\nfont-weight, font-size, and DOM structure heuristics to detect section boundaries. While extraction succeeds\nfor the vast majority of filings, some items may be missing or have imprecise boundaries in edge cases.\nIf an item is not listed by `/api/filings/item-list`, it was not detected in the filing.\n","parameters":[{"name":"accessionNumber","in":"query","required":true,"schema":{"type":"string","minLength":10,"maxLength":25,"example":"0000320193-25-000079"},"description":"SEC accession number of the filing."},{"name":"item","in":"query","required":true,"schema":{"type":"string","example":"1A"},"description":"Item identifier. The available items depend on the filing's form type.\n\n### 10-K Annual Report Items\n\n| Item | Title |\n|------|-------|\n| `1` | Business |\n| `1A` | Risk Factors |\n| `1B` | Unresolved Staff Comments |\n| `1C` | Cybersecurity |\n| `2` | Properties |\n| `3` | Legal Proceedings |\n| `4` | Mine Safety Disclosures |\n| `5` | Market for Common Equity |\n| `7` | Management's Discussion and Analysis |\n| `7A` | Quantitative and Qualitative Disclosures About Market Risk |\n| `8` | Financial Statements |\n| `9` | Changes in and Disagreements with Accountants |\n| `9A` | Controls and Procedures |\n| `9B` | Other Information |\n| `9C` | Disclosure Regarding Foreign Jurisdictions |\n| `10` | Directors, Executive Officers and Corporate Governance |\n| `11` | Executive Compensation |\n| `12` | Security Ownership |\n| `13` | Certain Relationships and Related Transactions |\n| `14` | Principal Accountant Fees |\n| `15` | Exhibits and Financial Statement Schedules |\n| `16` | Form 10-K Summary |\n\n### 10-Q Quarterly Report Items\n\n| Item | Title |\n|------|-------|\n| `1` | Financial Statements (Part I) / Legal Proceedings (Part II) |\n| `1A` | Risk Factors |\n| `2` | Management's Discussion and Analysis (Part I) / Unregistered Sales (Part II) |\n| `3` | Market Risk Disclosures (Part I) / Defaults Upon Senior Securities (Part II) |\n| `4` | Controls and Procedures (Part I) / Mine Safety (Part II) |\n| `5` | Other Information |\n| `6` | Exhibits |\n\n### 8-K Current Report Items\n\n| Item | Title |\n|------|-------|\n| `1.01` | Entry into a Material Definitive Agreement |\n| `1.02` | Termination of a Material Definitive Agreement |\n| `1.03` | Bankruptcy or Receivership |\n| `1.04` | Mine Safety |\n| `1.05` | Material Cybersecurity Incidents |\n| `2.01` | Completion of Acquisition or Disposition of Assets |\n| `2.02` | Results of Operations and Financial Condition |\n| `2.03` | Creation of a Direct Financial Obligation |\n| `2.04` | Triggering Events That Accelerate a Direct Financial Obligation |\n| `2.05` | Costs Associated with Exit or Disposal Activities |\n| `2.06` | Material Impairments |\n| `3.01` | Notice of Delisting or Failure to Satisfy Listing Standards |\n| `3.02` | Unregistered Sales of Equity Securities |\n| `3.03` | Material Modification to Rights of Security Holders |\n| `4.01` | Changes in Registrant's Certifying Accountant |\n| `4.02` | Non-Reliance on Previously Issued Financial Statements |\n| `5.01` | Changes in Control of Registrant |\n| `5.02` | Departure of Directors or Certain Officers |\n| `5.03` | Amendments to Articles of Incorporation or Bylaws |\n| `5.04` | Temporary Suspension of Trading Under Employee Benefit Plans |\n| `5.05` | Amendment to Code of Ethics |\n| `5.06` | Change in Shell Company Status |\n| `5.07` | Submission of Matters to a Vote of Security Holders |\n| `5.08` | Shareholder Nominations |\n| `6.01` | ABS Informational and Computational Material |\n| `6.02` | Change of Servicer or Trustee |\n| `6.03` | Change in Credit Enhancement |\n| `6.04` | Failure to Make a Required Distribution |\n| `6.05` | Securities Act Updating Disclosure |\n| `7.01` | Regulation FD Disclosure |\n| `8.01` | Other Events |\n| `9.01` | Financial Statements and Exhibits |\n\n### S-1 Registration Statement Items\n\n| Item | Title |\n|------|-------|\n| `risk-factors` | Risk Factors |\n| `business` | Business |\n| `mda` | Management's Discussion and Analysis |\n"},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["html","text"],"default":"html","example":"html"},"description":"Response content format.\n- `html` — Original HTML with formatting, tables, and structure preserved.\n- `text` — Plain text with HTML tags stripped. Tables are converted to tab-separated values.\n"}],"responses":{"200":{"description":"Extracted item content","content":{"application/json":{"schema":{"type":"object","properties":{"accessionNumber":{"type":"string","description":"SEC accession number","example":"0000320193-25-000079"},"cik":{"type":"string","description":"Company CIK (zero-padded)","example":"0000320193"},"form":{"type":"string","description":"Filing form type","example":"10-K"},"filedAt":{"type":"string","description":"Date the filing was submitted","example":"2025-11-01"},"item":{"type":"string","description":"Item identifier","example":"1A"},"title":{"type":"string","description":"Item title","example":"Risk Factors"},"content":{"type":"string","description":"Full item content (HTML or plain text depending on `type` parameter)","example":"<div>The following discussion of risk factors contains..."},"charCount":{"type":"integer","description":"Content length in characters","example":84231},"contentType":{"type":"string","enum":["html","text"],"description":"Format of the content field","example":"html"}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/financials/as-reported":{"get":{"tags":["Financials"],"summary":"As-reported financials","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns raw XBRL financial facts exactly as filed with the SEC, without any normalization or mapping. Includes both standard US-GAAP taxonomy facts and company-specific custom extension facts. Useful for accessing the full set of reported line items.\n","parameters":[{"in":"query","name":"symbol","description":"Stock ticker symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"period","description":"The period to query data for (annual or quarter).","required":false,"schema":{"type":"string","enum":["annual","quarter"],"default":"annual"}},{"in":"query","name":"limit","description":"Maximum number of periods to return (may be clamped by subscription tier).","required":false,"schema":{"type":"integer","default":4,"minimum":1,"maximum":80}}],"responses":{"200":{"description":"Raw financial data as originally reported in SEC filings","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string","description":"The fiscal period end date","example":"2023-09-30"},"fiscalYear":{"type":"integer","description":"The company's fiscal year (handles non-December year-ends — AAPL FY ends Sep, COST FY ends Aug).","example":2025},"fiscalPeriod":{"type":"string","enum":["FY","Q1","Q2","Q3","Q4","TTM"],"description":"The fiscal period type. `FY` for annual, `Q1`-`Q4` for quarterly, `TTM` for trailing-twelve-months.","example":"FY"},"facts":{"type":"object","description":"Flat key-value pairs of financial metrics. Keys are namespace-prefixed XBRL concept names (e.g. `us-gaap:NetIncomeLoss`, `aapl:MachineryEquipmentAndInternalUseSoftwareNet`). Includes both standard US-GAAP and company-specific custom extensions.","additionalProperties":{"type":"number"},"example":{"us-gaap:NetIncomeLoss":112010000000,"us-gaap:EarningsPerShareDiluted":7.46,"us-gaap:GeneralAndAdministrativeExpense":8077000000}},"sources":{"$ref":"#/components/schemas/FactSources"}}}}}}},"400":{"description":"Invalid parameters or symbol not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/financials/income-statement":{"get":{"tags":["Financials"],"summary":"Income statement","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns normalized income statement data — revenue, cost of revenue, operating expenses, EBITDA, net income, EPS, and more. Facts are mapped from raw XBRL to a curated set of standardized line items.\n\nUse `period=ttm` to get trailing twelve months data, computed by summing the last 4 reported quarters.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"period","required":false,"schema":{"type":"string","enum":["annual","quarter","ttm"],"default":"annual"},"description":"The reporting period: `annual`, `quarter`, or `ttm` (trailing twelve months). TTM sums the last 4 quarters for flow items and uses the latest quarter for point-in-time items."},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":80,"default":4},"description":"Maximum number of periods to return (may be clamped by subscription tier). Ignored when `period=ttm`."}],"responses":{"200":{"description":"Income statement data organized by period","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string","description":"The fiscal period end date","example":"2023-09-30"},"fiscalYear":{"type":"integer","description":"The company's fiscal year (handles non-December year-ends — AAPL FY ends Sep, COST FY ends Aug).","example":2025},"fiscalPeriod":{"type":"string","enum":["FY","Q1","Q2","Q3","Q4","TTM"],"description":"The fiscal period type. `FY` for annual, `Q1`-`Q4` for quarterly, `TTM` for trailing-twelve-months.","example":"FY"},"facts":{"type":"object","description":"Normalized income statement line items, keyed by curated fact name with numeric values.","properties":{"revenue":{"type":"number","description":"Total Revenue — Total income generated from sales of goods or services before any expenses are deducted."},"costOfRevenue":{"type":"number","description":"Cost of Revenue — Direct costs attributable to producing goods or services sold, including materials and direct labor."},"grossProfit":{"type":"number","description":"Gross Profit — Revenue minus cost of revenue, showing profitability before operating expenses."},"researchAndDevelopment":{"type":"number","description":"Research & Development — Spending on activities to develop new products, services, or processes."},"generalAndAdministrativeExpenses":{"type":"number","description":"General & Administrative — Overhead costs for running the business, such as rent, salaries, and office expenses."},"sellingAndMarketingExpenses":{"type":"number","description":"Selling & Marketing — Costs related to advertising, promotions, and sales activities."},"sellingGeneralAndAdministrativeExpenses":{"type":"number","description":"SG&A — Combined selling, general, and administrative expenses."},"otherExpenses":{"type":"number","description":"Other Expenses — Non-core income or expenses not classified elsewhere in operations."},"restructuringCharges":{"type":"number","description":"Restructuring Charges — Costs from restructuring activities — severance, facility exits, contract terminations. Sourced from `us-gaap:RestructuringCharges` when reported; falls back to the broader `us-gaap:RestructuringSettlementAndImpairmentProvisions` (which also includes related asset impairments and settlement provisions) for filers that only tag the aggregate. Often called out by management as non-recurring; useful for deriving adjusted operating margin."},"operatingExpenses":{"type":"number","description":"Operating Expenses — Total costs incurred through normal business operations, excluding cost of revenue."},"costAndExpenses":{"type":"number","description":"Cost & Expenses — Total of all costs and expenses, including cost of revenue and operating expenses."},"interestIncome":{"type":"number","description":"Interest Income — Income earned from interest-bearing assets like deposits or bonds."},"interestExpense":{"type":"number","description":"Interest Expense — Cost of borrowing money, including interest on debt and credit facilities. **IFRS note**: under IFRS, `FinanceCosts` may include lease-liability interest by default; US-GAAP filers typically separate lease interest into other line items."},"interestIncomeNet":{"type":"number","description":"Net Interest Income (Expense) — Interest income minus interest expense. Key profitability metric for banks."},"depreciationAndAmortization":{"type":"number","description":"Depreciation & Amortization — Non-cash charges for the gradual write-down of tangible and intangible assets."},"depreciation":{"type":"number","description":"Depreciation — Non-cash expense reflecting the wear and aging of physical assets like equipment and buildings."},"amortization":{"type":"number","description":"Amortization — Non-cash expense for the systematic write-off of intangible assets like patents and software."},"operatingIncome":{"type":"number","description":"Operating Income — Profit from core business operations after subtracting operating expenses from gross profit."},"nonOperatingIncome":{"type":"number","description":"Non-Operating Income — Income from activities outside core operations, such as investment gains or asset sales."},"incomeBeforeTax":{"type":"number","description":"Income Before Tax — Total earnings before income tax is deducted. Also known as pre-tax income."},"incomeTaxExpense":{"type":"number","description":"Income Tax Expense — Total income taxes owed for the period, including current and deferred taxes."},"netIncome":{"type":"number","description":"Net Income — Total profit after all expenses, taxes, and costs are subtracted from revenue."},"netIncomeCommonStockholders":{"type":"number","description":"Net Income to Common — Profit available to common shareholders after preferred dividends."},"netIncomeCommonStockholdersDiluted":{"type":"number","description":"Net Income to Common (Diluted) — Profit available to common shareholders, adjusted for all dilutive securities."},"weightedAverageSharesOutstanding":{"type":"number","description":"Shares Outstanding — Average number of basic shares outstanding during the period."},"weightedAverageSharesOutstandingDiluted":{"type":"number","description":"Shares Outstanding (Diluted) — Average shares outstanding including dilutive effects of options, warrants, and convertibles."},"eps":{"type":"number","description":"EPS — Net income divided by weighted average basic shares outstanding."},"epsDiluted":{"type":"number","description":"EPS (Diluted) — Net income divided by weighted average diluted shares outstanding."},"ebit":{"type":"number","description":"EBIT — Earnings before interest and taxes. Measures operating profitability regardless of capital structure."},"ebitda":{"type":"number","description":"EBITDA — Earnings before interest, taxes, depreciation, and amortization. Proxy for operating cash generation."},"premiumsEarned":{"type":"number","description":"Premiums Earned — Insurance premium revenue recognized during the period."},"premiumsWritten":{"type":"number","description":"Premiums Written — Total insurance premiums from policies written during the period, whether or not yet earned."},"policyholderBenefitsAndClaims":{"type":"number","description":"Policyholder Benefits & Claims — Payments and reserves for insurance claims and policyholder benefits."},"policyAcquisitionCosts":{"type":"number","description":"Policy Acquisition Costs — Costs to acquire new insurance policies, such as commissions and underwriting expenses."},"underwritingIncome":{"type":"number","description":"Underwriting Income (Loss) — Profit from insurance operations: premiums earned minus claims and acquisition costs."},"netInvestmentIncome":{"type":"number","description":"Net Investment Income — Income from the insurance company's investment portfolio."},"noninterestIncome":{"type":"number","description":"Non-Interest Income — Bank revenue from sources other than interest, such as fees, trading, and service charges."},"noninterestExpense":{"type":"number","description":"Non-Interest Expense — Bank operating costs excluding interest expense, such as salaries, occupancy, and technology."},"provisionForCreditLosses":{"type":"number","description":"Provision for Credit Losses — Amount set aside to cover estimated losses on loans and other credit exposures."}}},"sources":{"$ref":"#/components/schemas/FactSources"},"derived":{"$ref":"#/components/schemas/DerivedFacts"},"dateFiled":{"type":"string","format":"date","description":"SEC filing acceptance date for the **original** 10-K (annual / Q4 quarterly entries) or 10-Q (Q1-Q3 quarterly entries) covering this period. Format: YYYY-MM-DD. Use this to gate point-in-time data access and avoid lookahead bias when joining with historical price data — backtesters should only treat the period's facts as \"knowable\" on or after this date. Amendments (10-K/A, 10-Q/A) are explicitly **not** used here; this field always reflects the original disclosure date. Not present when `period=ttm` — TTM is synthesized from 4 quarters and has no single filing date.\n","example":"2024-11-01"}}}},"example":[{"period":"2025-12-31","fiscalYear":2025,"fiscalPeriod":"FY","dateFiled":"2026-02-15","facts":{"revenue":100000000000,"costOfRevenue":50000000000,"grossProfit":50000000000,"researchAndDevelopment":8000000000,"generalAndAdministrativeExpenses":4000000000,"sellingAndMarketingExpenses":6000000000,"sellingGeneralAndAdministrativeExpenses":10000000000,"otherExpenses":500000000,"restructuringCharges":1000000000,"operatingExpenses":18500000000,"costAndExpenses":68500000000,"interestIncome":800000000,"interestExpense":300000000,"interestIncomeNet":500000000,"depreciationAndAmortization":4000000000,"depreciation":3000000000,"amortization":1000000000,"operatingIncome":31500000000,"nonOperatingIncome":500000000,"incomeBeforeTax":32000000000,"incomeTaxExpense":6400000000,"netIncome":25600000000,"netIncomeCommonStockholders":25600000000,"netIncomeCommonStockholdersDiluted":25600000000,"weightedAverageSharesOutstanding":4000000000,"weightedAverageSharesOutstandingDiluted":4050000000,"eps":6.4,"epsDiluted":6.32,"ebit":31500000000,"ebitda":35500000000,"premiumsEarned":100000000000,"premiumsWritten":100000000000,"policyholderBenefitsAndClaims":30000000000,"policyAcquisitionCosts":5000000000,"underwritingIncome":31500000000,"netInvestmentIncome":2000000000,"noninterestIncome":5000000000,"noninterestExpense":8000000000,"provisionForCreditLosses":1500000000},"sources":{"0001234567-26-000001":{"type":"10-K","dateFiled":"2026-02-15","amendment":false,"facts":{"revenue":{},"costOfRevenue":{},"researchAndDevelopment":{},"generalAndAdministrativeExpenses":{},"sellingAndMarketingExpenses":{},"otherExpenses":{},"restructuringCharges":{},"costAndExpenses":{},"interestExpense":{},"operatingIncome":{},"nonOperatingIncome":{},"incomeBeforeTax":{},"incomeTaxExpense":{},"netIncome":{},"netIncomeCommonStockholders":{},"netIncomeCommonStockholdersDiluted":{},"weightedAverageSharesOutstanding":{},"weightedAverageSharesOutstandingDiluted":{},"eps":{},"epsDiluted":{},"premiumsEarned":{},"premiumsWritten":{},"policyholderBenefitsAndClaims":{},"policyAcquisitionCosts":{},"underwritingIncome":{},"netInvestmentIncome":{},"noninterestIncome":{},"noninterestExpense":{},"provisionForCreditLosses":{}}},"0001234567-26-000042":{"type":"10-K","dateFiled":"2026-05-30","amendment":true,"facts":{"revenue":{"before":98000000000}}}},"derived":["grossProfit","sellingGeneralAndAdministrativeExpenses","operatingExpenses","depreciationAndAmortization","amortization","depreciation","interestIncomeNet","ebit","ebitda","interestIncome"]}]}}},"400":{"description":"Invalid parameters or symbol not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/financials/balance-sheet":{"get":{"tags":["Financials"],"summary":"Balance sheet","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns normalized balance sheet data — total assets, current assets, total liabilities, stockholders' equity, cash, debt, and more. Facts are mapped from raw XBRL to a curated set of standardized line items.\n\nUse `period=ttm` to get the latest quarterly balance sheet snapshot.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"period","required":false,"schema":{"type":"string","enum":["annual","quarter","ttm"],"default":"annual"},"description":"The reporting period: `annual`, `quarter`, or `ttm`. For the balance sheet, TTM returns the most recent quarter's point-in-time values."},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":80,"default":4},"description":"Maximum number of periods to return (may be clamped by subscription tier). Ignored when `period=ttm`."}],"responses":{"200":{"description":"Balance sheet data organized by period","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string","description":"The fiscal period end date","example":"2023-09-30"},"fiscalYear":{"type":"integer","description":"The company's fiscal year (handles non-December year-ends — AAPL FY ends Sep, COST FY ends Aug).","example":2025},"fiscalPeriod":{"type":"string","enum":["FY","Q1","Q2","Q3","Q4","TTM"],"description":"The fiscal period type. `FY` for annual, `Q1`-`Q4` for quarterly, `TTM` for trailing-twelve-months.","example":"FY"},"facts":{"type":"object","description":"Normalized balance sheet line items, keyed by curated fact name with numeric values.","properties":{"assets":{"type":"number","description":"Total Assets — Total Assets — everything the company owns that has economic value. Equals the sum of current assets and non-current assets."},"currentAssets":{"type":"number","description":"Current Assets — Assets expected to be converted to cash or used within one year."},"cash":{"type":"number","description":"Cash and Cash Equivalents — Cash on hand and short-term, highly liquid investments."},"netReceivables":{"type":"number","description":"Net Receivables — Amounts owed by customers minus allowances for uncollectible accounts."},"accountsReceivable":{"type":"number","description":"Accounts Receivable — Money owed by customers for goods or services delivered on credit."},"inventory":{"type":"number","description":"Inventory — Goods available for sale or raw materials used in production."},"finishedGoods":{"type":"number","description":"Finished Goods Inventory — Completed products ready for sale within total inventory."},"otherCurrentAssets":{"type":"number","description":"Other Current Assets — Short-term assets not classified elsewhere, such as prepaid expenses."},"accumulatedDepreciation":{"type":"number","description":"Accumulated Depreciation — Total depreciation charged against assets since acquisition. Reduces gross asset value."},"goodwill":{"type":"number","description":"Goodwill — Premium paid above fair value in acquisitions, representing intangible value like brand and customer relationships."},"otherIntangibleAssets":{"type":"number","description":"Other Intangible Assets — Non-physical assets such as patents, trademarks, and customer lists."},"otherNonCurrentAssets":{"type":"number","description":"Other Non-Current Assets — Long-term assets not classified elsewhere."},"nonCurrentAssets":{"type":"number","description":"Non-Current Assets — Assets not expected to be converted to cash within one year. Equals total assets minus current assets. Most filers don't tag this directly (the classified-BS identity makes it redundant); when not filed, derived as `assets - currentAssets`."},"liabilities":{"type":"number","description":"Total Liabilities — Everything the company owes to outside parties."},"currentLiabilities":{"type":"number","description":"Current Liabilities — Obligations due within one year."},"accountsPayable":{"type":"number","description":"Accounts Payable — Amounts owed to suppliers for goods or services received on credit."},"taxesPayable":{"type":"number","description":"Taxes Payable, Current — Income and other taxes currently due to government authorities."},"totalPayable":{"type":"number","description":"Total Payable — Combined accounts payable and other payable amounts."},"otherCurrentAccruedLiabilities":{"type":"number","description":"Other Current Accrued Liabilities — Short-term obligations recognized but not yet paid, such as wages or utilities."},"currentCapitalLeaseObligations":{"type":"number","description":"Current Capital Lease Obligations — Lease payments due within one year."},"currentDeferredLiabilities":{"type":"number","description":"Current Deferred Liabilities — Revenue received but not yet earned, or other deferred obligations due within a year."},"otherCurrentLiabilities":{"type":"number","description":"Other Current Liabilities or Licensed Asset Obligations — Short-term obligations not classified elsewhere."},"totalNonCurrentLiabilities":{"type":"number","description":"Total Non-Current Liabilities — Obligations due beyond one year."},"longTermDebt":{"type":"number","description":"Long-term Debt — Borrowings and financial obligations due beyond one year. Excludes the current portion (see `longTermDebtCurrent`)."},"longTermCapitalLeaseObligations":{"type":"number","description":"Long-term Capital Lease Obligations — Lease payment obligations extending beyond one year."},"otherNonCurrentLiabilities":{"type":"number","description":"Other Non-Current Liabilities — Long-term obligations not classified elsewhere."},"stockholdersEquity":{"type":"number","description":"Total Stockholders Equity — Net assets belonging to shareholders: total assets minus total liabilities."},"commonStock":{"type":"number","description":"Common Stock — Par or stated value of common shares issued."},"preferredStock":{"type":"number","description":"Preferred Stock — Value of preferred shares issued, which have priority over common stock for dividends."},"retainedEarnings":{"type":"number","description":"Retained Earnings — Cumulative net income kept in the business rather than paid out as dividends."},"otherEquityAdjustments":{"type":"number","description":"Other Equity Adjustments — Accumulated other comprehensive income and other equity adjustments."},"additionalPaidInCapital":{"type":"number","description":"Additional Paid-in Capital — Amount shareholders paid above par value for shares issued."},"capitalLeaseObligations":{"type":"number","description":"Capital Lease Obligations — Total remaining lease payments recognized as debt."},"workingCapital":{"type":"number","description":"Working Capital — Current assets minus current liabilities. Measures short-term liquidity."},"totalDebt":{"type":"number","description":"Total Debt — Sum of all short-term and long-term borrowings."},"sharesIssued":{"type":"number","description":"Shares Issued — Total number of shares the company has ever issued."},"storeCount":{"type":"number","description":"Number of Stores — Total number of retail store locations operated by the company."},"sharesOutstanding":{"type":"number","description":"Shares Outstanding — Total shares currently held by all shareholders."},"treasuryShares":{"type":"number","description":"Treasury Shares — Shares repurchased by the company and held in its treasury."},"currentSharesOutstanding":{"type":"number","description":"Current Shares Outstanding — Shares outstanding as reported on the cover page of the 10-K/10-Q. Typically dated 2-3 weeks after the period end, so this is more recent than the balance-sheet snapshot in `sharesOutstanding`."},"preferredSharesOutstanding":{"type":"number","description":"Preferred Shares Outstanding — Total preferred shares currently issued and outstanding."},"publicFloat":{"type":"number","description":"Public Float — Aggregate market value of voting and non-voting common equity held by non-affiliates, reported annually on the 10-K cover page (as of the last business day of the most recent second fiscal quarter). Null on quarterly periods."},"policyReserves":{"type":"number","description":"Policy Liabilities and Reserves — Reserves held to pay future insurance policy claims and benefits."},"deferredAcquisitionCosts":{"type":"number","description":"Deferred Policy Acquisition Costs — Policy acquisition costs deferred and recognized over the life of insurance policies."},"propertyPlantAndEquipmentGross":{"type":"number","description":"Property, Plant and Equipment, Gross — Total cost of physical assets before deducting accumulated depreciation."},"propertyPlantAndEquipmentNet":{"type":"number","description":"Property, Plant and Equipment, Net — Physical assets like land, buildings, and equipment, minus accumulated depreciation."},"constructionInProgress":{"type":"number","description":"Construction in Progress — Costs accumulated for construction projects not yet completed."},"costsInExcessOfBillings":{"type":"number","description":"Costs in Excess of Billings (Contract Asset) — Contract revenue earned but not yet billed to the customer."},"billingsInExcessOfCosts":{"type":"number","description":"Billings in Excess of Costs (Contract Liability) — Customer billings that exceed work performed to date. A contract liability."},"contractReceivableRetainage":{"type":"number","description":"Contract Receivable Retainage — Amounts withheld by customers from progress billings until contract completion."},"debtCurrent":{"type":"number","description":"Current Debt (Short-Term Borrowings) — Total current debt. Equal to longTermDebtCurrent for companies without separate short-term borrowings (commercial paper, revolver draws, etc.); otherwise the broader umbrella that includes them."},"longTermDebtCurrent":{"type":"number","description":"Current Maturities of Long-Term Debt — Portion of long-term debt due within one year."},"deposits":{"type":"number","description":"Deposits — Customer deposits held by the bank. A primary source of bank funding."},"loans":{"type":"number","description":"Loans and Leases Receivable — Total loans and leases issued to borrowers, net of unearned income."},"allowanceForDoubtfulAccounts":{"type":"number","description":"Allowance for Doubtful Accounts Receivable — Reserve for receivables estimated to be uncollectible."},"allowanceForCreditLossesLoans":{"type":"number","description":"Allowance for Credit Losses on Loans — Reserve for estimated losses on the bank's loan portfolio."},"assetRetirementObligation":{"type":"number","description":"Asset Retirement Obligation (Total) — Estimated cost to dismantle and restore a site when a long-lived asset is retired."},"assetRetirementObligationCurrent":{"type":"number","description":"Asset Retirement Obligation, Current — Portion of asset retirement obligation due within one year."},"assetRetirementObligationNoncurrent":{"type":"number","description":"Asset Retirement Obligation, Non-Current — Long-term portion of asset retirement obligation."},"warrantyLiability":{"type":"number","description":"Warranty Liability — Estimated costs to fulfill product warranty obligations."},"contractLiabilityNoncurrent":{"type":"number","description":"Non-Current Contract Liability / Deferred Revenue — Revenue collected but not yet recognized, with performance obligations beyond one year."},"remainingPerformanceObligations":{"type":"number","description":"Remaining Performance Obligations — Total contracted revenue not yet recognized, representing the backlog of future revenue."},"investments":{"type":"number","description":"Investments — Securities and other financial assets held for investment purposes."},"shortTermInvestments":{"type":"number","description":"Short-Term Investments — Marketable securities and short-term investments expected to be converted to cash within one year. Included in current assets. Used in net-debt calculations alongside cash."},"longTermInvestments":{"type":"number","description":"Long-Term Investments — Marketable securities and other investments expected to be held for more than one year. Distinct from `shortTermInvestments` (current) and from `investments` (which is the broader portfolio for banks and insurers)."},"lettersOfCreditOutstanding":{"type":"number","description":"Letters of Credit Outstanding — Contingent obligations where the bank guarantees payment on behalf of a customer."}}},"sources":{"$ref":"#/components/schemas/FactSources"},"derived":{"$ref":"#/components/schemas/DerivedFacts"},"dateFiled":{"type":"string","format":"date","description":"SEC filing acceptance date for the **original** 10-K (annual / Q4 quarterly entries) or 10-Q (Q1-Q3 quarterly entries) covering this period. Format: YYYY-MM-DD. Use this to gate point-in-time data access and avoid lookahead bias when joining with historical price data — backtesters should only treat the period's facts as \"knowable\" on or after this date. Amendments (10-K/A, 10-Q/A) are explicitly **not** used here; this field always reflects the original disclosure date. Not present when `period=ttm` — TTM is synthesized from 4 quarters and has no single filing date.\n","example":"2024-11-01"}}}},"example":[{"period":"2025-12-31","fiscalYear":2025,"fiscalPeriod":"FY","dateFiled":"2026-02-15","facts":{"assets":200000000000,"currentAssets":80000000000,"cash":25000000000,"netReceivables":12000000000,"accountsReceivable":12000000000,"inventory":8000000000,"finishedGoods":5000000000,"otherCurrentAssets":20000000000,"accumulatedDepreciation":30000000000,"goodwill":25000000000,"otherIntangibleAssets":5000000000,"otherNonCurrentAssets":15000000000,"nonCurrentAssets":120000000000,"liabilities":100000000000,"currentLiabilities":35000000000,"accountsPayable":8000000000,"taxesPayable":2000000000,"totalPayable":10000000000,"otherCurrentAccruedLiabilities":6000000000,"currentCapitalLeaseObligations":1000000000,"currentDeferredLiabilities":4000000000,"otherCurrentLiabilities":5000000000,"totalNonCurrentLiabilities":65000000000,"longTermDebt":40000000000,"longTermCapitalLeaseObligations":5000000000,"otherNonCurrentLiabilities":14000000000,"stockholdersEquity":100000000000,"commonStock":4000000,"preferredStock":0,"retainedEarnings":80000000000,"otherEquityAdjustments":-4000000,"additionalPaidInCapital":20000000000,"capitalLeaseObligations":6000000000,"workingCapital":45000000000,"totalDebt":49000000000,"sharesIssued":4000000000,"storeCount":850,"sharesOutstanding":4000000000,"treasuryShares":4000000000,"currentSharesOutstanding":4000000000,"preferredSharesOutstanding":4000000000,"publicFloat":1000000000,"policyReserves":40000000000,"deferredAcquisitionCosts":3000000000,"propertyPlantAndEquipmentGross":80000000000,"propertyPlantAndEquipmentNet":50000000000,"constructionInProgress":1500000000,"costsInExcessOfBillings":1000000000,"billingsInExcessOfCosts":1000000000,"contractReceivableRetainage":800000000,"debtCurrent":4000000000,"longTermDebtCurrent":3000000000,"deposits":50000000000,"loans":60000000000,"allowanceForDoubtfulAccounts":200000000,"allowanceForCreditLossesLoans":800000000,"assetRetirementObligation":2000000000,"assetRetirementObligationCurrent":2000000000,"assetRetirementObligationNoncurrent":2000000000,"warrantyLiability":500000000,"contractLiabilityNoncurrent":3000000000,"remainingPerformanceObligations":8000000000,"investments":30000000000,"shortTermInvestments":15000000000,"longTermInvestments":25000000000,"lettersOfCreditOutstanding":500000000},"sources":{"0001234567-26-000001":{"type":"10-K","dateFiled":"2026-02-15","amendment":false,"facts":{"assets":{},"currentAssets":{},"cash":{},"netReceivables":{},"accountsReceivable":{},"inventory":{},"finishedGoods":{},"otherCurrentAssets":{},"accumulatedDepreciation":{},"goodwill":{},"otherIntangibleAssets":{},"otherNonCurrentAssets":{},"nonCurrentAssets":{},"liabilities":{},"currentLiabilities":{},"accountsPayable":{},"taxesPayable":{},"otherCurrentAccruedLiabilities":{},"currentCapitalLeaseObligations":{},"currentDeferredLiabilities":{},"otherCurrentLiabilities":{},"longTermDebt":{},"longTermCapitalLeaseObligations":{},"otherNonCurrentLiabilities":{},"stockholdersEquity":{},"commonStock":{},"preferredStock":{},"retainedEarnings":{},"otherEquityAdjustments":{},"additionalPaidInCapital":{},"sharesIssued":{},"storeCount":{},"sharesOutstanding":{},"treasuryShares":{},"currentSharesOutstanding":{},"preferredSharesOutstanding":{},"publicFloat":{},"policyReserves":{},"deferredAcquisitionCosts":{},"propertyPlantAndEquipmentGross":{},"propertyPlantAndEquipmentNet":{},"constructionInProgress":{},"costsInExcessOfBillings":{},"billingsInExcessOfCosts":{},"contractReceivableRetainage":{},"debtCurrent":{},"longTermDebtCurrent":{},"deposits":{},"loans":{},"allowanceForDoubtfulAccounts":{},"allowanceForCreditLossesLoans":{},"assetRetirementObligation":{},"assetRetirementObligationCurrent":{},"assetRetirementObligationNoncurrent":{},"warrantyLiability":{},"contractLiabilityNoncurrent":{},"remainingPerformanceObligations":{},"investments":{},"shortTermInvestments":{},"longTermInvestments":{},"lettersOfCreditOutstanding":{}}},"0001234567-26-000042":{"type":"10-K","dateFiled":"2026-05-30","amendment":true,"facts":{"assets":{"before":196000000000}}}},"derived":["totalPayable","capitalLeaseObligations","totalDebt","totalNonCurrentLiabilities","workingCapital"]}]}}},"400":{"description":"Invalid parameters or symbol not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/financials/cash-flow-statement":{"get":{"tags":["Financials"],"summary":"Cash flow statement","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns normalized cash flow data — operating, investing, and financing activities, free cash flow, capex, and more. Facts are mapped from raw XBRL to a curated set of standardized line items.\n\nUse `period=ttm` to get trailing twelve months data, computed by summing the last 4 reported quarters.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"period","required":false,"schema":{"type":"string","enum":["annual","quarter","ttm"],"default":"annual"},"description":"The reporting period: `annual`, `quarter`, or `ttm` (trailing twelve months). TTM sums the last 4 quarters for flow items."},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":80,"default":4},"description":"Maximum number of periods to return (may be clamped by subscription tier). Ignored when `period=ttm`."}],"responses":{"200":{"description":"Cash flow statement data organized by period","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string","description":"The fiscal period end date","example":"2023-09-30"},"fiscalYear":{"type":"integer","description":"The company's fiscal year (handles non-December year-ends — AAPL FY ends Sep, COST FY ends Aug).","example":2025},"fiscalPeriod":{"type":"string","enum":["FY","Q1","Q2","Q3","Q4","TTM"],"description":"The fiscal period type. `FY` for annual, `Q1`-`Q4` for quarterly, `TTM` for trailing-twelve-months.","example":"FY"},"facts":{"type":"object","description":"Normalized cash flow line items, keyed by curated fact name with numeric values.","properties":{"operatingCashFlow":{"type":"number","description":"Operating Cash Flow — Cash generated from core business operations."},"netIncome":{"type":"number","description":"Net Income (CF) — Net income as reported on the cash flow statement, starting point for operating cash flow."},"operatingGainsLosses":{"type":"number","description":"Operating Gains & Losses — Non-cash gains or losses removed from net income in the cash flow reconciliation."},"depreciationAndAmortization":{"type":"number","description":"D&A (CF) — Non-cash depreciation and amortization added back in the cash flow reconciliation."},"depreciation":{"type":"number","description":"Depreciation — Depreciation of physical assets, added back as a non-cash charge in the cash flow statement."},"amortization":{"type":"number","description":"Amortization — Amortization of intangible assets, added back as a non-cash charge in the cash flow statement."},"stockBasedCompensation":{"type":"number","description":"Stock-Based Compensation — Non-cash expense for employee equity compensation, added back to operating cash flow."},"deferredIncomeTax":{"type":"number","description":"Deferred Income Tax — Deferred income tax expense or benefit, a non-cash adjustment to operating cash flow reflecting timing differences between book and tax recognition. Reported literal as filed. **Overlap note**: some filers also include this amount inside the broader `otherNonCashItems` bucket — when both are present, do not add them together."},"otherNonCashItems":{"type":"number","description":"Other Non-Cash Items — Catch-all bucket for non-cash items in the operating cash flow reconciliation that aren't classified as D&A, stock-based comp, or specific gains/losses. Distinct from `operatingGainsLosses` which captures explicit gain/loss reclassifications. Reported literal as filed. **Overlap note**: some filers tag this concept inclusively — values may already contain amounts also tagged under more specific facts (e.g., `deferredIncomeTax`). Treat as a residual when summing components to avoid double-counting."},"changeInWorkingCapital":{"type":"number","description":"Change in Working Capital — Net change in current assets and liabilities, reflecting cash tied up in or released from operations."},"changeInInventory":{"type":"number","description":"Change in Inventory — Cash impact from changes in inventory levels. An increase uses cash."},"changeInAccountsReceivable":{"type":"number","description":"Change in Receivables — Cash impact from changes in customer receivables. An increase means less cash collected."},"changeInPrepaidAssets":{"type":"number","description":"Change in Prepaid Assets — Cash impact from changes in prepaid expenses and other prepaid items."},"changeInPayablesAndAccruedExpenses":{"type":"number","description":"Change in Payables — Cash impact from changes in accounts payable and accrued liabilities."},"changeInAccountsPayable":{"type":"number","description":"Change in Accounts Payable — Cash impact from changes in amounts owed to suppliers. An increase preserves cash."},"changeInAccruedExpenses":{"type":"number","description":"Change in Accrued Expenses — Cash impact from changes in accrued but unpaid expenses."},"changeInOtherNonCurrentAssets":{"type":"number","description":"Change in Other Non-Current Assets — Cash impact from changes in long-term assets not classified elsewhere."},"changeInOtherCurrentLiabilities":{"type":"number","description":"Change in Other Current Liabilities — Cash impact from changes in short-term obligations not classified elsewhere. Reported literal as filed. **Overlap note**: some filers tag this concept inclusively — values may already contain amounts also tagged under `changeInOtherWorkingCapital` (e.g., contract-liability changes). Treat as a residual when summing components."},"changeInOtherWorkingCapital":{"type":"number","description":"Change in Other Working Capital — Cash impact from changes in other working capital items not separately reported. Reported literal as filed. **Overlap note**: for some filers, this amount may also be embedded in the broader `changeInOtherCurrentLiabilities` bucket — when both are present, do not add them together."},"investingCashFlow":{"type":"number","description":"Investing Cash Flow — Cash used for or generated by investments in long-term assets and securities."},"purchaseOfIntangibleAssets":{"type":"number","description":"Purchase of Intangibles — Cash spent acquiring intangible assets like patents, licenses, and software."},"purchasesOfInvestments":{"type":"number","description":"Purchases of Investments — Cash spent buying investment securities like stocks and bonds."},"proceedsFromSaleOfInvestments":{"type":"number","description":"Proceeds from Sale of Investments — Cash received from selling or maturing investment securities. Mirror to `purchasesOfInvestments`. Filers that report sale and maturity proceeds on separate lines (e.g. AAPL, JPM) will populate this from whichever XBRL concept is filed first in the mapping order — the other line remains uncaptured."},"netOtherInvestingChanges":{"type":"number","description":"Other Investing Activities — Cash from investing activities not separately categorized. Reported literal as filed. **Overlap note**: some filers tag this concept inclusively — values may already contain amounts also tagged under more specific facts (e.g., `acquisitionsNet`, `purchaseOfIntangibleAssets`). Treat as a residual when summing components to avoid double-counting."},"financingCashFlow":{"type":"number","description":"Financing Cash Flow — Cash from transactions with the company's owners and creditors."},"commonStockRepurchased":{"type":"number","description":"Stock Buybacks — Cash spent repurchasing the company's own shares from the open market."},"proceedsFromStockOptionsExercised":{"type":"number","description":"Stock Option Proceeds — Cash received when employees exercise stock options."},"endCash":{"type":"number","description":"Ending Cash Balance — Cash and equivalents at the end of the reporting period."},"changeInCash":{"type":"number","description":"Change in Cash — Net increase or decrease in cash during the period, **excluding** the effect of foreign exchange rate changes. Equals operating + investing + financing cash flows. For the total period change (including FX), see `netChangeInCashIncludingFx`."},"effectOfExchangeRateChanges":{"type":"number","description":"FX Effect on Cash — Impact of foreign currency exchange rate fluctuations on cash balances."},"netChangeInCashIncludingFx":{"type":"number","description":"Net Change in Cash (incl. FX) — Total period change in cash including the effect of foreign exchange rate changes. Equals endCash − beginningCash."},"beginningCash":{"type":"number","description":"Beginning Cash Balance — Cash and equivalents at the start of the reporting period."},"incomeTaxPaid":{"type":"number","description":"Income Tax Paid — Actual cash paid for income taxes during the period."},"interestPaid":{"type":"number","description":"Interest Paid — Actual cash paid for interest on debt during the period."},"capitalExpenditure":{"type":"number","description":"Capital Expenditure — Cash spent on acquiring or upgrading physical assets like property, equipment, and facilities."},"purchaseOfPropertyPlantAndEquipment":{"type":"number","description":"Purchase of Property, Plant and Equipment — Cash paid to acquire or construct physical assets such as buildings, machinery, and equipment."},"issuanceOfDebt":{"type":"number","description":"Debt Issuance Proceeds — Cash received from issuing new debt, including both short-term and long-term borrowings."},"issuanceOfShortTermDebt":{"type":"number","description":"Short-Term Debt Issuance — Cash received from issuing short-term borrowings."},"issuanceOfLongTermDebt":{"type":"number","description":"Long-Term Debt Issuance — Cash received from issuing long-term debt instruments like bonds or term loans."},"repaymentOfLongTermDebt":{"type":"number","description":"Long-Term Debt Repayments — Cash used to repay long-term debt instruments. Mirror to `issuanceOfLongTermDebt`."},"cashDividendsPaid":{"type":"number","description":"Dividends Paid — Cash distributed to shareholders as dividend payments."},"freeCashFlow":{"type":"number","description":"Free Cash Flow — Operating cash flow minus capital expenditures. Cash available for debt repayment, dividends, or reinvestment."},"acquisitionsNet":{"type":"number","description":"Acquisitions (Net) — Cash paid for business acquisitions, net of any cash acquired in the transaction. Reported literal as filed. **Overlap note**: for some filers, this amount may also be embedded in the broader `netOtherInvestingChanges` bucket — when both are present, do not add them together."},"netOtherFinancingChanges":{"type":"number","description":"Other Financing Activities — Cash from financing activities not separately categorized. Mirror to `netOtherInvestingChanges`."},"taxWithholdingShareBasedComp":{"type":"number","description":"Tax Withholding for Share-Based Comp — Cash paid to tax authorities to cover withholding obligations on employee share-based compensation (e.g., RSU vesting). Reduces effective share dilution. Material for tech/cash-rich filers with heavy equity compensation."}}},"sources":{"$ref":"#/components/schemas/FactSources"},"derived":{"$ref":"#/components/schemas/DerivedFacts"},"dateFiled":{"type":"string","format":"date","description":"SEC filing acceptance date for the **original** 10-K (annual / Q4 quarterly entries) or 10-Q (Q1-Q3 quarterly entries) covering this period. Format: YYYY-MM-DD. Use this to gate point-in-time data access and avoid lookahead bias when joining with historical price data — backtesters should only treat the period's facts as \"knowable\" on or after this date. Amendments (10-K/A, 10-Q/A) are explicitly **not** used here; this field always reflects the original disclosure date. Not present when `period=ttm` — TTM is synthesized from 4 quarters and has no single filing date.\n","example":"2024-11-01"}}}},"example":[{"period":"2025-12-31","fiscalYear":2025,"fiscalPeriod":"FY","dateFiled":"2026-02-15","facts":{"operatingCashFlow":30000000000,"netIncome":25600000000,"operatingGainsLosses":100000000,"depreciationAndAmortization":4000000000,"depreciation":3000000000,"amortization":1000000000,"stockBasedCompensation":2500000000,"deferredIncomeTax":-200000000,"otherNonCashItems":150000000,"changeInWorkingCapital":-1000000000,"changeInInventory":-300000000,"changeInAccountsReceivable":-300000000,"changeInPrepaidAssets":-300000000,"changeInPayablesAndAccruedExpenses":-300000000,"changeInAccountsPayable":-300000000,"changeInAccruedExpenses":-300000000,"changeInOtherNonCurrentAssets":-300000000,"changeInOtherCurrentLiabilities":-300000000,"changeInOtherWorkingCapital":-300000000,"investingCashFlow":-8000000000,"purchaseOfIntangibleAssets":500000000,"purchasesOfInvestments":6000000000,"proceedsFromSaleOfInvestments":5000000000,"netOtherInvestingChanges":500000000,"financingCashFlow":-10000000000,"commonStockRepurchased":8000000000,"proceedsFromStockOptionsExercised":500000000,"endCash":25000000000,"changeInCash":12000000000,"effectOfExchangeRateChanges":0.21,"netChangeInCashIncludingFx":12100000000,"beginningCash":13000000000,"incomeTaxPaid":6500000000,"interestPaid":350000000,"capitalExpenditure":5000000000,"purchaseOfPropertyPlantAndEquipment":5000000000,"issuanceOfDebt":5000000000,"issuanceOfShortTermDebt":1000000000,"issuanceOfLongTermDebt":4000000000,"repaymentOfLongTermDebt":3000000000,"cashDividendsPaid":4000000000,"freeCashFlow":25000000000,"acquisitionsNet":2000000000,"netOtherFinancingChanges":-300000000,"taxWithholdingShareBasedComp":600000000},"sources":{"0001234567-26-000001":{"type":"10-K","dateFiled":"2026-02-15","amendment":false,"facts":{"operatingCashFlow":{},"netIncome":{},"operatingGainsLosses":{},"stockBasedCompensation":{},"deferredIncomeTax":{},"otherNonCashItems":{},"changeInInventory":{},"changeInAccountsReceivable":{},"changeInPrepaidAssets":{},"changeInAccountsPayable":{},"changeInAccruedExpenses":{},"changeInOtherNonCurrentAssets":{},"changeInOtherCurrentLiabilities":{},"changeInOtherWorkingCapital":{},"investingCashFlow":{},"purchaseOfIntangibleAssets":{},"purchasesOfInvestments":{},"proceedsFromSaleOfInvestments":{},"netOtherInvestingChanges":{},"financingCashFlow":{},"commonStockRepurchased":{},"proceedsFromStockOptionsExercised":{},"endCash":{},"effectOfExchangeRateChanges":{},"incomeTaxPaid":{},"interestPaid":{},"purchaseOfPropertyPlantAndEquipment":{},"issuanceOfShortTermDebt":{},"issuanceOfLongTermDebt":{},"repaymentOfLongTermDebt":{},"cashDividendsPaid":{},"acquisitionsNet":{},"netOtherFinancingChanges":{},"taxWithholdingShareBasedComp":{}}},"0001234567-26-000042":{"type":"10-K","dateFiled":"2026-05-30","amendment":true,"facts":{"operatingCashFlow":{"before":29400000000}}}},"derived":["depreciationAndAmortization","amortization","depreciation","changeInPayablesAndAccruedExpenses","changeInWorkingCapital","issuanceOfDebt","beginningCash","changeInCash","netChangeInCashIncludingFx","capitalExpenditure","freeCashFlow"]}]}}},"400":{"description":"Invalid parameters or symbol not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/financials/growth":{"get":{"tags":["Financials"],"summary":"Financial growth rates","description":"![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns year-over-year growth rates for key financial line items. Each value is expressed as a decimal (e.g. 0.15 = 15% growth, -0.08 = 8% decline). Computed as `(current - previous) / |previous|`.\n\nCovers revenue, gross profit, operating income, net income, EPS, EBITDA, free cash flow, total assets, stockholders' equity, and operating cash flow.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"period","required":false,"schema":{"type":"string","enum":["annual","quarter","ttm"],"default":"annual"},"description":"The reporting period: `annual`, `quarter`, or `ttm` (trailing twelve months)."},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":80,"default":4},"description":"Maximum number of periods to return (may be clamped by subscription tier). Ignored when `period=ttm`."}],"responses":{"200":{"description":"Growth rates by period (most recent first)","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string","description":"The fiscal period end date","example":"2024-09-28"},"fiscalYear":{"type":"integer","description":"The company's fiscal year (handles non-December year-ends — AAPL FY ends Sep, COST FY ends Aug).","example":2025},"fiscalPeriod":{"type":"string","enum":["FY","Q1","Q2","Q3","Q4","TTM"],"description":"The fiscal period type. `FY` for annual, `Q1`-`Q4` for quarterly, `TTM` for trailing-twelve-months.","example":"FY"},"revenueGrowth":{"type":"number","nullable":true,"description":"Revenue year-over-year growth","example":0.0202},"grossProfitGrowth":{"type":"number","nullable":true,"description":"Gross profit year-over-year growth","example":0.0561},"operatingIncomeGrowth":{"type":"number","nullable":true,"description":"Operating income year-over-year growth","example":0.0789},"netIncomeGrowth":{"type":"number","nullable":true,"description":"Net income year-over-year growth","example":-0.0345},"epsGrowth":{"type":"number","nullable":true,"description":"Earnings per share year-over-year growth","example":-0.0123},"ebitdaGrowth":{"type":"number","nullable":true,"description":"EBITDA year-over-year growth","example":0.0634},"freeCashFlowGrowth":{"type":"number","nullable":true,"description":"Free cash flow year-over-year growth","example":0.1245},"totalAssetsGrowth":{"type":"number","nullable":true,"description":"Total assets year-over-year growth","example":0.0156},"stockholdersEquityGrowth":{"type":"number","nullable":true,"description":"Stockholders' equity year-over-year growth","example":0.0234},"operatingCashFlowGrowth":{"type":"number","nullable":true,"description":"Operating cash flow year-over-year growth","example":0.0891}}}}}}},"400":{"description":"Invalid parameters or symbol not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/financials/key-metrics":{"get":{"tags":["Financials"],"summary":"Sector-aware key metrics","description":"![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns financial metrics organized in three blocks: **`general`** (every company), **`sectorMetrics`** (varies by SIC-derived sector), and **`industryMetrics`** (varies by industry-group). The full catalog of every possible field with its formula and unit is documented under the `KeyMetricsGeneral`, `KeyMetricsSector`, and `KeyMetricsIndustry` schemas referenced below.\n\nMargins/percentages are returned as percentage values (e.g. `68.82` means `68.82%`). Ratios are decimals (e.g. `1.87` = `1.87x`). A handful of legacy keys (`pretaxProfitMargin`, `effectiveTaxRate`) are returned as raw decimals — see the per-key descriptions in the schema. `null` means the underlying fact wasn't tagged for that period or a divisor was zero.\n\n### Sector → metric mapping\n\nThe `sectorId` field on each entry maps to one of the views below; `sectorMetrics` will contain only the keys associated with that view. Companies whose SIC doesn't map to any sector get an empty `sectorMetrics: {}`.\n\n| sectorId | Keys returned in `sectorMetrics` |\n|----------|---------------------------------|\n| `agriculture`    | `ppeIntensity`, `capexDepreciation`, `inventoryTurnover`, `daysInventory`, `ccc`, `grossMargin`, `operatingMargin`, `roa`, `debtEquity`, `interestCoverage` |\n| `banking`        | `netInterestIncome`, `interestIncome`, `interestExpense`, `nim`, `roa`, `roe`, `loanToDeposit`, `allowanceToLoans`, `efficiencyRatio`, `provisionToLoans` |\n| `construction`   | `contractAssetRatio`, `contractLiabilityRatio`, `dso`, `dpo`, `ccc`, `workingCapitalRatio`, `ppeIntensity`, `debtEquity`, `interestCoverage`, `retainage`, `cipRatio`, `bondingCapacity` |\n| `insurance`      | `lossRatio`, `expenseRatio`, `combinedRatio`, `underwritingIncome`, `investmentIncome`, `netProfitMargin`, `roa`, `roe`, `insuranceLeverage`, `reserveRatio`, `premiumGrowth`, `dacRatio`, `floatYield`, `bookValueGrowth`, `floatSize` |\n| `manufacturing`  | `inventoryTurnover`, `daysInventory`, `grossMargin`, `operatingMargin`, `dso`, `dpo`, `ccc`, `capexRevenue`, `capexDepreciation`, `assetTurnover`, `warrantyReserve` |\n| `mining`         | `ppeIntensity`, `capexDda`, `grossMargin`, `operatingMargin`, `ebitdaMargin`, `ocfRevenue`, `roa`, `debtEquity`, `interestCoverage`, `aroCurrent`, `aroNoncurrent` |\n| `reit`           | `ffo`, `affo`, `ffoPerShare`, `payoutRatio`, `debtToAssets`, `interestCoverage` |\n| `retail-trade`   | `storeCount`, `revenuePerStore`, `incomePerStore`, `inventoryTurnover`, `daysInventory`, `inventoryPerStore`, `inventoryRevenue`, `sgaRevenue` |\n| `services`       | `grossMargin`, `operatingMargin`, `ebitdaMargin`, `netMargin`, `sgaRevenue`, `roe`, `dso` |\n| `telecom`        | `revenueGrowth`, `grossMargin`, `operatingMargin`, `ebitdaMargin`, `capexRevenue`, `debtEbitda`, `dividendPayout`, `dividendCoverage` |\n| `transportation` | `operatingRatio`, `grossMargin`, `operatingMargin`, `assetTurnover`, `roa`, `capexRevenue`, `capexDepreciation`, `debtToEquity`, `ebitdaMargin`, `interestCoverage` |\n| `utilities`      | `roe`, `operatingMargin`, `dividendPayout`, `dividendCoverage`, `capexDepreciation`, `capexRevenue`, `debtEquity`, `interestCoverage` |\n| `wholesale`      | `grossMargin`, `operatingMargin`, `netMargin`, `dso`, `dpo`, `dio`, `ccc`, `inventoryTurnover`, `assetTurnover`, `roa`, `allowancePctAr` |\n\n### Industry → metric mapping\n\nThe `industryId` field on each entry maps to one of the eight specialized industry views below; `industryMetrics` will contain only the keys associated with that view. Companies outside these eight industries get an empty `industryMetrics: {}`.\n\n| industryId | Keys returned in `industryMetrics` |\n|------------|------------------------------------|\n| `semiconductor` | `rdToRevenue`, `sbcToRevenue`, `fcfConversion`, `fcfMargin` |\n| `software`      | `rdToRevenue`, `sgaToRevenue`, `sbcToRevenue`, `fcfMargin`, `deferredRevenue`, `deferredRevenueGrowth`, `billings`, `remainingPerformanceObligations` |\n| `pharma`        | `rdToRevenue`, `sbcToRevenue`, `cashRunwayQuarters`, `fcfMargin` |\n| `aerospace`     | `rdToRevenue`, `fcfConversion`, `daToRevenue`, `debtToEbitda`, `interestCoverage` |\n| `automotive`    | `rdToRevenue`, `capexToDepreciation`, `inventoryTurnover`, `fcfMargin`, `debtToEquity` |\n| `airlines`      | `ebitdaMargin`, `fcfMargin`, `debtToEbitda`, `capexToRevenue`, `interestCoverage` |\n| `oil-gas`       | `ebitdaMargin`, `fcfMargin`, `capexToRevenue`, `debtToEbitda`, `dividendPayout` |\n| `fintech`       | `grossMargin`, `rdToRevenue`, `sgaToRevenue`, `fcfMargin`, `sbcToRevenue` |\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"period","required":false,"schema":{"type":"string","enum":["annual","quarter","ttm"],"default":"annual"},"description":"The reporting period: `annual`, `quarter`, or `ttm` (trailing twelve months)."},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":80,"default":4},"description":"Maximum number of periods to return (may be clamped by subscription tier). Ignored when `period=ttm`."}],"responses":{"200":{"description":"Key metrics organized by period with general, sector, and industry tiers","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["period","fiscalYear","fiscalPeriod","sector","sectorId","industry","industryId","general","sectorMetrics","industryMetrics"],"properties":{"period":{"type":"string","format":"date","description":"The fiscal period end date (YYYY-MM-DD).","example":"2025-06-30"},"fiscalYear":{"type":"integer","description":"The company's fiscal year (handles non-December year-ends — AAPL FY ends September, COST FY ends August).","example":2025},"fiscalPeriod":{"type":"string","enum":["FY","Q1","Q2","Q3","Q4","TTM"],"description":"The fiscal period type. `FY` for annual, `Q1`–`Q4` for quarterly, `TTM` for trailing-twelve-months.","example":"FY"},"sector":{"type":"string","nullable":true,"description":"Broad sector classification derived from SIC code.","example":"Services"},"sectorId":{"type":"string","nullable":true,"description":"Sector identifier used to determine which metric set populates `sectorMetrics`. One of: `agriculture`, `banking`, `construction`, `insurance`, `manufacturing`, `mining`, `reit`, `retail-trade`, `services`, `telecom`, `transportation`, `utilities`, `wholesale`, or `null`.","example":"services"},"industry":{"type":"string","nullable":true,"description":"Detailed industry classification derived from SIC code.","example":"Software Publishers"},"industryId":{"type":"string","nullable":true,"description":"Industry identifier used to determine which metric set populates `industryMetrics`. One of: `semiconductor`, `software`, `pharma`, `aerospace`, `automotive`, `airlines`, `oil-gas`, `fintech`, or `null`.","example":"software"},"general":{"$ref":"#/components/schemas/KeyMetricsGeneral"},"sectorMetrics":{"$ref":"#/components/schemas/KeyMetricsSector"},"industryMetrics":{"$ref":"#/components/schemas/KeyMetricsIndustry"}}}},"example":[{"period":"2025-06-30","fiscalYear":2025,"fiscalPeriod":"FY","sector":"Services","sectorId":"services","industry":"Software Publishers","industryId":"software","general":{"revenue":281724000000,"netIncome":101832000000,"grossMargin":68.8237423861652,"operatingMargin":45.62195624085985,"profitMargin":36.146015248967075,"debtToEquity":0.12562922332951942,"quickRatio":0.7091659703437239,"currentRatio":1.3534464445042416,"roa":18.004784443662558,"roe":33.280824111537434,"roic":31.896602768520527,"eps":13.7,"ebitda":123803000000,"freeCashFlow":71611000000,"fcfMargin":25.418849654271558,"fcfNetIncome":70.3226883494383,"assetTurnover":0.49811256703260176,"interestCoverage":53.89014675052411,"netDebt":18964000000,"netDebtEbitda":0.15317884057736889,"investedCapital":362443000000,"sbcRevenue":4.250259118853913,"dividendPayout":23.648754811846963,"netShareChange":0,"cashRatio":0.2142,"operatingCashFlowRatio":0.9642,"receivablesTurnover":4.4426,"payablesTurnover":3.533,"inventoryTurnover":80.4313,"fixedAssetTurnover":1.6545,"financialLeverageRatio":1.8022,"longTermDebtToCapitalRatio":0.1116,"freeCashFlowOperatingCashFlowRatio":0.5259,"capitalExpenditureCoverageRatio":2.1094,"pretaxProfitMargin":0.4388,"effectiveTaxRate":0.1763,"revenuePerShare":37.7393,"netIncomePerShare":13.6413,"operatingCashFlowPerShare":18.2401,"freeCashFlowPerShare":9.5929,"cashPerShare":4.0512,"bookValuePerShare":46.0119},"sectorMetrics":{"grossMargin":68.8237423861652,"operatingMargin":45.62195624085985,"ebitdaMargin":43.94478283710298,"netMargin":36.146015248967075,"sgaRevenue":11.669932274140649,"roe":33.280824111537434,"dso":82.15946280757053},"industryMetrics":{"rdToRevenue":11.531853871164687,"sgaToRevenue":11.669932274140649,"sbcToRevenue":4.250259118853913,"fcfMargin":25.418849654271558,"deferredRevenue":64555000000,"deferredRevenueGrowth":12.10968705498246,"billings":288697000000,"remainingPerformanceObligations":375000000000}},{"period":"2024-06-30","fiscalYear":2024,"fiscalPeriod":"FY","sector":"Services","sectorId":"services","industry":"Software Publishers","industryId":"software","general":{"revenue":245122000000,"netIncome":88136000000,"grossMargin":69.76444382797138,"operatingMargin":44.64429957327371,"profitMargin":35.955972944084984,"debtToEquity":0.16737746622615718,"quickRatio":0.6005379691266383,"currentRatio":1.2749549031815206,"roa":19.074186891798746,"roe":37.13334737729092,"roic":34.03855402542557,"eps":11.86,"ebitda":108114000000,"freeCashFlow":74071000000,"fcfMargin":30.218013886962407,"fcfNetIncome":84.04170826903876,"assetTurnover":0.5304872968243954,"interestCoverage":37.285519591141394,"netDebt":32906000000,"netDebtEbitda":0.30436391216678693,"investedCapital":301383000000,"sbcRevenue":4.3790439046678795,"dividendPayout":24.701597531088318,"netShareChange":0.026910656620021525,"cashRatio":0.1462,"operatingCashFlowRatio":0.9462,"receivablesTurnover":4.6419,"payablesTurnover":3.6973,"inventoryTurnover":39.5697,"fixedAssetTurnover":2.1201,"financialLeverageRatio":1.9077,"longTermDebtToCapitalRatio":0.1434,"freeCashFlowOperatingCashFlowRatio":0.6248,"capitalExpenditureCoverageRatio":2.6654,"pretaxProfitMargin":0.4397,"effectiveTaxRate":0.1823,"revenuePerShare":32.8186,"netIncomePerShare":11.8002,"operatingCashFlowPerShare":15.872,"freeCashFlowPerShare":9.9171,"cashPerShare":2.4521,"bookValuePerShare":35.9455},"sectorMetrics":{"grossMargin":69.76444382797138,"operatingMargin":44.64429957327371,"ebitdaMargin":44.10620017787061,"netMargin":35.955972944084984,"sgaRevenue":13.081241177862452,"roe":37.13334737729092,"dso":78.63100823263518},"industryMetrics":{"rdToRevenue":12.038903076835208,"sgaToRevenue":13.081241177862452,"sbcToRevenue":4.3790439046678795,"fcfMargin":30.218013886962407,"deferredRevenue":57582000000,"deferredRevenueGrowth":13.125478870749102,"billings":251803000000,"remainingPerformanceObligations":275000000000}},{"period":"2023-06-30","fiscalYear":2023,"fiscalPeriod":"FY","sector":"Services","sectorId":"services","industry":"Software Publishers","industryId":"software","general":{"revenue":211915000000,"netIncome":72361000000,"grossMargin":68.92008588349103,"operatingMargin":41.7728806361041,"profitMargin":34.14623787839464,"debtToEquity":0.2290578645446919,"quickRatio":0.8006989985501541,"currentRatio":1.76916725076573,"roa":18.63015179913905,"roe":38.82392391989591,"roic":33.16596104432817,"eps":9.72,"ebitda":88300000000,"freeCashFlow":59475000000,"fcfMargin":28.06549795908737,"fcfNetIncome":82.1920647862799,"assetTurnover":0.5455989577969558,"interestCoverage":44.98119918699187,"netDebt":18162000000,"netDebtEbitda":0.20568516421291053,"investedCapital":224385000000,"sbcRevenue":4.53530896821839,"dividendPayout":27.36280593137187,"netShareChange":-0.4287245444801715,"cashRatio":0.3332,"operatingCashFlowRatio":0.8409,"receivablesTurnover":4.5598,"payablesTurnover":3.551,"inventoryTurnover":21.1032,"fixedAssetTurnover":2.4925,"financialLeverageRatio":1.9977,"longTermDebtToCapitalRatio":0.1864,"freeCashFlowOperatingCashFlowRatio":0.6791,"capitalExpenditureCoverageRatio":3.116,"pretaxProfitMargin":0.4214,"effectiveTaxRate":0.1898,"revenuePerShare":28.3612,"netIncomePerShare":9.6843,"operatingCashFlowPerShare":11.7214,"freeCashFlowPerShare":7.9597,"cashPerShare":4.6445,"bookValuePerShare":27.5994},"sectorMetrics":{"grossMargin":68.92008588349103,"operatingMargin":41.7728806361041,"ebitdaMargin":41.66764976523606,"netMargin":34.14623787839464,"sgaRevenue":14.31422976193285,"roe":38.82392391989591,"dso":80.04715333978245},"industryMetrics":{"rdToRevenue":12.832975485454073,"sgaToRevenue":14.31422976193285,"sbcToRevenue":4.53530896821839,"fcfMargin":28.06549795908737,"deferredRevenue":50901000000,"deferredRevenueGrowth":11.776977469366244,"billings":217278000000,"remainingPerformanceObligations":229000000000}},{"period":"2022-06-30","fiscalYear":2022,"fiscalPeriod":"FY","sector":"Services","sectorId":"services","industry":"Software Publishers","industryId":"software","general":{"revenue":198270000000,"netIncome":72738000000,"grossMargin":68.4016744842891,"operatingMargin":42.05527815604983,"profitMargin":36.68633681343622,"debtToEquity":0.2989095843691081,"quickRatio":0.6120190993037589,"currentRatio":1.7846069708251824,"roa":20.82336724308958,"roe":47.15133050270639,"roic":36.24281762025356,"eps":9.7,"ebitda":83351000000,"freeCashFlow":65149000000,"fcfMargin":32.85872799717557,"fcfNetIncome":89.56666391707223,"assetTurnover":0.5676055188879776,"interestCoverage":40.41832283082889,"netDebt":41580000000,"netDebtEbitda":0.4988542429005051,"investedCapital":208122000000,"sbcRevenue":3.7837292580824124,"dividendPayout":24.931947537738182,"netShareChange":-0.7314802500332491,"cashRatio":0.1465,"operatingCashFlowRatio":0.9364,"receivablesTurnover":4.818,"payablesTurnover":3.6677,"inventoryTurnover":19.6457,"fixedAssetTurnover":2.9568,"financialLeverageRatio":2.1907,"longTermDebtToCapitalRatio":0.2301,"freeCashFlowOperatingCashFlowRatio":0.7317,"capitalExpenditureCoverageRatio":3.7275,"pretaxProfitMargin":0.4222,"effectiveTaxRate":0.1311,"revenuePerShare":26.2958,"netIncomePerShare":9.6469,"operatingCashFlowPerShare":11.8084,"freeCashFlowPerShare":8.6405,"cashPerShare":1.8476,"bookValuePerShare":22.0878},"sectorMetrics":{"grossMargin":68.4016744842891,"operatingMargin":42.05527815604983,"ebitdaMargin":42.039138548444036,"netMargin":36.68633681343622,"sgaRevenue":13.983456902204065,"roe":47.15133050270639,"dso":75.75770414081808},"industryMetrics":{"rdToRevenue":12.362939426035204,"sgaToRevenue":13.983456902204065,"sbcToRevenue":3.7837292580824124,"fcfMargin":32.85872799717557,"deferredRevenue":45538000000,"deferredRevenueGrowth":9.664057796508127,"billings":202283000000,"remainingPerformanceObligations":193000000000}}]}}},"400":{"description":"Invalid parameters or symbol not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/financials/scores":{"get":{"tags":["Financials"],"summary":"Financial health scores","description":"![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns two well-known financial health scores computed from the company's most recent annual filings:\n\n**Piotroski F-Score** (0–9): A composite score measuring financial strength across 9 binary criteria in three categories:\n\n| Category | Criteria | Signal |\n|----------|----------|--------|\n| Profitability | Positive net income | +1 |\n| Profitability | Positive operating cash flow | +1 |\n| Profitability | Rising return on assets (YoY) | +1 |\n| Profitability | Cash flow exceeds net income (earnings quality) | +1 |\n| Leverage | Declining debt-to-assets ratio (YoY) | +1 |\n| Leverage | Rising current ratio (YoY) | +1 |\n| Leverage | No share dilution (YoY) | +1 |\n| Efficiency | Rising gross margin (YoY) | +1 |\n| Efficiency | Rising asset turnover (YoY) | +1 |\n\nScores 7–9 indicate strong financial health; 0–3 indicate weakness.\n\n**Altman Z-Score**: A bankruptcy prediction model using 5 weighted ratios:\n`Z = 1.2×(Working Capital/Assets) + 1.4×(Retained Earnings/Assets) + 3.3×(EBIT/Assets) + 0.6×(Equity/Liabilities) + 1.0×(Revenue/Assets)`\n\n| Zone | Z-Score | Interpretation |\n|------|---------|----------------|\n| Safe | > 2.99 | Low bankruptcy risk |\n| Grey | 1.81 – 2.99 | Moderate risk, needs monitoring |\n| Distress | < 1.81 | High bankruptcy risk |\n\nNote: The equity component uses book value of equity as a proxy (market capitalization is not available).\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Financial health scores from the most recent annual filing","content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"string","description":"The fiscal year end date used for computation","example":"2024-09-28"},"fiscalYear":{"type":"integer","description":"The company's fiscal year (handles non-December year-ends — AAPL FY ends Sep, COST FY ends Aug).","example":2025},"fiscalPeriod":{"type":"string","enum":["FY","Q1","Q2","Q3","Q4","TTM"],"description":"The fiscal period type. `FY` for annual, `Q1`-`Q4` for quarterly, `TTM` for trailing-twelve-months.","example":"FY"},"piotroskiFScore":{"type":"integer","description":"Piotroski F-Score (0–9)","minimum":0,"maximum":9,"example":7},"piotroskiDetails":{"type":"object","description":"Individual Piotroski criteria results","properties":{"positiveNetIncome":{"type":"boolean","example":true},"positiveOperatingCashFlow":{"type":"boolean","example":true},"risingRoa":{"type":"boolean","example":true},"cashFlowExceedsNetIncome":{"type":"boolean","example":true},"decliningLeverage":{"type":"boolean","example":false},"risingCurrentRatio":{"type":"boolean","example":true},"noShareDilution":{"type":"boolean","example":true},"risingGrossMargin":{"type":"boolean","example":true},"risingAssetTurnover":{"type":"boolean","example":false}}},"altmanZScore":{"type":"number","nullable":true,"description":"Altman Z-Score (null if insufficient data)","example":4.12},"altmanZone":{"type":"string","nullable":true,"description":"Altman Z-Score classification","enum":["safe","grey","distress"],"example":"safe"}}}}}},"400":{"description":"Invalid parameters, symbol not found, or company has no annual financial filings (e.g. SPACs, shell companies, pre-revenue companies)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/financials/chart/scores":{"get":{"tags":["Financials"],"summary":"Financial health scores chart","description":"![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns chart-ready data for financial health scores over time: Piotroski F-Score (0–9) and Altman Z-Score. Annual periods only.\nEach period requires a prior year for Piotroski YoY comparisons, so internally fetches `limit + 1` periods.\nAltman Z-Score may be null for periods with insufficient balance sheet data.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":80,"default":4},"description":"Maximum number of periods (may be clamped by subscription tier)"}],"responses":{"200":{"description":"Series-oriented chart data with periods sorted ascending","content":{"application/json":{"schema":{"type":"object","required":["periods","series"],"properties":{"periods":{"type":"array","description":"Reporting period end dates (YYYY-MM-DD), sorted ascending. Each entry corresponds index-wise to the values in every `series.data` array. Annual periods only.","items":{"type":"string","format":"date"}},"series":{"type":"array","description":"Always returns two entries — `Piotroski F-Score` (integer 0–9, higher is better) and `Altman Z-Score` (decimal; >2.99 = safe zone, 1.81–2.99 = grey zone, <1.81 = distress zone) — in that order. Altman Z-Score may be `null` for periods where required balance sheet items aren't tagged. Piotroski may be `null` only when the prior-year comparison values are missing.","items":{"type":"object","required":["name","data"],"properties":{"name":{"type":"string","enum":["Piotroski F-Score","Altman Z-Score"]},"data":{"type":"array","items":{"type":"number","nullable":true}}}}}}},"example":{"periods":["2016-09-26","2017-09-26","2018-09-26","2019-09-26","2020-09-26","2021-09-26","2022-09-26","2023-09-26","2024-09-26","2025-09-26"],"series":[{"name":"Piotroski F-Score","data":[5,4,6,6,7,7,8,7,6,8]},{"name":"Altman Z-Score","data":[2.19,1.94,1.93,2.01,1.88,2.25,2.26,2.27,null,null]}]}}}},"400":{"description":"Invalid parameters or symbol not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/financials/chart/revenue-profitability":{"get":{"tags":["Financials"],"summary":"Revenue & profitability chart","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns chart-ready data for revenue, net income, and profitability margins over time. Periods are sorted ascending. Use `series` for absolute values and `rates` for margin ratios.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"period","required":false,"schema":{"type":"string","enum":["annual","quarter"],"default":"annual"},"description":"The reporting period"},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":80,"default":4},"description":"Maximum number of periods (may be clamped by subscription tier)"}],"responses":{"200":{"description":"Series-oriented chart data with periods sorted ascending","content":{"application/json":{"schema":{"type":"object","required":["periods","series","rates"],"properties":{"periods":{"type":"array","description":"Reporting period end dates (YYYY-MM-DD), sorted ascending. Each entry corresponds index-wise to the values in every `series.data` and `rates.data` array.","items":{"type":"string","format":"date"}},"series":{"type":"array","description":"Absolute value series in USD. Always returns two entries — `Revenue`, `Net Income` — in that order. Individual data points may be `null` for periods where the underlying fact wasn't tagged.","items":{"type":"object","required":["name","data"],"properties":{"name":{"type":"string","enum":["Revenue","Net Income"]},"data":{"type":"array","items":{"type":"number","nullable":true}}}}},"rates":{"type":"array","description":"Margin ratio series, expressed as decimals (e.g. 0.469 = 46.9%). Always returns three entries — `Gross Margin`, `Operating Margin`, `Net Margin` — in that order.","items":{"type":"object","required":["name","data"],"properties":{"name":{"type":"string","enum":["Gross Margin","Operating Margin","Net Margin"]},"data":{"type":"array","items":{"type":"number","nullable":true}}}}}}},"example":{"periods":["2016-09-26","2017-09-26","2018-09-26","2019-09-26","2020-09-26","2021-09-26","2022-09-26","2023-09-26","2024-09-26","2025-09-26"],"series":[{"name":"Revenue","data":[215639000000,229234000000,265595000000,260174000000,274515000000,365817000000,394328000000,383285000000,391035000000,416161000000]},{"name":"Net Income","data":[45687000000,48351000000,59531000000,55256000000,57411000000,94680000000,99803000000,96995000000,93736000000,112010000000]}],"rates":[{"name":"Gross Margin","data":[0.3908,0.3847,0.3834,0.3782,0.3823,0.4178,0.4331,0.4413,0.4621,0.4691]},{"name":"Operating Margin","data":[0.2784,0.2676,0.2669,0.2457,0.2415,0.2978,0.3029,0.2982,0.3151,0.3197]},{"name":"Net Margin","data":[0.2119,0.2109,0.2241,0.2124,0.2091,0.2588,0.2531,0.2531,0.2397,0.2692]}]}}}},"400":{"description":"Invalid parameters or symbol not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/financials/chart/cash-flow":{"get":{"tags":["Financials"],"summary":"Cash flow chart","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns chart-ready data for operating cash flow, capital expenditure, and free cash flow over time. Periods are sorted ascending.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"period","required":false,"schema":{"type":"string","enum":["annual","quarter"],"default":"annual"},"description":"The reporting period"},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":80,"default":4},"description":"Maximum number of periods (may be clamped by subscription tier)"}],"responses":{"200":{"description":"Series-oriented chart data with periods sorted ascending","content":{"application/json":{"schema":{"type":"object","required":["periods","series"],"properties":{"periods":{"type":"array","description":"Reporting period end dates (YYYY-MM-DD), sorted ascending. Each entry corresponds index-wise to the values in every `series.data` array.","items":{"type":"string","format":"date"}},"series":{"type":"array","description":"Cash flow series in absolute USD. Always returns three entries — `Operating Cash Flow`, `Capital Expenditure`, `Free Cash Flow` — in that order. Capital Expenditure is reported as a positive outflow value (subtracted from operating cash flow to derive free cash flow). Individual data points may be `null` for periods where the underlying fact wasn't tagged.","items":{"type":"object","required":["name","data"],"properties":{"name":{"type":"string","enum":["Operating Cash Flow","Capital Expenditure","Free Cash Flow"]},"data":{"type":"array","items":{"type":"number","nullable":true}}}}}}},"example":{"periods":["2016-09-26","2017-09-26","2018-09-26","2019-09-26","2020-09-26","2021-09-26","2022-09-26","2023-09-26","2024-09-26","2025-09-26"],"series":[{"name":"Operating Cash Flow","data":[66231000000,64225000000,77434000000,69391000000,80674000000,104038000000,122151000000,110543000000,118254000000,111482000000]},{"name":"Capital Expenditure","data":[12734000000,12451000000,13313000000,10495000000,7309000000,11085000000,10708000000,10959000000,9447000000,12715000000]},{"name":"Free Cash Flow","data":[53497000000,51774000000,64121000000,58896000000,73365000000,92953000000,111443000000,99584000000,108807000000,98767000000]}]}}}},"400":{"description":"Invalid parameters or symbol not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/financials/chart/balance-sheet-health":{"get":{"tags":["Financials"],"summary":"Balance sheet health chart","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns chart-ready data for balance sheet composition (assets, liabilities, debt, cash) and health ratios (debt-to-equity, current ratio) over time. Periods are sorted ascending. Use `series` for absolute values and `rates` for ratios.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"period","required":false,"schema":{"type":"string","enum":["annual","quarter"],"default":"annual"},"description":"The reporting period"},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":80,"default":4},"description":"Maximum number of periods (may be clamped by subscription tier)"}],"responses":{"200":{"description":"Series-oriented chart data with periods sorted ascending","content":{"application/json":{"schema":{"type":"object","required":["periods","series","rates"],"properties":{"periods":{"type":"array","description":"Reporting period end dates (YYYY-MM-DD), sorted ascending. Each entry corresponds index-wise to the values in every `series.data` and `rates.data` array.","items":{"type":"string","format":"date"}},"series":{"type":"array","description":"Balance sheet composition series in absolute USD. Always returns four entries — `Total Assets`, `Total Liabilities`, `Total Debt`, `Cash` — in that order. Individual data points may be `null` for periods where the underlying fact wasn't tagged.","items":{"type":"object","required":["name","data"],"properties":{"name":{"type":"string","enum":["Total Assets","Total Liabilities","Total Debt","Cash"]},"data":{"type":"array","items":{"type":"number","nullable":true}}}}},"rates":{"type":"array","description":"Health ratio series, expressed as decimals (e.g. 1.24 = 124%). Always returns two entries — `Debt to Equity`, `Current Ratio` — in that order.","items":{"type":"object","required":["name","data"],"properties":{"name":{"type":"string","enum":["Debt to Equity","Current Ratio"]},"data":{"type":"array","items":{"type":"number","nullable":true}}}}}}},"example":{"periods":["2016-09-26","2017-09-26","2018-09-26","2019-09-26","2020-09-26","2021-09-26","2022-09-26","2023-09-26","2024-09-26","2025-09-26"],"series":[{"name":"Total Assets","data":[321686000000,375319000000,365725000000,338516000000,323888000000,351002000000,352755000000,352583000000,364980000000,359241000000]},{"name":"Total Liabilities","data":[193437000000,241272000000,258578000000,248028000000,258549000000,287912000000,302083000000,290437000000,308030000000,285508000000]},{"name":"Total Debt","data":[78384000000,104021000000,104193000000,101679000000,106078000000,118063000000,111824000000,106572000000,97341000000,91281000000]},{"name":"Cash","data":[20484000000,20289000000,25913000000,48844000000,38016000000,34940000000,23646000000,29965000000,29943000000,35934000000]}],"rates":[{"name":"Debt to Equity","data":[0.6112,0.776,0.9724,1.1237,1.6235,1.8713,2.2068,1.7149,1.7092,1.238]},{"name":"Current Ratio","data":[1.3527,1.2761,1.1329,1.5401,1.3636,1.0746,0.8794,0.988,0.8673,0.8933]}]}}}},"400":{"description":"Invalid parameters or symbol not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/financials/chart/per-share":{"get":{"tags":["Financials"],"summary":"Per-share metrics chart","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns chart-ready data for per-share financial metrics over time: EPS, revenue per share, book value per share, and free cash flow per share. Periods are sorted ascending. Uses diluted weighted average shares outstanding when available.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"period","required":false,"schema":{"type":"string","enum":["annual","quarter"],"default":"annual"},"description":"The reporting period"},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":80,"default":4},"description":"Maximum number of periods (may be clamped by subscription tier)"}],"responses":{"200":{"description":"Series-oriented chart data with periods sorted ascending","content":{"application/json":{"schema":{"type":"object","properties":{"periods":{"type":"array","items":{"type":"string"},"example":["2021-09-25","2022-09-24","2023-09-30","2024-09-28"]},"series":{"type":"array","description":"Per-share metric series (EPS, Revenue Per Share, Book Value Per Share, Free Cash Flow Per Share)","items":{"type":"object","properties":{"name":{"type":"string","example":"EPS"},"data":{"type":"array","items":{"type":"number","nullable":true},"example":[5.67,6.15,6.16,6.08]}}}}}}}}},"400":{"description":"Invalid parameters or symbol not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/fund/profile":{"get":{"tags":["ETF/MF"],"summary":"Fund profile","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns quarterly snapshots of a fund's financial profile, sourced from SEC N-PORT filings. Includes total assets, liabilities, net assets, monthly returns, sales/redemptions flow, and number of holdings.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":10},"description":"Fund ticker symbol (ETF or mutual fund)","example":"SPY"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Quarterly fund profile snapshots (most recent first)","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"reportDate":{"type":"string","description":"Quarter-end report date (YYYY-MM-DD)","example":"2025-12-31"},"seriesId":{"type":"integer","description":"Series ID for the fund","example":0},"seriesName":{"type":"string","nullable":true,"description":"Series name, or null for single-series funds","example":null},"totalAssets":{"type":"number","description":"Total assets under management (USD)","example":714279299481},"totalLiabilities":{"type":"number","description":"Total liabilities (USD)","example":2206759226},"netAssets":{"type":"number","description":"Net assets / AUM (totalAssets - totalLiabilities, USD)","example":712072540255},"returnMon1":{"type":"number","description":"Return for the most recent month of the quarter (%)","example":2.33},"returnMon2":{"type":"number","description":"Return for the second month of the quarter (%)","example":0.23},"returnMon3":{"type":"number","description":"Return for the third month of the quarter (%)","example":0.05},"totalSales":{"type":"number","description":"Total inflows/sales during the quarter (USD)","example":303112952193.25},"totalRedemptions":{"type":"number","description":"Total outflows/redemptions during the quarter (USD)","example":279346630139.35},"holdingCount":{"type":"integer","description":"Number of holdings in the portfolio","example":503}}}}}}},"400":{"description":"Symbol not found or not a fund (ETF or mutual fund)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/fund/holdings":{"get":{"tags":["ETF/MF"],"summary":"Fund holdings","description":"![Starter](https://img.shields.io/badge/Starter-3b82f6) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns the individual holdings of a fund from its most recent SEC N-PORT filing, with pagination. Holdings are sorted by portfolio weight descending. Where possible, holdings are mapped to their CIK and ticker symbol.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":10},"description":"Fund ticker symbol (ETF or mutual fund)","example":"SPY"},{"in":"query","name":"cik","description":"Fund CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1,"maximum":1000},"description":"Page number (1-indexed)"},{"in":"query","name":"pageSize","schema":{"type":"integer","default":50,"minimum":1,"maximum":1000},"description":"Number of results per page"}],"responses":{"200":{"description":"Paginated ETF holdings","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number (1-indexed)","example":1},"pageSize":{"type":"integer","description":"Number of results per page","example":50},"totalPages":{"type":"integer","description":"Total number of pages","example":10},"totalResults":{"type":"integer","description":"Total number of holdings","example":503},"reportDate":{"type":"string","nullable":true,"description":"Quarter end date of the N-PORT filing","example":"2025-12-31"},"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Holding name","example":"NVIDIA Corp"},"cusip":{"type":"string","description":"CUSIP identifier","example":"67066G104"},"isin":{"type":"string","nullable":true,"description":"ISIN identifier","example":"US67066G1040"},"ticker":{"type":"string","nullable":true,"description":"Ticker symbol as reported in the filing (often null)","example":null},"title":{"type":"string","description":"Security title","example":"NVIDIA Corp"},"valueUsd":{"type":"number","description":"Market value of the holding (USD)","example":55218508208},"pctVal":{"type":"number","description":"Percentage of net assets","example":7.754618397194},"balance":{"type":"number","description":"Number of shares or units held","example":296077792},"units":{"type":"string","description":"Unit type (NS = number of shares, PA = principal amount, etc.)","example":"NS"},"assetCat":{"type":"string","description":"Asset category (EC = equity common, DBT = debt, etc.)","example":"EC"},"issuerCat":{"type":"string","description":"Issuer category (CORP = corporate, SOVN = sovereign, etc.)","example":"CORP"},"country":{"type":"string","description":"Country of issuer (ISO 2-letter code)","example":"US"},"payoffProfile":{"type":"string","description":"Payoff profile (Long, Short, or N/A)","example":"Long"},"fairValueLevel":{"type":"integer","nullable":true,"description":"Fair value hierarchy level (1, 2, or 3)","example":1},"mappedCik":{"type":"integer","nullable":true,"description":"SEC CIK of the held company (mapped by us, null if unmapped)","example":1045810},"mappedSymbol":{"type":"string","nullable":true,"description":"Ticker symbol of the held company (mapped by us, null if unmapped)","example":"NVDA"},"reportDate":{"type":"string","description":"Report date of the N-PORT filing (YYYY-MM-DD)","example":"2025-12-31"}}}}}}}}},"400":{"description":"Symbol not found or not a fund (ETF or mutual fund)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/fund/reverse-lookup":{"get":{"tags":["ETF/MF"],"summary":"Find funds holding a symbol","description":"![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns a paginated list of ETFs and mutual funds that hold the specified symbol in their portfolio, based on the most recent N-PORT filings. Accepts any symbol type — stocks, ETFs, and mutual funds (fund-of-funds structures are supported). Sorted by position value descending.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":10},"description":"Ticker symbol to look up (stock, ETF, or mutual fund)","example":"AAPL"},{"in":"query","name":"cik","description":"Company/Fund CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"page","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1},"description":"Page number (1-indexed)","example":1},{"in":"query","name":"pageSize","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":50},"description":"Results per page","example":50}],"responses":{"200":{"description":"Paginated list of ETFs/funds holding the stock","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number","example":1},"pageSize":{"type":"integer","description":"Results per page","example":50},"totalPages":{"type":"integer","description":"Total number of pages","example":12},"totalResults":{"type":"integer","description":"Total number of funds holding the symbol","example":573},"data":{"type":"array","items":{"type":"object","properties":{"fundName":{"type":"string","description":"Name of the fund","example":"VANGUARD TOTAL STOCK MARKET INDEX FUND"},"fundTicker":{"type":"string","nullable":true,"description":"Ticker symbol of the fund","example":"VTSMX"},"fundCik":{"type":"integer","description":"SEC CIK of the fund","example":36405},"fundSeriesId":{"type":"integer","description":"Series ID of the fund","example":2848},"valueUsd":{"type":"number","description":"Market value of the position (USD)","example":126245057639.88},"pctVal":{"type":"number","description":"Position as percentage of fund net assets","example":6.134426855446},"balance":{"type":"number","description":"Number of shares held","example":464375258},"reportDate":{"type":"string","description":"Report date of the N-PORT filing (YYYY-MM-DD)","example":"2025-12-31"},"fundNetAssets":{"type":"number","nullable":true,"description":"Total net assets of the fund (USD)","example":2057976411077}}}}}}}}},"400":{"description":"Invalid parameters or symbol not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/fund/composition":{"get":{"tags":["ETF/MF"],"summary":"Portfolio composition","description":"![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns a breakdown of the fund's portfolio by asset type, country, issuer type, and top 10 holdings from the most recent N-PORT filing. Useful for understanding portfolio diversification at a glance.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":10},"description":"Fund ticker symbol (ETF or mutual fund)","example":"SPY"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Portfolio composition breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"reportDate":{"type":"string","description":"Report date of the N-PORT filing","example":"2025-12-31"},"assetTypes":{"type":"array","description":"Holdings grouped by asset category","items":{"type":"object","properties":{"category":{"type":"string","description":"Asset category code (EC = equity common, EP = equity preferred, DBT = debt, STIV = short-term investment vehicle, etc.)","example":"EC"},"count":{"type":"integer","description":"Number of holdings in this category","example":498},"weight":{"type":"number","description":"Percentage of net assets","example":99.82}}}},"countries":{"type":"array","description":"Holdings grouped by country of issuer","items":{"type":"object","properties":{"category":{"type":"string","description":"ISO 2-letter country code","example":"US"},"count":{"type":"integer","example":498},"weight":{"type":"number","example":99.52}}}},"issuerTypes":{"type":"array","description":"Holdings grouped by issuer category","items":{"type":"object","properties":{"category":{"type":"string","description":"Issuer category (CORP = corporate, UST = US Treasury, USGA = US Government Agency, etc.)","example":"CORP"},"count":{"type":"integer","example":498},"weight":{"type":"number","example":99.82}}}},"top10":{"type":"array","description":"Top 10 holdings by portfolio weight","items":{"type":"object","properties":{"name":{"type":"string","example":"NVIDIA Corp"},"cusip":{"type":"string","example":"67066G104"},"pctVal":{"type":"number","description":"Percentage of net assets","example":7.75},"valueUsd":{"type":"number","description":"Market value (USD)","example":55218508208},"mappedSymbol":{"type":"string","nullable":true,"description":"Mapped ticker symbol","example":"NVDA"}}}},"top10Weight":{"type":"number","description":"Combined weight of top 10 holdings (%)","example":36.82}}}}}},"400":{"description":"Symbol not found or not a fund (ETF or mutual fund)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/fund/flows":{"get":{"tags":["ETF/MF"],"summary":"Fund flows","description":"![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns quarterly fund flow data with monthly granularity — sales (inflows), redemptions (outflows), reinvestments, and monthly returns. Sourced from SEC N-PORT filings. Most recent quarter first. Historical depth depends on subscription tier.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":10},"description":"Fund ticker symbol (ETF or mutual fund)","example":"SPY"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Quarterly fund flow data (most recent first)","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"reportDate":{"type":"string","example":"2025-12-31"},"returnMon1":{"type":"number","nullable":true,"description":"Month 1 return (%)","example":2.33},"returnMon2":{"type":"number","nullable":true,"description":"Month 2 return (%)","example":0.23},"returnMon3":{"type":"number","nullable":true,"description":"Month 3 return (%)","example":0.05},"flowSalesMon1":{"type":"number","nullable":true,"description":"Month 1 inflows/sales (USD)","example":101037650731.08},"flowReinvestMon1":{"type":"number","nullable":true,"description":"Month 1 reinvestments (USD)","example":0},"flowRedemptionMon1":{"type":"number","nullable":true,"description":"Month 1 outflows/redemptions (USD)","example":93115543379.78},"flowSalesMon2":{"type":"number","nullable":true,"example":98000000000},"flowReinvestMon2":{"type":"number","nullable":true,"example":0},"flowRedemptionMon2":{"type":"number","nullable":true,"example":90000000000},"flowSalesMon3":{"type":"number","nullable":true,"example":104075301462.17},"flowReinvestMon3":{"type":"number","nullable":true,"example":0},"flowRedemptionMon3":{"type":"number","nullable":true,"example":96231086759.57},"netAssets":{"type":"number","description":"Net assets / AUM at quarter end (USD)","example":712072540255},"totalAssets":{"type":"number","description":"Total assets at quarter end (USD)","example":714279299481}}}}}}},"400":{"description":"Symbol not found or not a fund (ETF or mutual fund)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/fund/changes":{"get":{"tags":["ETF/MF"],"summary":"Portfolio changes","description":"![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nCompares the two most recent N-PORT filings and returns holdings that were added, removed, or significantly reweighted (>0.05% portfolio weight change). Useful for tracking portfolio manager decisions and rebalancing activity.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":10},"description":"Fund ticker symbol (ETF or mutual fund)","example":"SPY"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Portfolio changes between the two most recent quarters","content":{"application/json":{"schema":{"type":"object","properties":{"latestDate":{"type":"string","description":"Most recent report date","example":"2025-12-31"},"previousDate":{"type":"string","description":"Previous report date","example":"2025-09-30"},"added":{"type":"array","description":"Holdings newly added to the portfolio","items":{"$ref":"#/components/schemas/EtfChange"}},"removed":{"type":"array","description":"Holdings removed from the portfolio","items":{"$ref":"#/components/schemas/EtfChange"}},"reweighted":{"type":"array","description":"Holdings with significant weight changes (>0.05%)","items":{"$ref":"#/components/schemas/EtfChange"}}}}}}},"400":{"description":"Symbol not found or not a fund (ETF or mutual fund)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/fund/overlap":{"get":{"tags":["ETF/MF"],"summary":"Portfolio overlap","description":"![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nCompares the holdings of two ETFs side by side. Returns overlap statistics (shared holdings count, exclusive counts) and per-holding detail showing weights in both portfolios. Uses CUSIP matching on the most recent N-PORT filing for each fund.\n","parameters":[{"in":"query","name":"symbol1","required":true,"schema":{"type":"string","minLength":1,"maxLength":10},"description":"First Fund ticker symbol (ETF or mutual fund)","example":"VTI"},{"in":"query","name":"symbol2","required":true,"schema":{"type":"string","minLength":1,"maxLength":10},"description":"Second Fund ticker symbol (ETF or mutual fund)","example":"VOO"}],"responses":{"200":{"description":"Portfolio overlap analysis","content":{"application/json":{"schema":{"type":"object","properties":{"symbol1":{"type":"string","example":"VTI"},"symbol2":{"type":"string","example":"VOO"},"reportDate1":{"type":"string","description":"Report date for the first ETF","example":"2025-12-31"},"reportDate2":{"type":"string","description":"Report date for the second ETF","example":"2025-12-31"},"overlapCount":{"type":"integer","description":"Number of holdings in both portfolios","example":498},"onlyIn1Count":{"type":"integer","description":"Holdings only in the first ETF","example":3150},"onlyIn2Count":{"type":"integer","description":"Holdings only in the second ETF","example":5},"overlapWeight1":{"type":"number","description":"Percentage of first fund's portfolio in shared holdings","example":82.5},"overlapWeight2":{"type":"number","description":"Percentage of second fund's portfolio in shared holdings","example":99.8},"holdings":{"type":"array","description":"Per-holding overlap detail (sorted by combined weight)","items":{"type":"object","properties":{"cusip":{"type":"string","example":"67066G104"},"name":{"type":"string","example":"NVIDIA Corp"},"mappedSymbol":{"type":"string","nullable":true,"example":"NVDA"},"weight1":{"type":"number","nullable":true,"description":"Weight in first ETF (%)","example":6.12},"weight2":{"type":"number","nullable":true,"description":"Weight in second ETF (%)","example":7.75},"value1":{"type":"number","nullable":true,"description":"Position value in first ETF (USD)"},"value2":{"type":"number","nullable":true,"description":"Position value in second ETF (USD)"},"overlapStatus":{"type":"string","enum":["both","only_1","only_2"],"description":"Whether the holding appears in both portfolios or only one","example":"both"}}}}}}}}},"400":{"description":"Symbol not found or not a fund (ETF or mutual fund)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/fund/fund-health":{"get":{"tags":["ETF/MF"],"summary":"Fund health assessment","description":"![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nComprehensive fund health assessment sourced from SEC N-CEN and N-PORT filings. Includes tracking quality metrics (for index funds), fair value hierarchy breakdown, liquidity classification, default/arrears status, operational red flags, and service provider summary.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":10},"description":"Fund ticker symbol (ETF or mutual fund)","example":"SPY"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Fund health data","content":{"application/json":{"schema":{"type":"object","properties":{"reportDate":{"type":"string","nullable":true,"example":"2025-06-30"},"ncenRecords":{"type":"array","description":"Annual N-CEN census data with tracking quality and red flags","items":{"type":"object","properties":{"reportDate":{"type":"string","example":"2025-06-30"},"isIndexFund":{"type":"boolean","example":true},"indexReturnDiffBefore":{"type":"number","nullable":true,"description":"Tracking difference before expenses (%)","example":-0.03},"indexReturnDiffAfter":{"type":"number","nullable":true,"description":"Tracking difference after expenses (%)","example":-0.12},"indexStdevBefore":{"type":"number","nullable":true,"description":"Tracking error volatility before expenses","example":0.01},"indexStdevAfter":{"type":"number","nullable":true,"description":"Tracking error volatility after expenses","example":0.02},"isLendingAuthorized":{"type":"boolean"},"didLend":{"type":"boolean"},"isLendingLiquidated":{"type":"boolean"},"hasMaterialWeakness":{"type":"boolean","description":"Internal control material weakness reported"},"hasLegalProceedings":{"type":"boolean"},"hasValuationChanges":{"type":"boolean"},"hasAccountingChanges":{"type":"boolean"},"hasPaymentErrors":{"type":"boolean"}}}},"liquidity":{"type":"array","description":"Holdings by liquidity classification (HLI = Highly Liquid, MLI = Moderately Liquid, LLI = Less Liquid, ILI = Illiquid)","items":{"type":"object","properties":{"category":{"type":"string","enum":["HLI","MLI","LLI","ILI"],"example":"HLI"},"count":{"type":"integer","example":490},"totalValue":{"type":"number","example":700000000000},"totalWeight":{"type":"number","description":"Percentage of portfolio","example":98.3}}}},"fairValue":{"type":"array","description":"Holdings by fair value hierarchy (Level 1 = quoted prices, Level 2 = observable inputs, Level 3 = unobservable/model-based)","items":{"type":"object","properties":{"level":{"type":"integer","enum":[1,2,3],"example":1},"count":{"type":"integer","example":498},"totalValue":{"type":"number","example":710000000000},"totalWeight":{"type":"number","example":99.7}}}},"defaults":{"type":"object","description":"Holdings in default or arrears","properties":{"defaults":{"type":"integer","example":0},"arrears":{"type":"integer","example":0},"total":{"type":"integer","example":0}}},"serviceProviders":{"type":"array","description":"Service providers from the latest N-CEN filing","items":{"type":"object","properties":{"providerRole":{"type":"string","example":"custodian"},"providerName":{"type":"string","example":"STATE STREET BANK AND TRUST COMPANY"},"isAffiliated":{"type":"boolean","example":true}}}}}}}}},"400":{"description":"Symbol not found or no N-CEN data available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/fund/fee-analysis":{"get":{"tags":["ETF/MF"],"summary":"Fee & cost analysis","description":"![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns annual fee and cost data from SEC N-CEN filings — expense limitations, waivers, aggregate brokerage commissions, AUM, in-kind creation/redemption efficiency, and per-broker commission breakdowns. Useful for evaluating total cost of ownership beyond the expense ratio.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":10},"description":"Fund ticker symbol (ETF or mutual fund)","example":"SPY"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Fee and cost analysis data","content":{"application/json":{"schema":{"type":"object","properties":{"feeRecords":{"type":"array","description":"Annual fee data from N-CEN filings (most recent first)","items":{"type":"object","properties":{"reportDate":{"type":"string","example":"2025-06-30"},"isExpenseLimitation":{"type":"boolean","description":"Whether an expense limitation agreement exists"},"isExpenseReducedOrWaived":{"type":"boolean","description":"Whether expenses were reduced or waived"},"isFeesWaivedRecoupable":{"type":"boolean","description":"Whether waived fees can be recouped later"},"monthlyAvgNetAssets":{"type":"number","nullable":true,"description":"Monthly average net assets (USD)","example":550000000000},"aggregateCommission":{"type":"number","nullable":true,"description":"Total brokerage commission paid (USD)","example":3200000},"creationUnitShares":{"type":"number","nullable":true,"description":"Number of shares per creation unit","example":50000},"avgPctPurchasedInKind":{"type":"number","nullable":true,"description":"Average percentage of creations done in-kind (%)","example":95.2},"avgPctRedeemedInKind":{"type":"number","nullable":true,"description":"Average percentage of redemptions done in-kind (%)","example":98.1},"hasLineOfCredit":{"type":"boolean"},"lineOfCreditSize":{"type":"number","nullable":true,"description":"Line of credit size (USD)"}}}},"brokerCommissions":{"type":"array","description":"Per-broker commission breakdown from the latest filing","items":{"type":"object","properties":{"providerName":{"type":"string","example":"GOLDMAN SACHS & CO. LLC"},"commission":{"type":"number","nullable":true,"description":"Commission paid to this broker (USD)","example":850000},"isAffiliated":{"type":"boolean","description":"Whether the broker is affiliated with the fund advisor","example":false}}}}}}}}},"400":{"description":"Symbol not found or no N-CEN data available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/fund/service-providers":{"get":{"tags":["ETF/MF"],"summary":"Service provider history","description":"![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns the full historical roster of service providers (custodians, administrators, auditors, transfer agents, brokers, authorized participants, etc.) from SEC N-CEN filings. Grouped by reporting year with provider role, name, affiliation status, and commission data.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":10},"description":"Fund ticker symbol (ETF or mutual fund)","example":"SPY"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":40,"default":2},"description":"Number of most recent reporting years to return"}],"responses":{"200":{"description":"Service provider history grouped by year","content":{"application/json":{"schema":{"type":"object","properties":{"providersByYear":{"type":"array","description":"Annual provider rosters (most recent first)","items":{"type":"object","properties":{"reportDate":{"type":"string","example":"2025-06-30"},"providers":{"type":"array","items":{"type":"object","properties":{"providerRole":{"type":"string","description":"Role (custodian, admin, transfer-agent, accountant, adviser, sub-adviser, broker, authorized-participant, pricing-service, lending-agent, underwriter)","example":"custodian"},"providerName":{"type":"string","example":"STATE STREET BANK AND TRUST COMPANY"},"isAffiliated":{"type":"boolean","description":"Whether the provider is affiliated with the fund advisor","example":true},"fileNumber":{"type":"string","nullable":true},"crdNumber":{"type":"string","nullable":true},"lei":{"type":"string","nullable":true},"commission":{"type":"number","nullable":true,"description":"Commission paid (USD, broker role only)"}}}}}}}}}}}},"400":{"description":"Symbol not found or no N-CEN data available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/fund/structure":{"get":{"tags":["ETF/MF"],"summary":"Structural analysis","description":"![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nComprehensive structural analysis of a fund's portfolio over time. Includes sector allocation by quarter (SIC-based), industry breakdown, geographic exposure by quarter, balance sheet trajectory, fund classifications (index/active, diversified), short positions, restricted securities, and multi-currency exposure. Sourced from N-PORT holdings joined with SIC classification data and N-CEN census data. Historical depth depends on subscription tier.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":10},"description":"Fund ticker symbol (ETF or mutual fund)","example":"SPY"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Comprehensive structural analysis","content":{"application/json":{"schema":{"type":"object","properties":{"sectorsByQuarter":{"type":"array","description":"Sector allocation by quarter (SIC-based)","items":{"type":"object","properties":{"reportDate":{"type":"string","example":"2025-12-31"},"sectors":{"type":"array","items":{"type":"object","properties":{"sector":{"type":"string","example":"Technology"},"holdingCount":{"type":"integer","example":85},"totalValue":{"type":"number","example":230000000000},"weight":{"type":"number","description":"Percentage of mapped portfolio","example":32.5}}}},"totalHoldings":{"type":"integer","description":"Total holdings in the portfolio"},"mappedHoldings":{"type":"integer","description":"Holdings successfully mapped to SIC sectors"}}}},"industries":{"type":"array","description":"Industry breakdown (latest quarter, SIC-based)","items":{"type":"object","properties":{"industry":{"type":"string","example":"Semiconductor & Related"},"sic":{"type":"string","example":"3674"},"holdingCount":{"type":"integer"},"totalValue":{"type":"number"},"weight":{"type":"number"}}}},"industryGroupsByQuarter":{"type":"array","description":"Industry group allocation by quarter (8 high-value groups derived from SIC codes)","items":{"type":"object","properties":{"reportDate":{"type":"string","example":"2025-12-31"},"groups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Industry group identifier","example":"semiconductor"},"label":{"type":"string","description":"Industry group label","example":"Semiconductors"},"holdingCount":{"type":"integer"},"weight":{"type":"number"}}}}}}},"countriesByQuarter":{"type":"array","description":"Geographic exposure by quarter","items":{"type":"object","properties":{"reportDate":{"type":"string"},"countries":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string","description":"ISO 2-letter country code","example":"US"},"holdingCount":{"type":"integer"},"weight":{"type":"number"}}}}}}},"classifications":{"type":"array","description":"Fund classification from N-CEN (index/active, diversified, in-kind, line of credit)","items":{"type":"object","properties":{"reportDate":{"type":"string"},"isIndexFund":{"type":"boolean"},"isNonDiversified":{"type":"boolean"},"isInKindEtf":{"type":"boolean"},"hasLineOfCredit":{"type":"boolean"}}}},"balanceSheet":{"type":"array","description":"Balance sheet trajectory from N-PORT","items":{"type":"object","properties":{"reportDate":{"type":"string"},"totalAssets":{"type":"number"},"totalLiabilities":{"type":"number"},"netAssets":{"type":"number"}}}},"shortPositions":{"type":"array","description":"Short positions in the portfolio (latest quarter)","items":{"type":"object","properties":{"name":{"type":"string"},"ticker":{"type":"string","nullable":true},"valueUsd":{"type":"number"},"weight":{"type":"number"}}}},"currencies":{"type":"array","description":"Multi-currency exposure (latest quarter)","items":{"type":"object","properties":{"currency":{"type":"string","example":"USD"},"holdingCount":{"type":"integer"},"weight":{"type":"number"}}}}}}}}},"400":{"description":"Symbol not found or not a fund (ETF or mutual fund)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/fund/chart/flows":{"get":{"tags":["ETF/MF"],"summary":"Fund flows chart","description":"![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nChart-ready fund flow data over time. Use `series` for absolute values (Net Flows, Net Assets)\nand `rates` for the normalized flow-to-AUM ratio. Periods are sorted ascending for direct charting.\nNet flows = total sales - total redemptions per quarter.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":10},"description":"Fund ticker symbol (ETF or mutual fund)","example":"SPY"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Series-oriented chart data with periods sorted ascending","content":{"application/json":{"schema":{"type":"object","properties":{"periods":{"type":"array","items":{"type":"string"},"description":"Quarter-end dates sorted ascending","example":["2025-03-31","2025-06-30","2025-09-30","2025-12-31"]},"series":{"type":"array","description":"Absolute value series: Net Flows (sales - redemptions) and Net Assets","items":{"type":"object","properties":{"name":{"type":"string","example":"Net Flows"},"data":{"type":"array","items":{"type":"number","nullable":true},"example":[23766322054,8000000000,15000000000,20000000000]}}}},"rates":{"type":"array","description":"Normalized ratio: Flow-to-AUM as a decimal (0.03 = 3%)","items":{"type":"object","properties":{"name":{"type":"string","example":"Flow-to-AUM"},"data":{"type":"array","items":{"type":"number","nullable":true},"example":[0.0334,0.012,0.021,0.028]}}}}}}}}},"400":{"description":"Symbol not found or not a fund (ETF or mutual fund)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/fund/chart/sectors":{"get":{"tags":["ETF/MF"],"summary":"Sector allocation chart","description":"![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nChart-ready sector allocation over time. Returns one series per top sector (by latest quarter weight),\nwith portfolio weight values for each quarter. Sectors are derived from SIC codes of underlying holdings.\nPeriods sorted ascending. Historical depth depends on subscription tier.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":10},"description":"Fund ticker symbol (ETF or mutual fund)","example":"SPY"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"topN","required":false,"schema":{"type":"integer","minimum":1,"maximum":15,"default":5},"description":"Number of top sectors to include"}],"responses":{"200":{"description":"Sector allocation chart data with periods sorted ascending","content":{"application/json":{"schema":{"type":"object","properties":{"periods":{"type":"array","items":{"type":"string"},"description":"Quarter-end dates sorted ascending","example":["2025-03-31","2025-06-30","2025-09-30","2025-12-31"]},"series":{"type":"array","description":"One series per top sector, with portfolio weight values (%)","items":{"type":"object","properties":{"name":{"type":"string","example":"Technology"},"data":{"type":"array","items":{"type":"number","nullable":true},"example":[31.2,32.5,33.1,32.8]}}}}}}}}},"400":{"description":"Symbol not found or not a fund (ETF or mutual fund)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/fund/chart/countries":{"get":{"tags":["ETF/MF"],"summary":"Country allocation chart","description":"![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nChart-ready geographic allocation over time. Returns one series per top country (by latest quarter weight),\nwith portfolio weight values for each quarter. Countries are ISO 2-letter codes from N-PORT holdings.\nPeriods sorted ascending. Historical depth depends on subscription tier.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":10},"description":"Fund ticker symbol (ETF or mutual fund)","example":"SPY"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"topN","required":false,"schema":{"type":"integer","minimum":1,"maximum":15,"default":5},"description":"Number of top countries to include"}],"responses":{"200":{"description":"Country allocation chart data with periods sorted ascending","content":{"application/json":{"schema":{"type":"object","properties":{"periods":{"type":"array","items":{"type":"string"},"description":"Quarter-end dates sorted ascending","example":["2025-03-31","2025-06-30","2025-09-30","2025-12-31"]},"series":{"type":"array","description":"One series per top country, with portfolio weight values (%)","items":{"type":"object","properties":{"name":{"type":"string","example":"US"},"data":{"type":"array","items":{"type":"number","nullable":true},"example":[98.5,98.7,99.1,99.2]}}}}}}}}},"400":{"description":"Symbol not found or not a fund (ETF or mutual fund)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/fund/chart/industry-groups":{"get":{"tags":["ETF/MF"],"summary":"Industry group allocation chart","description":"![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nChart-ready industry group allocation over time. Returns one series per top industry group (by latest quarter weight),\nwith portfolio weight values for each quarter. Industry groups are StockFit's 8 high-value classifications\n(Semiconductors, Software & SaaS, Pharma & Biotech, Aerospace & Defense, Automotive, Airlines, Oil & Gas, Fintech & Payments)\nderived from SIC codes of underlying holdings. Holdings that don't map to an industry group are excluded.\nPeriods sorted ascending. Historical depth depends on subscription tier.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":10},"description":"Fund ticker symbol (ETF or mutual fund)","example":"QQQ"},{"in":"query","name":"cik","description":"Fund CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"topN","required":false,"schema":{"type":"integer","minimum":1,"maximum":8,"default":5},"description":"Number of top industry groups to include (max 8)"}],"responses":{"200":{"description":"Industry group allocation chart data with periods sorted ascending","content":{"application/json":{"schema":{"type":"object","properties":{"periods":{"type":"array","items":{"type":"string"},"description":"Quarter-end dates sorted ascending","example":["2025-03-31","2025-06-30","2025-09-30","2025-12-31"]},"series":{"type":"array","description":"One series per industry group. Each entry has a `name` and `data` array parallel to `periods`.","items":{"type":"object","properties":{"name":{"type":"string","description":"Industry group label","example":"Semiconductors"},"data":{"type":"array","items":{"type":"number","nullable":true},"description":"Portfolio weight percentage per period","example":[18.5,19.2,20.1,19.8]}}}}}}}}},"400":{"description":"Symbol not found or not a fund (ETF or mutual fund)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/fund/exposure-model":{"get":{"tags":["ETF/MF"],"summary":"Full audit-grade ETF exposure model (lazy-generated)","description":"![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\n## 🔒 Audit-grade by construction\n\n**Every claim in this response — except peer identity — is defensible in an IC meeting or audit.** Most competing \"AI fund classification\" APIs return plausible-sounding prose you cannot verify. This endpoint is different. For each claim you get:\n\n- 🔗 a clickable URL to the exact authoritative document (SEC EDGAR prospectus, N-CSR shareholder report, N-CEN census),\n- 📄 the document section the claim is drawn from (e.g., `Principal Investment Strategies`, `Principal Investment Risks`, `Expense Example`, `Portfolio Manager Commentary`),\n- 💬 a **verbatim quote** from that section (20–400 characters, copied word-for-word),\n- ✅ **machine-verified at generation time** — we fetch the filing, strip HTML, and confirm the quote literally appears in the document before we store it. Fabricated or paraphrased quotes are rejected and the model is regenerated.\n\nAn analyst can click a URL, jump to the section, `Ctrl-F` the quote, and have the source paragraph in front of them in ten seconds. No more \"trust me, the AI read the prospectus.\"\n\n## What's in the model\n\nSummary, mandate (including benchmark), portfolio construction, exposures (risk drivers + key holdings/buckets), implementation (replication + derivatives + securities lending), distributions & taxes, costs & leakage, sensitivities (macro/market/mechanics), use cases & failure modes (best/bad/failure), and peers (primary + secondary + comparison framework).\n\nPeers are an analytical judgment (the ETF competitive landscape rarely names itself verbatim in a prospectus), so peers do not carry sources. Every other section and array item does.\n\n## Source document types\n\nCitations draw from: `prospectus` (485BPOS / 497 / N-1A), `N-CSR` / `N-CSRS` (annual / semi-annual shareholder reports), `N-CEN` (annual fund census), `N-PORT` (quarterly holdings), and `issuer-website`.\n\n## Two possible response shapes\n\n### ✅ `200 OK` — model is ready\n\nReturns the full `ExposureModel` JSON. Stable and safe to cache client-side.\n\n### ⏳ `202 Accepted` — model is being generated\n\nThe model for this fund has never been built. A background job has been queued (or one was already in flight).\n\n**Generation takes a few minutes.** The job fetches the fund's latest prospectus, N-CSR, and N-CEN directly from SEC EDGAR, passes them to the AI along with strict citation requirements, verifies every quote against the filing text, and writes the result.\n\n**Poll this same endpoint** with the same `symbol` — once the job completes you will start receiving the `200` response. A reasonable poll interval is every 30 seconds.\n\n```json\n{\n  \"status\": \"generating\",\n  \"jobId\": \"64abfe1234567890abcdef12\",\n  \"message\": \"Generating exposure model — this can take a few minutes. Call this endpoint again to retrieve the result.\"\n}\n```\n\n## Deduplication\n\nIf a generation job is already in flight for this fund — regardless of which account queued it — this endpoint returns the existing `jobId`. You will never queue two generations for the same fund series.\n\n## Cost\n\nGeneration runs server-side and does not count against your API request budget beyond the call to this endpoint.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":10},"description":"Fund ticker symbol (ETF or mutual fund)","example":"VTI"},{"in":"query","name":"cik","description":"Fund CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":1100663}],"responses":{"200":{"description":"Model is ready. Full exposure model JSON with per-claim SEC-filing citations.","content":{"application/json":{"schema":{"type":"object","description":"Full AI-classified ETF exposure model. Every section and item (except peers) carries a `sources` array of `{url, source, publisher, section, quote}` citations machine-verified against the embedded filing text at generation time.","properties":{"summary":{"type":"object","description":"Primary exposure, strategy type, who-it-is-for, what-it-is-not. Has sources[]."},"mandate":{"type":"object","description":"Investment objective, benchmark, universe (asset class / geography / instruments), constraints. Has sources[]."},"portfolioConstruction":{"type":"object","description":"Selection rules, weighting, rebalancing frequency + triggers, concentration notes. Has sources[]."},"exposures":{"type":"object","description":"Risk drivers, factor tilts, key holdings or buckets (each with own sources[]), KPI mappings. Has sources[]."},"implementation":{"type":"object","description":"Replication method, derivatives usage, securities lending, liquidity notes. Has sources[]."},"distributionsAndTaxes":{"type":"object","description":"Distribution profile, tax notes, capital gains risk. Has sources[]."},"costsAndLeakage":{"type":"object","description":"Expense ratio notes, implicit costs, tracking difference drivers. Has sources[]."},"sensitivities":{"type":"object","description":"Macro, market, and portfolio-mechanics sensitivities. Has sources[]."},"useCasesAndFailureModes":{"type":"object","description":"bestUseCases, badUseCases, failureModes — each an array of {text, sources[]}."},"peers":{"type":"object","description":"primary (2-5) + secondary (0-6) + comparisonFramework. Peers do NOT carry sources — analytical judgment."},"provenance":{"type":"object","description":"Whole-model confidence + deduped source kinds that appear across citations.","properties":{"confidence":{"type":"string","enum":["low","medium","high"]},"sources":{"type":"array","items":{"type":"string","enum":["prospectus","N-CSR","N-CSRS","N-CEN","N-PORT","issuer-website"]}}}}}}}}},"202":{"description":"Model generation has been queued (or one is already in flight). Poll the same URL for the finished result.","content":{"application/json":{"schema":{"type":"object","required":["status","jobId","message"],"properties":{"status":{"type":"string","enum":["generating"],"example":"generating"},"jobId":{"type":"string","description":"ID of the background job","example":"64abfe1234567890abcdef12"},"message":{"type":"string","example":"Generating exposure model — this can take a few minutes. Call this endpoint again to retrieve the result."}}}}}},"400":{"description":"Invalid parameters or fund not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/fund/fees":{"get":{"tags":["ETF/MF"],"summary":"Fund fee schedule","description":"![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns paginated fee schedule data from SEC N-1A prospectus filings.\nIncludes management fees, 12b-1 fees, expense ratios, fee waivers, sales charges,\nand redemption fees per share class. Most recent filings first.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":10},"description":"Fund ticker symbol (ETF or mutual fund)","example":"SPY"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"page","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1},"description":"Page number (1-indexed)"},{"in":"query","name":"pageSize","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"description":"Results per page"}],"responses":{"200":{"description":"Paginated fund fee schedule data","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number (1-indexed)","example":1},"pageSize":{"type":"integer","description":"Results per page","example":10},"totalPages":{"type":"integer","description":"Total number of pages","example":3},"totalResults":{"type":"integer","description":"Total number of fee records","example":25},"data":{"type":"array","items":{"type":"object","properties":{"filedDate":{"type":"string","description":"SEC filing date (YYYY-MM-DD)","example":"2025-10-15"},"accessionNumber":{"type":"string","description":"SEC accession number","example":"0001234567-25-000123"},"symbol":{"type":"string","nullable":true,"description":"Share class ticker symbol (e.g. VTI for ETF shares, VTSMX for Investor shares)","example":"VTI"},"managementFee":{"type":"number","nullable":true,"description":"Management fee (%)","example":0.03},"distribution12b1Fee":{"type":"number","nullable":true,"description":"12b-1 distribution fee (%)","example":0},"otherExpenses":{"type":"number","nullable":true,"description":"Other expenses (%)","example":0.01},"acquiredFundFees":{"type":"number","nullable":true,"description":"Acquired fund fees and expenses (%)","example":0},"totalExpenseRatio":{"type":"number","nullable":true,"description":"Gross total expense ratio (%)","example":0.09},"feeWaiver":{"type":"number","nullable":true,"description":"Fee waiver/reimbursement amount (%)","example":-0.06},"netExpenseRatio":{"type":"number","nullable":true,"description":"Net expense ratio after waivers (%)","example":0.03},"maxSalesChargePurchase":{"type":"number","nullable":true,"description":"Maximum front-end sales charge on purchases (%)","example":0},"maxDeferredSalesCharge":{"type":"number","nullable":true,"description":"Maximum deferred sales charge (%)","example":0},"redemptionFee":{"type":"number","nullable":true,"description":"Redemption fee (%)","example":0}}}}}}}}},"400":{"description":"Symbol not found or not a fund (ETF or mutual fund)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/fund/performance":{"get":{"tags":["ETF/MF"],"summary":"Fund performance data","description":"![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns paginated fund performance data from SEC N-CSR (annual/semi-annual shareholder report) filings.\nIncludes annualized returns (1yr, 5yr, 10yr, since inception), expense ratio, net assets,\nportfolio turnover, and holdings count per share class. Most recent periods first.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":10},"description":"Fund ticker symbol (ETF or mutual fund)","example":"SPY"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"page","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1},"description":"Page number (1-indexed)"},{"in":"query","name":"pageSize","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"description":"Results per page"}],"responses":{"200":{"description":"Paginated fund performance data","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number (1-indexed)","example":1},"pageSize":{"type":"integer","description":"Results per page","example":10},"totalPages":{"type":"integer","description":"Total number of pages","example":5},"totalResults":{"type":"integer","description":"Total number of performance records","example":48},"data":{"type":"array","items":{"type":"object","properties":{"periodEndDate":{"type":"string","description":"Reporting period end date (YYYY-MM-DD)","example":"2025-09-30"},"formType":{"type":"string","description":"SEC form type (N-CSR or N-CSRS)","example":"N-CSR"},"filedDate":{"type":"string","description":"SEC filing date (YYYY-MM-DD)","example":"2025-12-01"},"symbol":{"type":"string","nullable":true,"description":"Share class ticker symbol","example":"VTI"},"shareClassName":{"type":"string","nullable":true,"description":"Share class name","example":"Investor Shares"},"expenseRatio":{"type":"number","nullable":true,"description":"Expense ratio (%)","example":0.03},"expensesPaid":{"type":"number","nullable":true,"description":"Expenses paid per $1,000 invested (USD)","example":0.15},"advisoryFeesPaid":{"type":"number","nullable":true,"description":"Advisory fees paid (USD)","example":1250000000},"netAssets":{"type":"number","nullable":true,"description":"Net assets / AUM at period end (USD)","example":712072540255},"return1yr":{"type":"number","nullable":true,"description":"1-year annualized return (%)","example":35.72},"return5yr":{"type":"number","nullable":true,"description":"5-year annualized return (%)","example":15.48},"return10yr":{"type":"number","nullable":true,"description":"10-year annualized return (%)","example":12.91},"returnSinceInception":{"type":"number","nullable":true,"description":"Annualized return since fund inception (%)","example":14.23},"inceptionDate":{"type":"string","nullable":true,"description":"Fund inception date (YYYY-MM-DD)","example":"2010-09-07"},"portfolioTurnoverRate":{"type":"number","nullable":true,"description":"Portfolio turnover rate (%)","example":4},"holdingsCount":{"type":"integer","nullable":true,"description":"Number of holdings in the portfolio","example":503}}}}}}}}},"400":{"description":"Symbol not found or not a fund (ETF or mutual fund)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/fund/chart/performance":{"get":{"tags":["ETF/MF"],"summary":"Fund performance chart","description":"![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nChart-ready fund performance data over time from SEC N-CSR filings.\nUse `series` for absolute values (Net Assets, Holdings Count)\nand `rates` for percentage metrics (1-Year Return, Expense Ratio, Turnover Rate).\nPeriods are sorted ascending for direct charting. Historical depth depends on subscription tier.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":10},"description":"Fund ticker symbol (ETF or mutual fund)","example":"SPY"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Series-oriented chart data with periods sorted ascending","content":{"application/json":{"schema":{"type":"object","properties":{"periods":{"type":"array","items":{"type":"string"},"description":"Period end dates sorted ascending","example":["2023-09-30","2024-03-31","2024-09-30","2025-03-31"]},"series":{"type":"array","description":"Absolute value series: Net Assets (USD) and Holdings Count","items":{"type":"object","properties":{"name":{"type":"string","example":"Net Assets"},"data":{"type":"array","items":{"type":"number","nullable":true},"example":[600000000000,650000000000,680000000000,712072540255]}}}},"rates":{"type":"array","description":"Percentage metrics: 1-Year Return (%), Expense Ratio (%), Turnover Rate (%)","items":{"type":"object","properties":{"name":{"type":"string","example":"1-Year Return"},"data":{"type":"array","items":{"type":"number","nullable":true},"example":[20.15,28.34,32.1,35.72]}}}}}}}}},"400":{"description":"Symbol not found or not a fund (ETF or mutual fund)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/insider-transactions":{"get":{"tags":["Insider Transactions"],"summary":"Insider transactions","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns insider transactions (Form 4/Form 5) for officers and directors. Transactions are deduplicated across co-owners and filings — each physical trade appears once, prioritizing the most senior filer (officer > director > 10% owner).\n\nExcludes trades with price >= $100,000 (SEC data entry errors). Form 5/5A amendments are excluded when a corresponding Form 4/4A exists for the same trade.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"filter","schema":{"type":"string","default":"all"},"description":"Transaction filter:\n- `all` — All transactions by officers or directors\n- `buys` — Acquisitions by officers or directors\n- `sells` — Dispositions by officers or directors\n- `significant` — Open-market purchases (P) and sales (S) only\n- `executives` — Officers only (excludes non-officer directors)\n- `voluntary-sells` — Sales not paired with an option exercise in the same filing\n"},{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1,"maximum":1000},"description":"Page number (1-indexed)"},{"in":"query","name":"pageSize","schema":{"type":"integer","default":50,"minimum":1,"maximum":100},"description":"Number of results per page"},{"in":"query","name":"startDate","schema":{"type":"string","format":"date"},"description":"Filter transactions on or after this date (YYYY-MM-DD)"},{"in":"query","name":"endDate","schema":{"type":"string","format":"date"},"description":"Filter transactions on or before this date (YYYY-MM-DD)"}],"responses":{"200":{"description":"Paginated insider transactions","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer","example":1,"description":"Current page number (1-indexed)"},"pageSize":{"type":"integer","example":50,"description":"Number of results per page"},"totalPages":{"type":"integer","example":4,"description":"Total number of pages"},"totalResults":{"type":"integer","example":167,"description":"Total matching records"},"data":{"type":"array","items":{"type":"object","properties":{"ownerName":{"type":"string","description":"Name of the insider","example":"LEVINSON ARTHUR D"},"ownerCik":{"type":"integer","nullable":true,"description":"CIK of the insider","example":1214128},"isDirector":{"type":"boolean","example":true},"isOfficer":{"type":"boolean","example":false},"isTenPercentOwner":{"type":"boolean","example":false},"officerTitle":{"type":"string","nullable":true},"documentType":{"type":"string","nullable":true,"description":"SEC filing form type:\n\n| Type | Description |\n|------|-------------|\n| 4 | Statement of changes in beneficial ownership |\n| 4/A | Amendment to Form 4 |\n| 5 | Annual statement of changes (deferred transactions) |\n| 5/A | Amendment to Form 5 |\n","example":"4"},"securityTitle":{"type":"string","nullable":true,"description":"Title of the security transacted","example":"Common Stock"},"transactionDate":{"type":"string","nullable":true,"description":"Transaction date (YYYY-MM-DD)","example":"2026-02-26"},"transactionCode":{"type":"string","nullable":true,"description":"SEC Form 4 transaction code:\n\n| Code | Description |\n|------|-------------|\n| P | Open-market or private purchase |\n| S | Open-market or private sale |\n| A | Grant or award |\n| M | Exercise or conversion of derivative |\n| C | Conversion of derivative security |\n| G | Gift |\n| F | Payment of exercise price or tax liability by delivering securities |\n| J | Other acquisition or disposition (see filing) |\n| K | Equity swap or similar instrument |\n| D | Disposition to the issuer |\n| W | Acquisition or disposition by will or laws of descent |\n| Z | Deposit into or withdrawal from voting trust |\n| U | Disposition due to tender of shares in change of control |\n| I | Discretionary transaction (Rule 16b-3(f)) |\n| L | Small acquisition (Rule 16a-6) |\n| V | Transaction voluntarily reported earlier than required |\n| H | Expiration of long derivative position |\n| E | Expiration of short derivative position |\n| O | Exercise of out-of-the-money derivative |\n| X | Exercise of in-the-money derivative |\n","example":"G"},"shares":{"type":"number","nullable":true,"description":"Number of shares transacted","example":1113},"pricePerShare":{"type":"number","nullable":true,"description":"Price per share","example":0},"acquiredDisposed":{"type":"string","nullable":true,"description":"| Value | Description |\n|-------|-------------|\n| A | Acquired |\n| D | Disposed |\n","example":"D"},"sharesAfter":{"type":"number","nullable":true,"description":"Shares owned after the transaction","example":4069576},"directIndirect":{"type":"string","nullable":true,"description":"| Value | Description |\n|-------|-------------|\n| D | Direct ownership |\n| I | Indirect ownership (held by trust, family member, etc.) |\n","example":"D"},"isDerivative":{"type":"boolean","description":"Whether this is a derivative transaction","example":false},"exercisePrice":{"type":"number","nullable":true,"description":"Exercise price for derivative transactions"},"exerciseDate":{"type":"string","nullable":true,"description":"Exercise date (YYYY-MM-DD)"},"expirationDate":{"type":"string","nullable":true,"description":"Expiration date for derivative securities (YYYY-MM-DD)"},"underlyingSecurity":{"type":"string","nullable":true,"description":"Title of the underlying security for derivatives"},"underlyingShares":{"type":"number","nullable":true,"description":"Number of underlying shares for derivatives"},"accessionNumber":{"type":"string","nullable":true,"description":"SEC accession number","example":"0001214128-26-000004"},"filingUrl":{"type":"string","nullable":true,"description":"URL to the SEC filing"},"transactionValue":{"type":"number","nullable":true,"description":"Total transaction value (shares × price per share)","example":245678},"filingDate":{"type":"string","nullable":true,"description":"Date the filing was submitted to the SEC (YYYY-MM-DD)","example":"2026-02-28"}}}}}}}}},"400":{"description":"Invalid parameters or company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/insider-transactions/chart":{"get":{"tags":["Insider Transactions"],"summary":"Insider transactions chart","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns monthly aggregated insider transaction data for charting. Non-derivative transactions only.\nTransactions are deduplicated across co-owners — each physical trade counted once, prioritizing the most senior filer (officer > director > 10% owner).\nExcludes trades with price >= $100,000 (SEC data entry errors). Form 5/5A amendments are excluded when a corresponding Form 4/4A exists for the same trade.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"filter","schema":{"type":"string","default":"all"},"description":"Transaction filter:\n- `all` — All transactions by officers or directors\n- `buys` — Acquisitions by officers or directors\n- `sells` — Dispositions by officers or directors\n- `significant` — Open-market purchases (P) and sales (S) only\n- `executives` — Officers only (excludes non-officer directors)\n- `voluntary-sells` — Sales not paired with an option exercise in the same filing\n"},{"in":"query","name":"startDate","schema":{"type":"string","format":"date"},"description":"Filter transactions on or after this date (YYYY-MM-DD)"},{"in":"query","name":"endDate","schema":{"type":"string","format":"date"},"description":"Filter transactions on or before this date (YYYY-MM-DD)"}],"responses":{"200":{"description":"Series-oriented chart data with continuous monthly periods (no gaps)","content":{"application/json":{"schema":{"type":"object","properties":{"periods":{"type":"array","items":{"type":"string"},"description":"Continuous month labels sorted ascending (YYYY-MM). Months with no activity are included as zero-filled entries.","example":["2024-10","2024-11","2024-12","2025-01"]},"series":{"type":"array","description":"Share volume series. Each entry has a `name` and a `data` array parallel to `periods`.","items":{"type":"object","properties":{"name":{"type":"string","description":"Series name","example":"Acquired"},"data":{"type":"array","items":{"type":"number"},"description":"Share counts per period (0 when no activity)","example":[316934,0,0,50000]}}}},"counts":{"type":"array","description":"Transaction count series. Same structure as `series` but counts transactions instead of shares.","items":{"type":"object","properties":{"name":{"type":"string","example":"Acquired"},"data":{"type":"array","items":{"type":"integer"},"example":[4,0,0,2]}}}}}}}}},"400":{"description":"Invalid parameters or company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/insider-transactions/summary":{"get":{"tags":["Insider Transactions"],"summary":"Insider trading summary","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns aggregated insider trading statistics for the last 3, 6, and 12 months.\nOnly includes significant open-market trades (purchase and sale codes P/S) by officers and directors.\nTransactions are deduplicated across co-owners — each physical trade counted once, prioritizing the most senior filer (officer > director > 10% owner).\nExcludes trades with price >= $100,000 (SEC data entry errors) and Form 5 amendments when a Form 4 exists for the same trade.\n\n`uniqueBuyers` and `uniqueSellers` count distinct insiders — cluster buying (multiple insiders buying) is a stronger signal than one person buying repeatedly.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Insider trading summary by time period","content":{"application/json":{"schema":{"type":"object","properties":{"3months":{"type":"object","description":"Last 3 months","properties":{"buyCount":{"type":"integer","description":"Number of purchase transactions","example":4},"sellCount":{"type":"integer","description":"Number of sale transactions","example":12},"buyShares":{"type":"number","description":"Total shares purchased","example":50000},"sellShares":{"type":"number","description":"Total shares sold","example":890000},"buyValue":{"type":"number","description":"Total value of purchases (USD)","example":2500000},"sellValue":{"type":"number","description":"Total value of sales (USD)","example":67000000},"netShares":{"type":"number","description":"Net shares (buyShares - sellShares)","example":-840000},"uniqueBuyers":{"type":"integer","description":"Number of distinct insiders who purchased","example":2},"uniqueSellers":{"type":"integer","description":"Number of distinct insiders who sold","example":5}}},"6months":{"type":"object","description":"Last 6 months","properties":{"buyCount":{"type":"integer","description":"Number of purchase transactions"},"sellCount":{"type":"integer","description":"Number of sale transactions"},"buyShares":{"type":"number","description":"Total shares purchased"},"sellShares":{"type":"number","description":"Total shares sold"},"buyValue":{"type":"number","description":"Total value of purchases (USD)"},"sellValue":{"type":"number","description":"Total value of sales (USD)"},"netShares":{"type":"number","description":"Net shares (buyShares - sellShares)"},"uniqueBuyers":{"type":"integer","description":"Number of distinct insiders who purchased"},"uniqueSellers":{"type":"integer","description":"Number of distinct insiders who sold"}}},"12months":{"type":"object","description":"Last 12 months","properties":{"buyCount":{"type":"integer","description":"Number of purchase transactions"},"sellCount":{"type":"integer","description":"Number of sale transactions"},"buyShares":{"type":"number","description":"Total shares purchased"},"sellShares":{"type":"number","description":"Total shares sold"},"buyValue":{"type":"number","description":"Total value of purchases (USD)"},"sellValue":{"type":"number","description":"Total value of sales (USD)"},"netShares":{"type":"number","description":"Net shares (buyShares - sellShares)"},"uniqueBuyers":{"type":"integer","description":"Number of distinct insiders who purchased"},"uniqueSellers":{"type":"integer","description":"Number of distinct insiders who sold"}}}}}}}},"400":{"description":"Invalid parameters or company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/insider-transactions/roster":{"get":{"tags":["Insider Transactions"],"summary":"Insider roster","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns all known insiders (officers and directors) for a company, with their most recent transaction date, total transaction count, and last reported share position. Derived from Form 3/4/5 filings.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"List of insiders ordered by most recent transaction","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"ownerName":{"type":"string","description":"Name of the insider","example":"COOK TIMOTHY D"},"ownerCik":{"type":"integer","nullable":true,"description":"CIK of the insider","example":1214156},"isOfficer":{"type":"boolean","description":"Whether this person is (or was) an officer","example":true},"isDirector":{"type":"boolean","description":"Whether this person is (or was) a director","example":false},"officerTitle":{"type":"string","nullable":true,"description":"Most recent officer title from filings","example":"Chief Executive Officer"},"lastTransactionDate":{"type":"string","nullable":true,"description":"Date of the most recent transaction (YYYY-MM-DD)","example":"2025-08-15"},"transactionCount":{"type":"integer","description":"Total number of transactions filed","example":24},"lastReportedShares":{"type":"number","nullable":true,"description":"Share position after the most recent non-derivative transaction","example":3280557}}}}}}},"400":{"description":"Invalid parameters or company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/insider-transactions/by-insider":{"get":{"tags":["Insider Transactions"],"summary":"Transactions by insider","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns all transactions for a specific insider identified by their CIK. Useful for tracking a particular officer's or director's trading history.\nExcludes trades with price >= $100,000 (SEC data entry errors). Form 5/5A amendments are excluded when a corresponding Form 4/4A exists for the same trade.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"ownerCik","required":true,"schema":{"type":"integer"},"description":"CIK of the insider (from the roster or main transactions endpoint)","example":1214156},{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1,"maximum":1000},"description":"Page number (1-indexed)"},{"in":"query","name":"pageSize","schema":{"type":"integer","default":50,"minimum":1,"maximum":100},"description":"Number of results per page"},{"in":"query","name":"startDate","schema":{"type":"string","format":"date"},"description":"Filter transactions on or after this date (YYYY-MM-DD)"},{"in":"query","name":"endDate","schema":{"type":"string","format":"date"},"description":"Filter transactions on or before this date (YYYY-MM-DD)"}],"responses":{"200":{"description":"Paginated insider transactions for the specified person","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer","example":1,"description":"Current page number (1-indexed)"},"pageSize":{"type":"integer","example":50,"description":"Number of results per page"},"totalPages":{"type":"integer","example":1,"description":"Total number of pages"},"totalResults":{"type":"integer","example":24,"description":"Total matching records"},"data":{"type":"array","items":{"type":"object","properties":{"ownerName":{"type":"string","description":"Name of the insider","example":"COOK TIMOTHY D"},"ownerCik":{"type":"integer","nullable":true,"description":"CIK of the insider","example":1214156},"isDirector":{"type":"boolean","example":false},"isOfficer":{"type":"boolean","example":true},"isTenPercentOwner":{"type":"boolean","example":false},"officerTitle":{"type":"string","nullable":true,"description":"Officer title at time of filing","example":"Chief Executive Officer"},"documentType":{"type":"string","nullable":true,"description":"SEC filing form type:\n\n| Type | Description |\n|------|-------------|\n| 4 | Statement of changes in beneficial ownership |\n| 4/A | Amendment to Form 4 |\n| 5 | Annual statement of changes (deferred transactions) |\n| 5/A | Amendment to Form 5 |\n","example":"4"},"securityTitle":{"type":"string","nullable":true,"description":"Title of the security transacted","example":"Common Stock"},"transactionDate":{"type":"string","nullable":true,"description":"Transaction date (YYYY-MM-DD)","example":"2025-08-15"},"transactionCode":{"type":"string","nullable":true,"description":"SEC Form 4 transaction code:\n\n| Code | Description |\n|------|-------------|\n| P | Open-market or private purchase |\n| S | Open-market or private sale |\n| A | Grant or award |\n| M | Exercise or conversion of derivative |\n| C | Conversion of derivative security |\n| G | Gift |\n| F | Payment of exercise price or tax liability by delivering securities |\n| J | Other acquisition or disposition (see filing) |\n| K | Equity swap or similar instrument |\n| D | Disposition to the issuer |\n| W | Acquisition or disposition by will or laws of descent |\n| Z | Deposit into or withdrawal from voting trust |\n| U | Disposition due to tender of shares in change of control |\n| I | Discretionary transaction (Rule 16b-3(f)) |\n| L | Small acquisition (Rule 16a-6) |\n| V | Transaction voluntarily reported earlier than required |\n| H | Expiration of long derivative position |\n| E | Expiration of short derivative position |\n| O | Exercise of out-of-the-money derivative |\n| X | Exercise of in-the-money derivative |\n","example":"S"},"shares":{"type":"number","nullable":true,"description":"Number of shares transacted","example":75000},"pricePerShare":{"type":"number","nullable":true,"description":"Price per share","example":198.73},"acquiredDisposed":{"type":"string","nullable":true,"description":"| Value | Description |\n|-------|-------------|\n| A | Acquired |\n| D | Disposed |\n","example":"D"},"sharesAfter":{"type":"number","nullable":true,"description":"Shares owned after the transaction","example":3205557},"directIndirect":{"type":"string","nullable":true,"description":"| Value | Description |\n|-------|-------------|\n| D | Direct ownership |\n| I | Indirect ownership (held by trust, family member, etc.) |\n","example":"D"},"isDerivative":{"type":"boolean","description":"Whether this is a derivative transaction","example":false},"exercisePrice":{"type":"number","nullable":true,"description":"Exercise price for derivative transactions"},"exerciseDate":{"type":"string","nullable":true,"description":"Exercise date (YYYY-MM-DD)"},"expirationDate":{"type":"string","nullable":true,"description":"Expiration date for derivative securities (YYYY-MM-DD)"},"underlyingSecurity":{"type":"string","nullable":true,"description":"Title of the underlying security for derivatives"},"underlyingShares":{"type":"number","nullable":true,"description":"Number of underlying shares for derivatives"},"accessionNumber":{"type":"string","nullable":true,"description":"SEC accession number","example":"0001214156-25-000012"},"filingUrl":{"type":"string","nullable":true,"description":"URL to the SEC filing"},"transactionValue":{"type":"number","nullable":true,"description":"Total transaction value (shares × price per share)","example":14904750},"filingDate":{"type":"string","nullable":true,"description":"Date the filing was submitted to the SEC (YYYY-MM-DD)","example":"2025-08-18"}}}}}}}}},"400":{"description":"Invalid parameters or company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/ownership/share-classes":{"get":{"tags":["Ownership"],"summary":"Share classes","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns share class information including outstanding and authorized shares, extracted from SEC filings.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"List of share classes ordered by shares outstanding (descending)","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"className":{"type":"string","description":"Name of the share class","example":"Class A"},"classMember":{"type":"string","description":"XBRL class member identifier","example":"us-gaap:CommonClassAMember"},"sharesOutstanding":{"type":"number","nullable":true,"description":"Number of shares outstanding","example":307955000},"sharesAuthorized":{"type":"number","nullable":true,"description":"Number of shares authorized","example":1500000000},"periodEnd":{"type":"string","nullable":true,"description":"Period end date (YYYY-MM-DD)","example":"2025-12-31"},"year":{"type":"integer","nullable":true,"description":"Fiscal year","example":2025},"fp":{"type":"string","nullable":true,"description":"Filing period (FY, Q1, Q2, Q3)","example":"FY"}}}}}}},"400":{"description":"Invalid parameters or company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/ownership/beneficial-owners":{"get":{"tags":["Ownership"],"summary":"Beneficial owners","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns beneficial owners (5%+ shareholders) from SEC Schedule 13D/13G filings. Shows the most recent report per owner, ordered by ownership percentage. Includes change tracking vs previous filing and insider cross-referencing.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"List of beneficial owners ordered by ownership percentage (descending)","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"reportingPersonName":{"type":"string","description":"Name of the beneficial owner","example":"The Vanguard Group"},"reportingPersonCik":{"type":"integer","nullable":true,"description":"CIK of the reporting person"},"activist":{"type":"boolean","description":"Whether this is an activist investor (Schedule 13D filer)","example":false},"amendment":{"type":"boolean","description":"Whether this is an amended filing","example":true},"percentOfClass":{"type":"number","nullable":true,"description":"Percentage of share class owned","example":9.47},"aggregateAmountOwned":{"type":"number","nullable":true,"description":"Total shares owned","example":1415826462},"soleVotingPower":{"type":"number","nullable":true,"description":"Shares with sole voting power","example":0},"sharedVotingPower":{"type":"number","nullable":true,"description":"Shares with shared voting power","example":19800347},"soleDispositivePower":{"type":"number","nullable":true,"description":"Shares with sole dispositive power","example":1343278627},"sharedDispositivePower":{"type":"number","nullable":true,"description":"Shares with shared dispositive power","example":72547835},"typeOfReportingPerson":{"type":"string","nullable":true,"description":"SEC reporting person type code:\n\n| Code | Meaning |\n|------|---------|\n| IA | Investment Adviser |\n| BD | Broker or Dealer |\n| BK | Bank |\n| IC | Insurance Company |\n| IV | Investment Company |\n| EP | Employee Benefit Plan or Endowment Fund |\n| HC | Holding Company |\n| SA | Savings Association |\n| CP | Corporation |\n| PN | Partnership |\n| IN | Individual |\n| OO | Other |\n","example":"IA"},"securityClassTitle":{"type":"string","nullable":true,"description":"Title of the security class","example":"Common Stock"},"reportDate":{"type":"string","nullable":true,"description":"Filing report date (YYYY-MM-DD)","example":"2025-07-29"},"accessionNumber":{"type":"string","nullable":true,"description":"SEC accession number","example":"0000932471-25-000778"},"filingUrl":{"type":"string","nullable":true,"description":"URL to the SEC filing"},"filingType":{"type":"string","nullable":true,"description":"SEC form type (13G, 13D, etc.)","example":"13G"},"prevPercentOfClass":{"type":"number","nullable":true,"description":"Previous filing ownership percentage for change tracking"},"purposeOfTransaction":{"type":"string","nullable":true,"description":"Stated purpose of the transaction"},"intent":{"type":"string","nullable":true,"description":"Investor intent classified from the filing's stated purpose (Item 4):\n\n| Value | Meaning |\n|-------|---------|\n| active | Activist intent — seeks board seats, proxy fights, corporate changes, or sale of the company |\n| strategic | Passive/strategic — investment purposes only, no current plans to influence management |\n"},"isInsider":{"type":"boolean","description":"Whether this owner is also a company officer or director","example":false},"insiderTitle":{"type":"string","nullable":true,"description":"Officer title if the owner is also an insider"}}}}}}},"400":{"description":"Invalid parameters or company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/ownership/institutional-holders":{"get":{"tags":["Ownership"],"summary":"Institutional holders","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns institutional holders from SEC 13F filings, aggregated by manager for a given reporting quarter and paired with the prior quarter for change tracking. Ownership percentage is calculated against shares outstanding. By default the most recent quarter with any filings is used; pass `reportDate` to pin an earlier quarter (see the parameter description for the filing-lag caveat).\n\nFor symbols without an issuer-level shares-outstanding figure (e.g. ETFs, funds), the per-row `pctOfShares` and `prevPctOfShares` fields are omitted.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","schema":{"type":"integer"},"description":"Company CIK number. Alternative to `symbol` — provide one or the other.","example":320193},{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1,"maximum":1000},"description":"Page number (1-indexed)"},{"in":"query","name":"pageSize","schema":{"type":"integer","default":100,"minimum":1,"maximum":500},"description":"Number of results per page (max 500)"},{"in":"query","name":"reportDate","schema":{"type":"string","format":"date"},"description":"Optional as-of date (YYYY-MM-DD) that pins the query to the most recent 13F quarter-end\non or before this date. Exact quarter-ends aren't required — any date works, and the\nreturned `reportDate` on each row tells you which quarter you actually got. When omitted,\nthe latest quarter with any filings is used.\n\n**Filing lag note:** Managers have up to 45 days after quarter end to file Form 13F, so\ncoverage of the current quarter is thin during that window. For a complete picture, pass\nthe prior quarter's end explicitly (e.g. `2025-12-31` during Q1 2026).\n","example":"2025-12-31"}],"responses":{"200":{"description":"Paginated list of institutional holders ordered by value (descending)","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number (1-indexed)","example":1},"pageSize":{"type":"integer","description":"Number of results per page","example":100},"totalPages":{"type":"integer","description":"Total number of pages","example":29},"totalResults":{"type":"integer","description":"Total number of institutional holders for this stock","example":2847},"data":{"type":"array","items":{"type":"object","properties":{"managerName":{"type":"string","description":"Name of the institutional manager","example":"BlackRock, Inc."},"managerCik":{"type":"integer","description":"CIK of the institutional manager","example":2012383},"value":{"type":"number","description":"Market value of holdings (USD)","example":314465315556},"shares":{"type":"number","description":"Number of shares held","example":1157054556},"shareType":{"type":"string","description":"Type of shares held:\n\n| Code | Meaning |\n|------|---------|\n| SH | Shares (common/preferred stock) |\n| PRN | Principal amount (bonds, convertible notes) |\n","example":"SH"},"investmentDiscretion":{"type":"string","description":"Level of investment discretion the manager has over the position:\n\n| Code | Meaning |\n|------|---------|\n| SOLE | Manager has sole discretion over investment decisions |\n| SHARED | Discretion is shared with another manager or entity |\n| DEFINED | Discretion is defined by a specific agreement or plan |\n","example":"SOLE"},"putCall":{"type":"string","nullable":true,"description":"Options position type, if applicable. Null for direct equity holdings.\n\n| Code | Meaning |\n|------|---------|\n| PUT | Put option — right to sell shares at a specified price |\n| CALL | Call option — right to buy shares at a specified price |\n","example":null},"soleVoting":{"type":"number","description":"Shares with sole voting authority","example":1037350935},"sharedVoting":{"type":"number","description":"Shares with shared voting authority","example":0},"noneVoting":{"type":"number","description":"Shares with no voting authority","example":119703621},"reportDate":{"type":"string","description":"Report quarter end date (YYYY-MM-DD)","example":"2025-12-31"},"prevShares":{"type":"number","nullable":true,"description":"Shares held in the previous quarter (null if new position)","example":1148562978},"prevValue":{"type":"number","nullable":true,"description":"Value of holdings in the previous quarter (null if new position)","example":292378841109},"pctOfShares":{"type":"number","description":"Percentage of total shares outstanding. Omitted when no issuer-level shares-outstanding figure is available (e.g. for ETFs/funds).","example":7.87},"accessionNumber":{"type":"string","nullable":true,"description":"SEC accession number of the 13F filing","example":"0002012383-26-000920"},"prevPctOfShares":{"type":"number","description":"Previous quarter ownership percentage. Omitted when the manager had no position in the prior quarter, or when no issuer-level shares-outstanding figure is available.","example":7.81}}}}}}}}},"400":{"description":"Invalid parameters or company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/ownership/portfolio":{"get":{"tags":["Ownership"],"summary":"Institutional investor portfolio","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns the full portfolio of an institutional investor (identified by CIK) from a 13F filing.\nThis is the inverse of `/api/ownership/institutional-holders` — instead of \"who owns this stock\", this answers \"what does this investor own\".\nOnly managers with $100M+ AUM who file Form 13F-HR are included.\n\nBy default the manager's own most recent filing is used, so different managers may resolve\nto different quarters during the 45-day filing window. Pass `reportDate` to pin every manager\nto the same quarter for side-by-side comparisons.\n","parameters":[{"in":"query","name":"cik","required":true,"schema":{"type":"integer"},"description":"CIK of the institutional manager","example":1067983},{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1,"maximum":1000},"description":"Page number (1-indexed)"},{"in":"query","name":"pageSize","schema":{"type":"integer","default":100,"minimum":1,"maximum":500},"description":"Number of results per page (max 500)"},{"in":"query","name":"reportDate","schema":{"type":"string","format":"date"},"description":"Optional as-of date (YYYY-MM-DD) that pins the query to the manager's most recent\n13F filing on or before this date. Exact quarter-ends aren't required — the returned\n`reportDate` field tells you which quarter you actually got. When omitted, the manager's\nlatest filing is used.\n\n**When to use it:** comparing several managers' portfolios side-by-side. Without a pin,\none manager may resolve to Q4 while another has already reported Q1, producing\napples-to-oranges results during the 45-day 13F filing window.\n","example":"2025-12-31"}],"responses":{"200":{"description":"Paginated portfolio of holdings ordered by value (descending)","content":{"application/json":{"schema":{"type":"object","properties":{"managerName":{"type":"string","description":"Name of the institutional manager","example":"BERKSHIRE HATHAWAY INC"},"managerCik":{"type":"integer","example":1067983},"reportDate":{"type":"string","nullable":true,"description":"Quarter end date of the latest filing (YYYY-MM-DD)","example":"2025-12-31"},"page":{"type":"integer","description":"Current page number (1-indexed)","example":1},"pageSize":{"type":"integer","description":"Number of results per page","example":100},"totalPages":{"type":"integer","description":"Total number of pages","example":1},"totalResults":{"type":"integer","description":"Total number of holdings in the portfolio","example":42},"data":{"type":"array","items":{"type":"object","properties":{"issuerName":{"type":"string","description":"Name of the issuer (company)","example":"APPLE INC"},"titleOfClass":{"type":"string","nullable":true,"description":"Title of the security class","example":"COM"},"cusip":{"type":"string","description":"CUSIP identifier (9 characters)","example":"037833100"},"symbol":{"type":"string","nullable":true,"description":"Ticker symbol (null if CUSIP could not be matched)","example":"AAPL"},"value":{"type":"number","description":"Market value of the position (USD)","example":75145782000},"shares":{"type":"number","description":"Number of shares held","example":300000000},"shareType":{"type":"string","description":"Type of shares held:\n\n| Code | Meaning |\n|------|---------|\n| SH | Shares (common/preferred stock) |\n| PRN | Principal amount (bonds, convertible notes) |\n","example":"SH"},"putCall":{"type":"string","description":"Options position type. Omitted for direct equity holdings.\n\n| Code | Meaning |\n|------|---------|\n| PUT | Put option — right to sell shares at a specified price |\n| CALL | Call option — right to buy shares at a specified price |\n"},"investmentDiscretion":{"type":"string","description":"Level of investment discretion the manager has over the position:\n\n| Code | Meaning |\n|------|---------|\n| SOLE | Manager has sole discretion over investment decisions |\n| SHARED | Discretion is shared with another manager or entity |\n| DEFINED | Discretion is defined by a specific agreement or plan |\n","example":"SOLE"},"soleVoting":{"type":"number","description":"Shares with sole voting authority"},"sharedVoting":{"type":"number","description":"Shares with shared voting authority"},"noneVoting":{"type":"number","description":"Shares with no voting authority"}}}}}}}}},"400":{"description":"Invalid parameters or manager not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/ownership/summary":{"get":{"tags":["Ownership"],"summary":"Ownership summary","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns an aggregate ownership breakdown for a stock: total institutional ownership percentage, holder count, top 10 holders, beneficial owner count, and insider count.\nInstitutional data is from the latest 13F quarter. Ownership percentage is calculated against shares outstanding.\n\nFor symbols without an issuer-level shares-outstanding figure (e.g. ETFs, funds), the `sharesOutstanding`, `institutional.pctOfSharesOutstanding`, and per-holder `pctOfShares` fields are omitted from the response.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Aggregate ownership breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"sharesOutstanding":{"type":"number","description":"Total shares outstanding from the latest filing. Omitted when no issuer-level shares-outstanding figure is available (e.g. for ETFs/funds).","example":14700000000},"institutional":{"type":"object","properties":{"holderCount":{"type":"integer","description":"Number of distinct institutional holders","example":2847},"totalShares":{"type":"number","description":"Total shares held by institutions","example":10234567890},"totalValue":{"type":"number","description":"Total market value of institutional holdings (USD)","example":2891234567000},"pctOfSharesOutstanding":{"type":"number","description":"Institutional ownership as percentage of shares outstanding. Omitted when `sharesOutstanding` is unavailable.","example":69.62},"reportDate":{"type":"string","nullable":true,"description":"Quarter end date of the latest 13F data","example":"2025-12-31"},"topHolders":{"type":"array","description":"Top 10 institutional holders by value, deduplicated by manager CIK","items":{"type":"object","properties":{"managerName":{"type":"string","example":"BlackRock, Inc."},"managerCik":{"type":"integer","example":2012383},"shares":{"type":"number","example":1157054556},"value":{"type":"number","example":314465315556},"pctOfShares":{"type":"number","description":"Holder's position as percentage of shares outstanding. Omitted when `sharesOutstanding` is unavailable.","example":7.87}}}},"votingAuthority":{"type":"object","description":"Aggregate voting authority across all institutional holdings in the latest quarter — sums of shares where managers have sole, shared, or no voting power","properties":{"sole":{"type":"number","description":"Total shares with sole voting authority","example":8123456789},"shared":{"type":"number","description":"Total shares with shared voting authority","example":234567890},"none":{"type":"number","description":"Total shares with no voting authority","example":12345678}}},"topQoqMovers":{"type":"object","description":"Top 5 increases and top 5 decreases in institutional positions between the two most recent reporting quarters,\nranked by absolute share count delta. Aggregated per manager CIK.\nMovers with absolute deltas under 1,000 shares are excluded.\n","properties":{"increases":{"type":"array","description":"Top 5 quarter-over-quarter position increases (largest deltaShares first)","items":{"type":"object","properties":{"managerName":{"type":"string","example":"BlackRock, Inc."},"managerCik":{"type":"integer","example":2012383},"shares":{"type":"number","description":"Current quarter share count (aggregated across this manager's positions)","example":1157054556},"prevShares":{"type":"number","description":"Prior quarter share count","example":1100000000},"deltaShares":{"type":"number","description":"Change in share count (current − previous; negative for decreases)","example":57054556},"deltaPct":{"type":"number","description":"Percentage change in share count (rounded to 1 decimal)","example":5.2},"pctOfShares":{"type":"number","description":"Manager's current position as percentage of shares outstanding (rounded to 2 decimals)","example":7.87}}}},"decreases":{"type":"array","description":"Top 5 quarter-over-quarter position decreases (most negative deltaShares first)","items":{"type":"object","properties":{"managerName":{"type":"string","example":"Vanguard Group Inc."},"managerCik":{"type":"integer","example":102909},"shares":{"type":"number","description":"Current quarter share count (aggregated across this manager's positions)","example":980000000},"prevShares":{"type":"number","description":"Prior quarter share count","example":1050000000},"deltaShares":{"type":"number","description":"Change in share count (current − previous; negative for decreases)","example":-70000000},"deltaPct":{"type":"number","description":"Percentage change in share count (rounded to 1 decimal)","example":-6.7},"pctOfShares":{"type":"number","description":"Manager's current position as percentage of shares outstanding (rounded to 2 decimals)","example":6.67}}}}}}}},"beneficialOwnerCount":{"type":"integer","description":"Number of 5%+ beneficial owners (Schedule 13D/13G filers)","example":3},"insiderCount":{"type":"integer","description":"Number of distinct company insiders (officers and directors)","example":12}}}}}},"400":{"description":"Invalid parameters or company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/ownership/institutional-holders/history":{"get":{"tags":["Ownership"],"summary":"Institutional ownership history","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns quarterly time series of institutional ownership for a stock.\nEach entry represents one quarter's aggregated 13F data: total holder count, shares, value, and ownership percentage.\nUseful for tracking how institutional interest in a stock has changed over time.\n\nFor symbols without an issuer-level shares-outstanding figure (e.g. ETFs, funds), the `pctOfSharesOutstanding` field is omitted from each entry.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"Quarterly ownership data points sorted chronologically (ascending)","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"reportDate":{"type":"string","description":"Quarter end date (YYYY-MM-DD)","example":"2025-09-30"},"holderCount":{"type":"integer","description":"Number of distinct institutional holders that quarter","example":2801},"totalShares":{"type":"number","description":"Total shares held by all institutions","example":10087654321},"totalValue":{"type":"number","description":"Total market value of all institutional holdings (USD)","example":2456789012000},"pctOfSharesOutstanding":{"type":"number","description":"Total institutional ownership as percentage of shares outstanding. Omitted when no issuer-level shares-outstanding figure is available (e.g. for ETFs/funds).","example":68.62}}}}}}},"400":{"description":"Invalid parameters or company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/ownership/institutional-holders/search":{"get":{"tags":["Ownership"],"summary":"Search institutional holders","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nSearch for institutional investment managers by name. Returns matching manager names and CIKs.\nUse the returned `managerCik` with `/api/ownership/portfolio` to view their full holdings.\n","parameters":[{"in":"query","name":"query","required":true,"schema":{"type":"string","minLength":2},"description":"Search term (case-insensitive substring match)","example":"blackrock"},{"in":"query","name":"limit","schema":{"type":"integer","default":20,"maximum":100},"description":"Maximum number of results"}],"responses":{"200":{"description":"List of matching institutional managers","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"managerName":{"type":"string","description":"Full name of the institutional manager","example":"BLACKROCK INC."},"managerCik":{"type":"integer","description":"CIK of the manager (use with /api/ownership/portfolio)","example":2012383}}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/ownership/beneficial-owners/history":{"get":{"tags":["Ownership"],"summary":"Beneficial ownership history","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns all Schedule 13D/13G filings for a stock, including historical entries.\nUnlike `/api/ownership/beneficial-owners` (which shows only the latest filing per owner), this endpoint shows every filing — useful for tracking how a beneficial owner's position has changed over time.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193}],"responses":{"200":{"description":"All beneficial ownership filings sorted by date (descending)","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"reportingPersonName":{"type":"string","description":"Name of the beneficial owner","example":"The Vanguard Group"},"reportingPersonCik":{"type":"integer","nullable":true,"description":"CIK of the reporting person"},"activist":{"type":"boolean","description":"Whether this is a 13D (activist) filer"},"percentOfClass":{"type":"number","nullable":true,"description":"Ownership percentage at the time of filing","example":9.47},"aggregateAmountOwned":{"type":"number","nullable":true,"description":"Total shares owned at the time of filing","example":1415826462},"reportDate":{"type":"string","nullable":true,"description":"Filing report date (YYYY-MM-DD)","example":"2025-07-29"},"accessionNumber":{"type":"string","nullable":true,"description":"SEC accession number"},"filingType":{"type":"string","nullable":true,"description":"SEC form type (13G, 13D, 13G/A, 13D/A)","example":"13G"},"intent":{"type":"string","nullable":true,"description":"Classified investor intent:\n\n| Value | Meaning |\n|-------|---------|\n| active | Activist — seeks board seats, proxy fights, corporate changes |\n| strategic | Passive — investment purposes only |\n"}}}}}}},"400":{"description":"Invalid parameters or company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/ownership/activity":{"get":{"tags":["Ownership"],"summary":"Recent ownership activity","description":"![Stock](https://img.shields.io/badge/Stock-f97316) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nCombined feed of recent ownership changes for a stock:\n- **Insider transactions** from the last 90 days (deduplicated, officers/directors only)\n- **Beneficial owner filings** from the last 180 days (Schedule 13D/13G)\n- **Institutional changes** from the latest quarter (new positions, 25%+ increases/decreases)\n\nProvides a single-call overview of all ownership activity without needing to hit multiple endpoints.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The stock ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"limit","schema":{"type":"integer","default":20,"maximum":100},"description":"Maximum items per category"}],"responses":{"200":{"description":"Recent ownership activity across all categories","content":{"application/json":{"schema":{"type":"object","properties":{"insiderTransactions":{"type":"array","description":"Recent insider trades (last 90 days)","items":{"type":"object","properties":{"ownerName":{"type":"string","description":"Name of the insider (officer or director)","example":"Tim Cook"},"transactionCode":{"type":"string","description":"SEC transaction code indicating the type of transaction:\n\n| Code | Meaning |\n|------|---------|\n| P | Open-market or private purchase |\n| S | Open-market or private sale |\n| M | Exercise or conversion of derivative security |\n| A | Grant, award, or other acquisition (e.g. stock award) |\n| D | Disposition to the issuer (e.g. return of shares) |\n| F | Payment of exercise price or tax liability by delivering securities |\n| G | Gift |\n| I | Discretionary transaction by Rule 10b5-1 trading plan |\n| C | Conversion of derivative security |\n| E | Expiration of short derivative position |\n| H | Expiration (or cancellation) of long derivative position with value received |\n| O | Exercise of out-of-the-money derivative security |\n| X | Exercise of in-the-money or at-the-money derivative security |\n| W | Acquisition or disposition by will or laws of descent |\n| Z | Deposit into or withdrawal from voting trust |\n| J | Other acquisition or disposition |\n| K | Equity swap or similar transaction |\n| U | Disposition due to a tender of shares in a change of control |\n| L | Small acquisition (less than $10,000) |\n| V | Transaction voluntarily reported earlier than required |\n","example":"S"},"shares":{"type":"number","nullable":true,"description":"Number of shares involved in the transaction","example":50000},"pricePerShare":{"type":"number","nullable":true,"description":"Price per share (USD)","example":245.5},"acquiredDisposed":{"type":"string","description":"Whether shares were acquired or disposed:\n\n| Code | Meaning |\n|------|---------|\n| A | Acquired — shares were added to the insider's holdings |\n| D | Disposed — shares were removed from the insider's holdings |\n","example":"D"},"transactionDate":{"type":"string","description":"Date the transaction occurred (YYYY-MM-DD)","example":"2025-12-15"},"officerTitle":{"type":"string","nullable":true,"description":"Officer title (e.g. CEO, CFO), null for non-officer directors","example":"Chief Executive Officer"}}}},"beneficialOwnerFilings":{"type":"array","description":"Recent 13D/13G filings (last 180 days)","items":{"type":"object","properties":{"reportingPersonName":{"type":"string","description":"Name of the beneficial owner (5%+ shareholder)","example":"The Vanguard Group"},"activist":{"type":"boolean","description":"Whether this is a Schedule 13D filer (activist intent). 13G filers are passive.","example":false},"percentOfClass":{"type":"number","nullable":true,"description":"Ownership percentage at the time of filing","example":9.47},"aggregateAmountOwned":{"type":"number","nullable":true,"description":"Total shares owned at the time of filing","example":1415826462},"reportDate":{"type":"string","nullable":true,"description":"Filing report date (YYYY-MM-DD)","example":"2025-07-29"},"intent":{"type":"string","nullable":true,"description":"Investor intent classified from the filing's stated purpose (Item 4):\n\n| Value | Meaning |\n|-------|---------|\n| active | Activist — seeks board seats, proxy fights, corporate changes |\n| strategic | Passive — investment purposes only |\n"}}}},"institutionalChanges":{"type":"array","description":"Significant institutional position changes from the latest quarter","items":{"type":"object","properties":{"managerName":{"type":"string","description":"Name of the institutional manager","example":"BlackRock, Inc."},"managerCik":{"type":"integer","description":"CIK of the institutional manager (use with /api/ownership/portfolio)","example":2012383},"shares":{"type":"number","description":"Number of shares held in the current quarter","example":1157054556},"value":{"type":"number","description":"Market value of holdings in the current quarter (USD)","example":314465315556},"prevShares":{"type":"number","description":"Previous quarter shares. `0` for new positions (`changeType: \"new\"`).\n"},"changeType":{"type":"string","description":"Type of change:\n\n| Value | Meaning |\n|-------|---------|\n| new | Position opened this quarter (not held previously) |\n| increased | Shares increased by 25%+ from previous quarter |\n| decreased | Shares decreased by 25%+ from previous quarter |\n"}}}}}}}}},"400":{"description":"Invalid parameters or company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/symbols":{"get":{"tags":["Symbol Lists"],"summary":"List all symbols","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nPaginated list of all supported ticker symbols (stocks, ETFs, and mutual funds) with enriched profile data. Filter by type, exchange, sector, or status.\n","parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1},"description":"Page number (1-indexed)"},{"in":"query","name":"pageSize","schema":{"type":"integer","default":100,"minimum":1,"maximum":1000},"description":"Number of results per page"},{"in":"query","name":"type","schema":{"type":"string","enum":["stock","etf"]},"description":"Filter by security type"},{"in":"query","name":"exchange","schema":{"type":"string"},"description":"Filter by exchange (e.g. NASDAQ, NYSE)","example":"NASDAQ"},{"in":"query","name":"sector","schema":{"type":"string"},"description":"Filter by business sector (e.g. Technology, Healthcare)","example":"Technology"},{"in":"query","name":"status","schema":{"type":"string","default":"operating","enum":["operating","delisted"]},"description":"Filter by listing status"}],"responses":{"200":{"description":"Paginated list of symbols with enriched profile data","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer","example":1},"pageSize":{"type":"integer","example":100},"totalPages":{"type":"integer","example":85},"totalResults":{"type":"integer","example":8432},"data":{"type":"array","items":{"$ref":"#/components/schemas/SymbolProfile"}}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/symbols/exchanges":{"get":{"tags":["Symbol Lists"],"summary":"List exchanges","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns all exchanges with the number of listed symbols on each.\n","responses":{"200":{"description":"List of exchanges","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"exchange":{"type":"string","description":"Exchange name","example":"NASDAQ"},"symbolCount":{"type":"integer","description":"Number of symbols listed on this exchange","example":3842}}}}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/symbols/sectors":{"get":{"tags":["Symbol Lists"],"summary":"List sectors","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns all business sectors with the number of stocks in each. Sectors are derived from SEC SIC codes.\n","responses":{"200":{"description":"List of sectors","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"sector":{"type":"string","description":"Business sector name","example":"Technology"},"symbolCount":{"type":"integer","description":"Number of stocks in this sector","example":1205}}}}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/symbols/industries":{"get":{"tags":["Symbol Lists"],"summary":"List industries","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns all distinct industries with the number of stocks in each. Industries are derived from SEC SIC codes.\n","responses":{"200":{"description":"List of industries","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"industry":{"type":"string","description":"Industry name","example":"Consumer Electronics"},"symbolCount":{"type":"integer","description":"Number of stocks in this industry","example":42}}}}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/symbols/industry-groups":{"get":{"tags":["Symbol Lists"],"summary":"List industry groups","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns all 8 high-value industry group definitions used by StockFit for cross-company comparison within specialized sectors. These groups appear as `industryGroup` in symbol profiles.\n","responses":{"200":{"description":"List of industry group definitions","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Machine-readable industry group identifier","example":"semiconductor"},"label":{"type":"string","description":"Human-readable industry group label (matches `industryGroup` field in symbol profiles)","example":"Semiconductors"}}}}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/lookup/cik":{"get":{"tags":["Symbol Lookup"],"summary":"Lookup by CIK","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns enriched symbol profile for a given SEC Central Index Key. Works for stocks, ETFs, and mutual funds.\n","parameters":[{"in":"query","name":"cik","required":true,"schema":{"type":"integer"},"description":"The SEC Central Index Key (CIK) without leading zeros","example":320193},{"in":"query","name":"seriesId","schema":{"type":"integer","default":0,"minimum":0,"maximum":999999},"description":"Series ID for ETFs/mutual funds that share a CIK across multiple series. Defaults to 0 (primary series)."}],"responses":{"200":{"description":"Symbol profile for the given CIK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SymbolProfile"}}}},"400":{"description":"Invalid parameters or symbol not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/lookup/cusip":{"get":{"tags":["Symbol Lookup"],"summary":"Lookup by CUSIP","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns enriched symbol profile for a given CUSIP identifier. Works for stocks, ETFs, and mutual funds.\n","parameters":[{"in":"query","name":"cusip","required":true,"schema":{"type":"string","minLength":6,"maxLength":9},"description":"The CUSIP identifier (6–9 characters)","example":"037833100"}],"responses":{"200":{"description":"Symbol profile for the given CUSIP","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SymbolProfile"}}}},"400":{"description":"Invalid parameters or CUSIP not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/lookup/symbol":{"get":{"tags":["Symbol Lookup"],"summary":"Lookup by symbol","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns enriched profile (name, CIK, exchange, sector, industry, description, logo) for a given ticker symbol.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The ticker symbol","example":"AAPL"}],"responses":{"200":{"description":"Symbol profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SymbolProfile"}}}},"400":{"description":"Invalid parameters or symbol not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/lookup/batch":{"get":{"tags":["Symbol Lookup"],"summary":"Batch lookup by symbols","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nReturns enriched profiles for multiple ticker symbols in a single request. Up to 50 symbols per request.\n","parameters":[{"in":"query","name":"symbols","required":true,"schema":{"type":"string","minLength":1,"maxLength":300},"description":"Comma-separated list of ticker symbols (max 50)","example":"AAPL,MSFT,GOOG"}],"responses":{"200":{"description":"Map of symbol to profile. Missing symbols are omitted from the response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/SymbolProfile"},"example":{"AAPL":{"symbol":"AAPL","name":"Apple Inc.","cik":320193,"seriesId":0,"exchange":"NASDAQ","type":"stock","sector":"Technology","industry":"Consumer Electronics"}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/lookup/figi":{"get":{"tags":["Symbol Lookup"],"summary":"Lookup by Composite FIGI","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nResolves a Bloomberg Composite FIGI to a full symbol profile with all identifiers.\nComposite FIGI is a security-level identifier — one per security regardless of listing exchange.\n","parameters":[{"in":"query","name":"figi","required":true,"schema":{"type":"string","minLength":12,"maxLength":12},"description":"Bloomberg Composite FIGI (12 characters, starts with BBG)","example":"BBG000B9XRY4"}],"responses":{"200":{"description":"Resolved symbol profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SymbolProfile"}}}},"400":{"description":"Invalid FIGI or not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/lookup/former-names":{"get":{"tags":["Symbol Lookup"],"summary":"Search by former company names","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nFinds companies that previously operated under a different legal name. Useful for tracking corporate rebrandings and name changes (e.g. searching \"Facebook\" finds Meta Platforms).\n","parameters":[{"in":"query","name":"searchString","required":true,"schema":{"type":"string","minLength":2,"maxLength":50},"description":"Search term to match against former company names","example":"Facebook"},{"in":"query","name":"limit","schema":{"type":"integer","default":10,"minimum":1,"maximum":50},"description":"Maximum number of results"}],"responses":{"200":{"description":"Matching companies with their current profile and former names","content":{"application/json":{"schema":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/SymbolProfile"},{"type":"object","properties":{"formerNames":{"type":"array","items":{"type":"string"},"description":"Previous legal names of the company","example":["FACEBOOK INC","THEFACEBOOK INC"]}}}]}}}}},"400":{"description":"Invalid search string","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/lookup/search":{"get":{"tags":["Symbol Lookup"],"summary":"Search symbols","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nFuzzy-matches company name or ticker symbol, ranked by relevance. Returns enriched profiles with sector, industry, description, and logo. Covers stocks, ETFs, and mutual funds.\n","parameters":[{"in":"query","name":"searchString","required":true,"schema":{"type":"string","minLength":2,"maxLength":50},"description":"Search term (name or ticker). Alphanumeric characters, dots, hyphens, and spaces allowed.","example":"Apple"},{"in":"query","name":"type","schema":{"type":"string","enum":["stock","etf"]},"description":"Filter by security type"},{"in":"query","name":"exchange","schema":{"type":"string"},"description":"Filter by exchange","example":"NASDAQ"},{"in":"query","name":"sector","schema":{"type":"string"},"description":"Filter by business sector","example":"Technology"},{"in":"query","name":"includeDelisted","schema":{"type":"boolean","default":false},"description":"Include delisted symbols in results"},{"in":"query","name":"limit","schema":{"type":"integer","default":25,"minimum":1,"maximum":100},"description":"Maximum number of results"}],"responses":{"200":{"description":"Matching symbols ranked by relevance","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SymbolProfile"}}}}},"400":{"description":"Invalid search string","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/lookup/news":{"get":{"tags":["Symbol Lookup"],"summary":"News for a ticker","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nRecent news headlines for a ticker symbol (stocks, ETFs, and mutual funds), aggregated from public news sources. Returns headline, publisher, publication timestamp, and a link to the original article — full article text is not included. Results are deduplicated by title and sorted newest-first.\n\n> **Best-effort data:** Aggregated from third-party news sources without a service-level agreement. Availability and freshness may change without notice. Use for informational purposes; not suitable for automated trading decisions.\n","parameters":[{"in":"query","name":"symbol","required":true,"schema":{"type":"string","minLength":1,"maxLength":5},"description":"The ticker symbol","example":"AAPL"},{"in":"query","name":"cik","description":"Company CIK number. Alternative to `symbol` — provide one or the other.","required":false,"schema":{"type":"integer"},"example":320193},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Maximum number of news items to return","example":20}],"responses":{"200":{"description":"Aggregated news items","content":{"application/json":{"schema":{"type":"object","properties":{"symbol":{"type":"string","example":"AAPL"},"news":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"Article headline","example":"Apple beats Q2 earnings, iPhone revenue up 8%"},"link":{"type":"string","description":"URL to the original article","example":"https://www.cbsnews.com/news/apple-earnings-q2"},"source":{"type":"string","nullable":true,"description":"Publisher name (derived from the article hostname)","example":"cbsnews.com"},"publishedAt":{"type":"string","format":"date-time","description":"Publication timestamp in ISO 8601","example":"2026-04-21T15:00:00.000Z"},"summary":{"type":"string","nullable":true,"description":"Short text summary if provided by the feed","example":"Apple reported stronger-than-expected results..."}}}}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/lookup/news/market":{"get":{"tags":["Symbol Lookup"],"summary":"General US market news","description":"![Free](https://img.shields.io/badge/Free-22c55e) ![Starter](https://img.shields.io/badge/Starter-3b82f6) ![Stock](https://img.shields.io/badge/Stock-f97316) ![ETF](https://img.shields.io/badge/ETF-14b8a6) ![Pro](https://img.shields.io/badge/Pro-8b5cf6)\n\nTop US market and business news headlines, merged from multiple public sources. Returns headline, publisher, publication timestamp, and a link to the original article — full article text is not included. Results are deduplicated by title and sorted newest-first.\n\n> **Best-effort data:** Aggregated from third-party news sources without a service-level agreement. Multi-source merge mitigates any single feed degrading, but availability and freshness may change without notice. Use for informational purposes; not suitable for automated trading decisions.\n","parameters":[{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Maximum number of news items to return","example":20}],"responses":{"200":{"description":"Aggregated market news items","content":{"application/json":{"schema":{"type":"object","required":["news"],"properties":{"news":{"type":"array","items":{"type":"object","required":["title","link","publishedAt"],"properties":{"title":{"type":"string","description":"Article headline","example":"Stocks close higher as Fed signals patience on rate cuts"},"link":{"type":"string","description":"URL to the original article","example":"https://www.marketwatch.com/story/stocks-close-higher"},"source":{"type":"string","nullable":true,"description":"Publisher name (derived from the article hostname)","example":"marketwatch.com"},"publishedAt":{"type":"string","format":"date-time","description":"Publication timestamp in ISO 8601","example":"2026-04-26T20:15:00.000Z"},"summary":{"type":"string","nullable":true,"description":"Short text summary if provided by the feed","example":"The S&P 500 rose 0.5% as investors digested..."}}}}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Feature not available on current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}