# GET /api/v1/overlap?funds={funds}

One endpoint of the TickerInside API, with data through 2026-10-16. Contents of the reference, each section and endpoint as a file: https://tickerinside.com/api/sections/index.md. The whole reference as Markdown: https://tickerinside.com/api/index.md

`GET /overlap?funds={funds}`: the overlap of 2 to 10 funds, computed when asked with the MCP tools' code: two give the pair (overlap by weight, each fund's share in common, the largest shared holdings, correlation), three or more every pair ranked. Bond funds overlap by issuer; a fund holding no shares is set aside with the reason. CSV: /overlap.csv. https://tickerinside.com/api/v1/overlap?funds=VOO,QQQ

## Response

The overlap of the funds in funds, a list separated by commas, computed when asked with the code of the MCP tools compare_etfs and get_etf_overlap_matrix, so the figures are theirs. Two funds give the pair: the overlap by weight, each fund's share held in common, the largest shared holdings, the correlation of weekly returns and each fund's cost and risk (kind pair). Three or more give every pair ranked by overlap by weight (kind matrix). Two fixed income funds overlap by issuer; a fund that holds no shares is set aside with the reason, and a ticker not covered is skipped, or answers 404 in a pair. A fund asked for under the ticker it had before it was renamed is read under its new ticker, which renamed gives. format=csv, or /api/v1/overlap.csv, gives one row per pair. 2 to 10 funds. The files read weigh at most 64 KB for two funds and 58 KB for three or more, a file of the other layers a third of its size, and the pairs compare at most 2,600 holdings, each pair the holdings of the fund that holds fewer.

```json
{
  "kind": "pair",
  "…": "2 more fields",
  "pair": ["VOO", "QQQ"],
  "…": "1 more field",
  "holdings_as_of": {"VOO": "2026-08-31", "QQQ": "2026-10-08"},
  "…": "1 more field",
  "overlap": {"by_weight": 53.9, "share_of_a": 54, "share_of_b": 92.9, "companies_in_both": 85, "…": "2 more fields", "largest_shared": [{"ticker": "NVDA", "in_a": 8.09, "in_b": 8.33, "counted": 8.09}, {"ticker": "AAPL", "in_a": 7.04, "in_b": 7.45, "counted": 7.04}, "… 13 more"]},
  "correlation_3y": 0.95,
  "…": "1 more field",
  "weeks_used": 156,
  "…": "7 more fields"
}
```

- `kind` (string): pair for two funds, matrix for three or more: which of the two shapes the answer has.
- `page_url` (string or null): The web page whose HTML, as the server sends it, prints the answer's figure, so that it reads without JavaScript: for a pair, its written comparison when there is one, else its "Does it diversify me?" answer within that answer's limits; for three funds or more, the x-ray the site wrote of the same funds; for a look-through, the x-ray the site wrote of the portfolio at the same weights (listed under pages in /og/answers.json), or for one fund, its page. Null where no page prints the figure yet: any other overlap of three funds or more or look-through of two funds or more, a pair past those limits, a pair of bond funds.
- `share_url` (string): The address whose HTML reproduces the whole answer on the site: for a pair, its "Does it diversify me?" answer within that answer's limits; for three funds or more and for a portfolio, the x-ray the site wrote of the same funds (listed under pages in /og/answers.json), each weight in percent to 0.01 point and never an amount, in the order of the funds the site wrote it in. Absent where no page prints the answer.
- `pair` (array of string): The two funds, upper case, in the order asked.
- `prices_as_of` (string or null): The price date of the figures read from weekly returns. Null when no fund has prices.
- `holdings_as_of` (object): Each fund's holdings date, by ticker: the date of its issuer file, or the quarter end its SEC filing describes.
- `holdings_source` (object): Each fund's source, by ticker: issuer file, SEC Form N-PORT, trust's own SEC filing, sponsor's own holdings file, or prospectus, no holdings yet.
- `overlap` (object): For two funds holding shares, in percent: by_weight, the sum over the companies both hold of the smaller of their two weights; share_of_a and share_of_b, the part of each fund in companies the other holds too; companies_in_both, the holdings both have, counted by ticker (GOOGL and GOOG count as two), positions_a and positions_b; and largest_shared, the 15 largest shared holdings with each weight and the smaller one counted. A ticker the two hold for two different companies is left out of every figure and listed in same_ticker_two_companies, with same_ticker_note.
- `overlap_kind` (string): issuer when the figures are an overlap by issuer, of fixed income funds. Absent otherwise.
- `issuer_overlap` (object): For two fixed income funds: the overlap by issuer, the smaller weight of each issuer both hold summed (by_weight), the share of each, issuers_in_both, the issuers compared and the largest shared and unshared ones. Never mixed with the overlap by shares.
- `correlation_3y` (number or null): The correlation of the two funds' weekly returns over up to three years, on the weeks both have. Null under 52 such weeks.
- `covariance_annualised_pct2` (number or null): The annualised covariance of the same returns, in percent squared. Null with correlation_3y.
- `weeks_used` (integer or null): How many weeks the two figures above read. Null when they are.
- `funds` (object or null): Each fund by ticker: name, expense_ratio_pct, return_3y_pct, volatility_pct, worst_fall_3y_pct, beta_vs_sp500 (three years, from its file), beta_vs_sp500_1y (the last 52 weeks against SPY's) and positions; a fixed income fund's average coupon, maturity and duration. Null where the data has no figure.
- `how_to_quote` (string): How to quote the figures: which measure, with the holdings dates.
- `covered` (boolean): true when the funds are covered but the answer has no figures (see comparable or computed).
- `comparable` (boolean): false when a fund of the two holds no shares that can be overlapped (see not_comparable). Absent when the figures are given.
- `not_comparable` (array of object): The funds set aside, each with why and the address of its file (fund_file): a leveraged, inverse or other derivative-based fund, a trust or pool, a multi-asset, sponsor-file or prospectus-only fund, or a bond fund beside a stock fund.
- `renamed` (object): Each ticker asked that a fund had before it was renamed, with its ticker now, under which the answer reads and names it. Absent when there is none.
- `source` (object): The files the answer is computed from: each fund's page_url, null without a page, api_url, holdings_source and, for a fund from a filing, filing_url; benchmark_url, SPY's file, when a one-year beta is computed; license; and cite_as, the line to print under a figure.
- `note` (string): Measurement, not investment advice.
- `license` (string): The licence the data is published under.
- `attribution` (string): How to credit the data: a link to the page of a fund the figure comes from, or to this address, where the medium allows one, the name where it does not.
- `docs` (string): The reference of this endpoint.

What three or more funds give instead (kind matrix):

- `computed` (boolean): false when fewer than two of the funds hold shares that can be overlapped (see reason).
- `reason` (string): Why nothing is computed, when computed is false.
- `skipped` (object): The tickers not covered, under not_covered, with what is covered (covered_issuers, also_covered and hint). Absent when every ticker is covered.
- `pairs` (array of object): Every pair of the funds holding shares, the largest overlap by weight first: pair, by_weight, share_of_first, share_of_second and companies_in_both, as overlap gives them for two funds, and same_ticker_two_companies when a ticker stands for two companies.
- `same_ticker_note` (string): What same_ticker_two_companies means, when a pair has it.
- `issuer_overlap_pairs` (array of object): Every pair of the fixed income funds by issuer overlap, largest first: pair, by_weight, share_of_first, share_of_second, issuers_in_both. Never mixed with pairs.
- `issuer_overlap_note` (string): How to read issuer_overlap_pairs, when there are some.

Each answer carries the date and source of every fund's holdings, and source names the files it is computed from.

## Errors and redirects

| Status | reason | Meaning | Next request |
|---|---|---|---|
| 200 |  | The file. | Read it. Every file carries its dates. |
| 204 |  | A browser's CORS preflight, an `OPTIONS` request, answered before any redirect: GET and HEAD from any origin, with the headers asked for, kept up to a day. | Nothing to do. |
| 301 |  | An upper case ticker, a share class written `BRK-B` or `BRK/B` (the file is `brk.b.json`), an address without `.json`, `/api/v1` alone, or punctuation copied from a sentence at its end. A key listed abroad with a hyphen, such as `SQM-B`, keeps it. A written comparison asked for in the other order leads to its file: `vym-vs-vig` to `vig-vs-vym.json`. A fund with no file under `/etf/` leads to its file under `/fund/`: `etf/voo.json` to `fund/voo.json`. `/stock/`, the name of the pages, leads to the stock files under `/sec/`: `stock/nvda.json` to `sec/nvda.json`. | Follow it (`curl -L`). `Location` gives the address. |
| 304 |  | Your `If-None-Match` matches the file's `ETag`. | Keep your copy. |
| 400 |  | A computed answer refused its query: `reason` (`missing_parameter`, `unknown_parameter`, `repeated_parameter`, `invalid_value`, `too_few_funds`, `too_many_funds`) and `parameter` say why. | Fix it as `message` says. |
| 400 | `too_large` | Past the limits of one call (fund files read, holdings compared or looked through): `limit` and `asked` give both figures. | Follow the address or tool `message` names first (`answered_by` gives them as fields), or ask for fewer funds per call. |
| 404 | `no_such_endpoint` | No endpoint at this address. | `covered`: `index.json`. |
| 404 |  | Under `/overlap`, `/lookthrough` and `/diversify`: a fund the answer needs is not covered; `not_covered` lists the tickers and `reasons` their codes. | `covered`: `index.json`. |
| 405 |  | A computed answer asked with another method than GET or HEAD (`method_not_allowed`). | Use GET. |
| 503 |  | The file could not be served just then. The body's `error` is `unavailable`, with `Retry-After: 60`. | Retry after a minute. `uptime`: `uptime.json` says whether the site fails its own checks. |

Every 404 body is JSON. It holds `error`, always `not_covered`; `reason`, a code /contract/ lists; `ticker`, as asked for, or null when the address names no ticker; `message`; `docs`; and the follow-up address named above. Under /history/, it also holds `date` when a date was asked for. `before_history`, for a date before a fund's first file, is answered only once holdings at a date are served. A 400 body holds `error` (`bad_request`), `reason`, `message`, `docs`, and `parameter`, or `limit` and `asked`.