API Documentation

Make a first call

One request against the public demo route: no key, no sign-up. It returns Berkshire Hathaway's largest 13F position; the receipt below links the filing that row was parsed from.

curl "https://api.ko.io/api/v1/holdings/1067983?per_page=1&demo=true"

Response

Abridged response captured 2026-09-23 (quarter ending 2026-06-30). Run it for the live response; no key or sign-up needed.

{
  "data": [
    {
      "cik": "1067983",
      "quarter_date": "2026-06-30",
      "ticker": "AAPL",
      "name_of_issuer": "APPLE INC",
      "shares_held": "227917808",
      "holding_value": "65950296923",
      "total_portfolio_value": "299253556246",
      "portfolio_weight_pct": 22.04,
      "action": "UNCHANGED",
      "share_change": "0",
      "prev_shares": "227917808"
    }
  ]
}

Filer: Berkshire Hathaway
Ticker: AAPL
Shares: 227,917,808
Lines summed: 12

SourceSEC EDGAR13F-HR0001193125-26-352200 ↗period 2026-06-30filed 2026-08-14

The row does not carry its accession. The 13F-HR it was parsed from (quarter ending 2026-06-30, captured 2026-09-23) is listed by GET /api/v1/filings/1067983?form=13F-HR. A newer quarter returns a newer filing.

Next, create a free account and a key in Console → API Keys, then send it as a Bearer token (below). Paginate with page and per_page.

Authentication

Send your API key as a Bearer token in the Authorization header. Keys use the format ko_live_*.

curl "https://api.ko.io/api/v1/holdings/1067983" \
  -H "Authorization: Bearer ko_live_your_key_here"

Demo mode

Add ?demo=true to any endpoint for keyless access. Rate-limited per IP; meant for testing and prototyping.

API key format

Keys start with ko_live_ followed by a hex string. Create keys in the Console.

Auth endpoints (web app)

Used by the ko.io web app; not intended for API consumers.

POST/api/auth/google · /api/auth/login · /api/auth/register · /api/auth/logout
GET/api/auth/me · /api/auth/profile

Response & provenance

All responses share one JSON structure with data and meta fields. data is an array for lists and an object for single resources.

List response200 OK

{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total_count": 1234,
    "query_time_ms": 3.1
  }
}

Object response200 OK

{
  "data": { ... },
  "meta": {
    "query_time_ms": 2.1
  }
}

Provenance

Numeric fields often arrive as strings (for example "holding_value": "65950296923"); parse them before arithmetic. Rows derived from SEC filings resolve to their filing through the filings endpoints (/api/v1/filings/:cik, then /api/v1/filings/:cik/:accession), which return the accession and the documents on sec.gov.

MCP Integration

24 tools

Connect Claude, Cursor, Windsurf or any Model Context Protocol client directly to ko.io data. 24 tools cover SEC filings, macro data and market microstructure.

Remote (HTTP transport -- Claude.ai, any MCP client)

claude mcp add ko-sec-data --transport http https://mcp.ko.io/mcp

Local (stdio -- Claude Code, Cursor)

claude mcp add ko-sec-data -- npx -y @ko-io/mcp-sec-data

.env (optional)

KO_API_KEY=ko_live_xxx    # Optional: without key, uses demo mode (rate-limited per IP)
KO_API_URL=https://api.ko.io

Available tools

24

Tool	Description
search	Search across institutions, stocks, and congress members
get_institution_holdings	13F institutional holdings with change analytics
list_institutions	List/search institutional investors
get_stock_profile	Stock info with ownership summary
get_stock_holders	Institutional holders for a stock
get_stock_activity	Stock activity and trading metrics
get_stock_financials	Company financials from SEC filings
get_stock_price	Historical daily OHLCV prices
get_insider_trades	Form 4 insider trades with filters
list_insider_traders	Top insider traders by volume
get_congress_trades	Congressional stock trades from STOCK Act
get_congress_member	Trading history for a congress member
get_form144_notices	Form 144 proposed sale notices
get_treasury_yields	US Treasury yield curve data
get_fed_rates	Federal Reserve interest rates
get_economic_indicators	BLS CPI, PPI, NFP, unemployment
get_ftd_data	SEC Failures to Deliver
get_financial_stress	OFR Financial Stress Index
get_crypto_exposure	Institutional spot BTC-ETF exposure summary
get_crypto_holders	Institutions holding spot crypto ETFs
get_crypto_holder	One institution's crypto-ETF positions
sec_list_filings	List an entity’s SEC EDGAR filings
sec_get_filing_index	Files inside a specific filing
sec_get_filing_document	Fetch a filing document + signed link

Plan	Price	Daily limit	Bulk export
Free	$0	200 / day	No
Pro	$29 / mo	20,000 / day	No
Team	$99 / mo	200,000 / day	Yes
Enterprise	$499 / mo	1,000,000 / day	Yes

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.

Error Codes

Status	Meaning	Resolution
400	Bad Request	Check query parameters and path format
401	Unauthorized	Include valid API key or use ?demo=true
403	Forbidden	Upgrade plan for this endpoint or feature
404	Not Found	Check endpoint path and resource IDs
429	Rate Limited	Wait for reset or upgrade plan
500	Server Error	Retry after a few seconds

Error response401

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key. Use ?demo=true for keyless access.",
  "status": 401
}

Make a first call

Authentication

Response & provenance

MCP Integration

Available tools

Institutions

Holdings

Stocks & Companies

Stock Analysis

Insider Trades

Congress Trades

SEC Extensions

Treasury

Federal Reserve

Economic

Market Microstructure

Energy

Banking

Financial Stress

Bulk Export

Dashboard

Search

Rate Limits

Error Codes

Available tools

GET/api/v1/institutionsList institutional investors with portfolio metrics. Returns AUM, holdings count, and top positions.

GET/api/v1/institutions/{cik}Get institution details by CIK number. Includes filing history, sector allocation, and recent activity.

GET/api/v1/institutions/aum/{cik}Get historical AUM (assets under management) over time. Returns quarterly portfolio values for charting.

GET/api/v1/institutions/{cik}/similarGet similar institutional investors based on quarterly 13F holdings, active timing, and portfolio profile signals. Supports CIK or slug.

GET/api/v1/holdings/{cik}Get 13F institutional holdings with pre-calculated analytics: quarter-over-quarter changes, action labels (NEW_BUY, ADD, REDUCE, SOLD_ALL), and portfolio weights. Supports slug (e.g., berkshire-hathaway).

GET/api/v1/stocksList stocks with basic information.

GET/api/v1/stocks/{ticker}Get stock info with top institutional holders, recent insider activity, and ownership summary.

GET/api/v1/stocks/{ticker}/financialsGet latest company financials from 10-K and 10-Q filings. 30+ standardized metrics including revenue, margins, EPS, cash flow, and debt ratios.

GET/api/v1/stocks/{ticker}/financials/historicalGet historical financial data for trend analysis. Returns quarterly or annual periods with all standardized metrics.

GET/api/v1/companiesList companies with basic information. Search by company name or ticker symbol.

GET/api/v1/companies/{ticker}Get detailed company profile including sector, industry, market cap, and description.

GET/api/v1/stock-price/{ticker}Get historical daily stock prices with OHLCV data and adjusted close.

GET/api/v1/stock-holders/{ticker}Get institutional holders for a stock. Shows ownership percentage, share counts, and quarter-over-quarter changes.

GET/api/v1/stock-transactions/{ticker}/{cik}Get the full transaction history between a stock and institution across all quarters.

GET/api/v1/insider-tradesList insider trades from SEC Form 4 filings. Includes officer/director buys and sells with dollar values and role identification.

GET/api/v1/executive-trades/{ticker}Get C-suite and director insider trades for a specific stock. Aggregated by executive with total buy/sell volumes.

GET/api/v1/congress-tradesList congressional stock trades from STOCK Act disclosures. Includes transaction type, dollar ranges, and disclosure delays.

GET/api/v1/congress-trades/{member}Get all trades for a specific congress member. URL-encode the member name.

GET/api/v1/congress-trades/stock/{ticker}Get all congressional trades for a specific stock across all members.

GET/api/v1/congress-trades/dashboardCongressional trading dashboard: most active members, most traded stocks, buy/sell ratio, and disclosure delay statistics.

GET/api/v1/form144-noticesList SEC Form 144 notices of proposed sale of securities.

GET/api/v1/form144-notices/{ticker}Get Form 144 notices for a specific stock ticker.

GET/api/v1/form144-notices/insider/{cik}Get Form 144 notices filed by a specific insider (by CIK).

GET/api/v1/sec/13dgSC 13D/G filings — beneficial ownership disclosures for >5% holders.

GET/api/v1/sec/form-dForm D offerings — private placement and Regulation D filings.

GET/api/v1/sec/buybacks8-K buyback announcements — share repurchase program disclosures extracted from 8-K filings.

GET/api/v1/treasury/yieldsUS Treasury yield curve data from 1990. Includes 1M, 3M, 6M, 1Y, 2Y, 3Y, 5Y, 7Y, 10Y, 20Y, 30Y maturities.

GET/api/v1/treasury/auctionsTreasury auction records — bid-to-cover ratios, high yields, allotment percentages.

GET/api/v1/treasury/debtDaily US public debt outstanding — total, public held, and intragovernmental.

GET/api/v1/fed/ratesFederal Reserve interest rates — Fed Funds Rate, SOFR, prime rate, discount rate. Data from 1962.

GET/api/v1/fed/balance-sheetFederal Reserve balance sheet (H.4.1) — total assets, treasuries, MBS, reserves.

GET/api/v1/fed/bank-creditCommercial bank credit (H.8) — loans, leases, securities, deposits at all commercial banks.

GET/api/v1/economic/indicatorsBLS economic indicators — CPI, PPI, Non-Farm Payrolls, unemployment rate, JOLTS.

GET/api/v1/sec/ftdSEC Failures to Deliver data from 2004. Daily FTD share counts and values by ticker.

GET/api/v1/cftc/positionsCFTC Commitments of Traders — disaggregated futures positioning from 2006.

GET/api/v1/energy/eiaEIA energy data — crude oil inventory, natural gas storage, WTI/Brent prices, 9 series total.

GET/api/v1/fdic/banksFDIC bank directory — all US banks with charter info, location, and status.

GET/api/v1/fdic/financialsFDIC bank quarterly financials — assets, deposits, loans, capital ratios for any US bank.

GET/api/v1/fdic/failuresFDIC bank failures from 1934. Includes acquiring institution, estimated loss, and assets at failure.

GET/api/v1/stress/ofrOFR Financial Stress Index — 6 sub-components covering credit, equity, funding, safe assets, volatility, and composite.

GET/api/v1/bulk/exportBulk data export in CSV or JSON format. Requires Team ($99/mo) or higher plan. Supports 6 core tables.

GET/api/v1/dashboard/metricsPlatform metrics: total institutions, holdings records, insider trades, and congress trades.

GET/api/v1/dashboard/trendsTrending activity across all data types. Most active institutions, most traded insider stocks, recent congressional activity.

GET/api/v1/searchUnified search across institutions, stocks, and congress members. Returns categorized results.