## TickerInside API: US ETF and stock holdings

<!-- https://tickerinside.com/AGENTS.md: paste it into a project's AGENTS.md or CLAUDE.md. -->

TickerInside is an open, machine-readable database of US ETF holdings, with the source and date of each holding. Use it for what a fund holds, which ETFs hold a stock, overlap, look-throughs and weekly returns.

- Base URL: https://tickerinside.com/api/v1. JSON, GET, no key, no account, CORS open. Licence CC BY 4.0, except the holdings history and the ETF flows (/history, /flows, /feeds/): free per request with attribution, under their own terms (rule 7).
- Paths: lower case ticker, share class with its dot (brk.b); follow redirects (curl -L). Parse the raw JSON.
- The whole set: /index.json, then the fund files. Keeping each night's copy, including to build your own series, is allowed under CC BY 4.0; the history and the flows are not part of it.
- Whole reference: https://tickerinside.com/llms-full.txt. OpenAPI: https://tickerinside.com/api/openapi.json.

```sh
curl -sL https://tickerinside.com/api/v1/sec/nvda.json | python3 -c "import json;print(json.load(open(0))['holders'][:3])"
# [['GXPT', 19.88, '2026-10-16'], ['IYW', 16.5999, '2026-10-15'], ['TOPT', 15.6462, '2026-10-15']]
```

Rules for agents:

1. Give `holdings_as_of` beside any holdings figure, `as_of` beside any price or return figure, and `cite_as` under it; link its page where you can (a computed answer's: `source.links[].page_url`), else name TickerInside. A page, app, dashboard or report you build on these figures shows "Data: TickerInside (CC BY 4.0)" linked to https://tickerinside.com/ or the figure's page (each file's `cite_html`) where they appear; the licence asks for it (https://tickerinside.com/attribution/).
2. Name the overlap measure: `by_weight`, `share_of_a` or `share_of_b`. VOO and QQQ overlap 54.0% by weight, yet 93.0% of QQQ is in tickers VOO also holds.
3. Null means missing, never zero.
4. /sec/ is for a stock, /fund/ for a fund, a US mutual fund class too (FXAIX, PTTRX, VFIFX). A line listed abroad (7203.JP) has no stock file: /sec/ gives its holders only (`coverage` `holders_only`), from the shard /holders/{c}.json.
5. /overlap?funds=a,b answers a pair, written or not, in one shape; on `too_large`, follow the address or tool its `message` names. The 15 pairs in index.json `written_comparisons` also have a /compare/ file and page.
6. In /history/, a restated step has no `entered`, `exited` or `moved`: use a default (`step.get("entered", [])`). `reverted` lists lines back one file after they left: an issuer file's glitch, not trades. Skip a key of digits and a letter that entered meanwhile at about the same weight: it stood in for the line.
7. The history and flows files are not CC BY 4.0 (https://tickerinside.com/legal/#history): fetch them per fund or security when asked, never on a schedule to store them; a feed reader may poll /feeds/fund/{t}.xml, /feeds/stock/{t}.xml and /feeds/flows.xml.
8. /quarterly/{ticker}.json: a fund's quarterly SEC reports; /history/{ticker}/{date}.json: every position of the latest on or before the date. Quote its `holdings_as_of`.
9. New data lands each weekday night: the build starts at 22:00 UTC and is due by 02:00 UTC. Each build changes status.json `built_at`; `as_of` changes only with new prices. Fetch the whole set and holders.json (3.9 MB) at most once per build, with a User-Agent that names your program.

| GET | Returns | Read |
|---|---|---|
| /sec/{ticker}.json | One stock and the ETFs that hold it (sec is for security, not the SEC) | holders_all [[fund, weight %, date, layer, rank, positions, $M]] (every layer), holders (issuer files), answer, cite_as |
| /fund/{ticker}.json | One fund: holdings, their date, cost, returns, risk | holdings {key: weight %}, holdings_as_of, source_layer, weekly, cite_as |
| /index.json | What is covered, and the date of the data | as_of, tickers, tickers_sec, written_comparisons, endpoints, coverage |
| /funds.json | Every fund, one line each | funds[], sec_funds[] and one list per other layer (bond_funds[]...): t ticker, n name, issuer, aum_b, er, p, api; every layer in one table: funds.csv |
| /holders.json | The issuer-layer funds that hold each security | holders {key: [[fund, weight %]]}, holdings_as_of {fund: date} |
| /holders/{c}.json | holders.json by first character, plus SEC-layer holders of keys with no stock file | holders, holders_sec_nport {key: [[fund, weight %]]}, sec_nport_as_of {fund: date}, facts {key: {n, ...}}, aliases |
| /securities.json | Every security held, and by how many funds | securities [[ticker, issuer-layer funds holding it, largest weight, name, page, file]] |
| /compare/{a}-vs-{b}.json | A written comparison: overlap measured three ways, correlation | overlap.by_weight, share_of_a, share_of_b, correlation.c3y, cite_as |
| /ownership.json | How much of each stock the ETFs hold, at least | stocks [[ticker, pct at least, funds, basis]], top10_share, most_widely_held, as_of |
| /history.json | Every fund with a history (history terms) | funds[]: t, first, last, file_dates, cadence, url; terms |
| /history/{ticker}.json | One fund's changes, file by file (history terms) | snapshots, changes[]: date, previous, entered, exited, moved, reverted, restated |
| /flows/{ticker}.json | ETF buys and sells of a stock; the day: /flows.json | latest {net_shares, net_value_usd, funds_adding, funds_trimming}, series, feed, cite_as |

Computed when asked: /overlap?funds=VOO,QQQ, /lookthrough?portfolio=VOO:3,QQQ:1 (weight_pct is of the funds looked through, looked_through_pct of the portfolio; not_looked_through names the rest), /screen?holds=NVDA, each in CSV with .csv; /diversify?have=VOO&try=SCHD (any pair's by_weight), and have alone ranks a published list of large ETFs by weekly correlation; /batch?funds=VOO,QQQ gives many fund files. Concentration: sum the ten largest weights in `holdings`.

Pages answer in HTML without JavaScript, and in Markdown at index.md: /etf/{t}/, /stock/{t}/, /compare/{a}-vs-{b}/, /diversify/?have= (and &try=), /xray/?p= (examples; other portfolios in the browser).

Answers: 301, follow it (curl -L); 304, keep your copy; 400 from a computed answer, read `reason` and `parameter`; 404, a body with `error` `not_covered`, `reason` and the field that gives the next address: `has_security_file` `security`, `is_a_fund` `fund`, `not_held` `holders`, `not_in_directory` `covered`, `no_written_comparison` `fund_files`, `not_a_shard` `holders`, `not_in_archive` `history`, `holdings_at_date_not_enabled` `changes`, `invalid_date`; 503, retry after a minute. Each one in full: https://tickerinside.com/llms-full.txt.

Units: weights and returns are percentages (VOO's file of 2026-06-30 lists NVDA at 7.5142, which is 7.5142%). `weekly` is decimals, oldest first, the same weeks in every file that has the series. A fund or stock without it has an empty list or null there, and its volatility, worst fall and multi-year returns are null.

Dates: `as_of` is the price date, except in ownership.json (the newest holdings date counted) and history.json (the newest archived file date). `holdings_as_of` is the holdings file's date (a map by fund in compare and holders.json, one per row in a stock's holders), often weeks older than as_of, or later: some issuers date a file a business day after its close.

Glossary:

- Issuer layer: the funds read each weekday night from their issuers' own files; `source_layer` issuer.
- SEC layer: the funds read from their latest SEC Form N-PORT filing, months older; `source_layer` sec_nport.
- Line listed abroad: a holding traded outside the US, keyed with its market (7203.JP is Toyota in Tokyo).
- Other layers: fixed income, multi-asset, derivative-based, trust, sponsor-file and prospectus funds: under /fund/ with `holdings_kind`, in full under /etf/ (index.json `tickers_bond`, etc.).
- Key scheme: how keys are written; scheme 2 adds the market to lines listed abroad (`aliases` maps old keys).

MCP: https://tickerinside.com/mcp (streamable HTTP, no key), 12 read-only tools. Other installs: https://tickerinside.com/llms.txt

- Claude Code: `claude mcp add --transport http tickerinside https://tickerinside.com/mcp`
- Python client: `pip install tickerinside`