API Documentation

List entities with optional filtering.

Query Parameters

kind=snapshot (default) — the daily-captured consensus: EPS and revenue avg/low/high, analyst counts, growth, the EPS trend 7/30/60/90 days ago and revision counts. One row per target fiscal period (estimate_date) per capture day (captured_at, the honest as-of). Snapshots exist from 2026-02-19 only. Daily capture began then, and there is no earlier history to backfill — that floor is real, not a backfill gap.

kind=pre_report — the consensus at each report, as an as-of-dated observation series: as_of = report date, target_period = the reported quarter, eps_estimate beside eps_actual. Quarterly, one observation per report, history to roughly 2004. It is not a forward-year snapshot and not a daily series.

as_of, start and end bound the observation date (captured_at for snapshots, the report date for pre-report); target_period keeps one target fiscal period. Every response's meta states both floors and which series you are holding. Pages never split an observation date, so the date cursors are safe to walk.

Stock splits, dividends, and other corporate actions.

Query Parameters

Split factor convention

factor is NEW shares per OLD share for that one event: 2.0 is a 2-for-1 forward split, 0.2 is a 1-for-5 reverse split. ratio is the same event written new:old (1:5). To put a price from BEFORE the event on the post-event basis, multiply it by 1/factor — SFY on 2024-10-02: factor 0.2, pre-event close 20.515 × 5 = 102.575 against the 102.84 print. This per-event factor is not the cumulative split_factor column on /prices, which already multiplies every later event together.

is_reverse is served from the factor and the raw price tape, never from a stored column: true exactly when factor < 1 and the raw price tape does not contradict it. direction_witness says what the raw price did across the date (tape_agrees, no_tape, below_witness_threshold, tape_contradicts, tape_silent); on the last two is_reverse is null with is_reverse_unavailable_reason, and likewise (factor_not_a_share_ratio) for a factor below 1 that is not a share ratio (a spin-off price adjustment) unless the tape itself agrees. ratio is null with ratio_unavailable_reason when the factor is not a simple share ratio.

Get ETF or mutual fund holdings.

{
  "data": [
    {
      "name": "Tesla Inc", …,
      "shares": 2521820.0,
      "market_value": 978567032.8,
      "percentage": 10.1478
    }, …
  ],
  "meta": {
    "fund_ticker": "ARKK",
    "report_date": "2020-10-30",
    "total_holdings": 49,
    "source": "sec_nport",
    "point_in_time": true, …
  }
}

Compare multiple entities on key metrics.

Parameters

Filters (all optional): fund_type (etf | mutual_fund), category, fund_family, asset_class, max_expense_ratio, q (name or ticker), status (active | dead | all — default active; pass dead or all to include closed and delisted funds), limit (default 50, max 200), offset.

Expense ratios are fractions — max_expense_ratio=0.001 means 0.10%, and every response echoes meta.expense_ratio_units. The filter compares exactly the expense_ratio each row shows — the gross (total annual operating) expense ratio, or the net where the filing carried no gross — for ETFs and mutual funds alike, so no returned row is above your cap; net_expense_ratio and net_expense_ratio_basis ride beside it, and meta.expense_ratio_basis names the rule. Unknown parameters are never silently ignored: they come back in meta.ignored_params.

For a full walk of the universe pass order=id and follow meta.next_cursor — stable keyset paging that will not skip or repeat rows.

A fund we do not hold says why. Every week we compare the SEC's list of registered fund share classes with the funds our price source lists. A fund symbol that does not resolve on /funds/<ticker> (and on the MCP fund tools, /funds/nav/batch and /resolve) carries universe_exclusion_reason and a plain sentence where that comparison has one — for example a share class the SEC lists under a new symbol, with held_as naming the symbol we hold it under. The bulk files' population rule (no minimum history) is stated in /export/schema.

{
  "data": {"funds": [
    {"ticker": "SPY", "name": "SPDR S&P 500 ETF Trust", "type": "etf",
     "category": "Large Blend", "expense_ratio": 0.000945,
     "total_assets": 624318000000.0}
  ]},
  "meta": {"count": 1, "has_more": true,
           "expense_ratio_units": "fraction (0.001 = 0.1%)"}
}

Returns family, category, expense ratios (gross, net, and net-of-acquired-fund-fees), yield, inception, AUM from SEC filings (where total_assets_scope is present it is the fund SERIES' net assets, shown on every share class of the series — never sum it across classes), plus style_box, synapse_category and N-CEN structural_flags (money-market, target-date, leveraged/inverse, fund-of-funds).

These classifications are our own. synapse_category, style_box and synapse_star_rating are computed in-house from SEC filings and our own prices. They are first-party — ours, computed from our own inputs, and not interchangeable with any industry-standard classification.

GET /funds/{identifier}/classification   portfolio weight breakdowns
GET /funds/{identifier}/distributions   dividends + capital gains
GET /funds/categories                   the category vocabulary + counts

Parameters

adjustment: raw (NAV only) · adjusted (default: our total-return series, the raw NAV times our own distribution and split factors; meta.nav_basis names the basis) · total_return / pit (a self-computed point-in-time total-return index) · total_return_reinvest (the reinvest-at-ex-NAV index a fund sponsor publishes, built from our adjusted chain's own distributions; meta.distribution_adjustment names the convention of every adjusted response). frequency=monthly resamples to month-end server-side. start, end, limit (default 10000, max 100000; 0 = all rows within your tier's historical window — Free 1 year, Developer 5 years, Quant full history), offset, order. meta.tier_clipped and meta.tier_floor_date report when that window truncated your result.

Windowing

The window anchors to the end you pinned. With start, limit bounds the earliest N rows in range and you page forward with meta.next_start. Without start, you get the most-recent N and page backward with meta.next_end. order only re-arranges the page — it never changes which rows are selected.

Exception: adjustment=total_return|pit|total_return_reinvest withholds both cursors. The PIT index re-bases at the filtered start, so following a cursor would splice two different bases; page that mode with offset instead.

{
  "data": [{"date": "2024-01-02", "nav": 100.0, "nav_raw": 100.0}],
  "meta": {"ordering": "date_asc", "window_anchor": "start",
           "next_start": "2024-02-15", "next_end": null,
           "has_more": true, "frequency": "daily"}
}

as_of=YYYY-MM-DD returns the newest report we hold that was public on or before that date — cut on filing date, not report date, so a backtest is not handed a portfolio before it was filed. limit default 500 (max 5000), offset.

Each position carries the issuer ticker, country, shares/par, market value, pct_of_nav, and sector — the issuer's synapse_sector (first-party, derived from the issuer's SEC SIC code) for equities, a deterministic bond segment for fixed income and cash, and null where we cannot classify the position honestly. Each position also carries issuer_synapse_id — our own id for the issuer, decided once per security and report date against the filer's own implied price — or null with issuer_unresolved_reason when we refuse to guess, and the ticker valid on the report date with its ticker_basis: journal (dated evidence), filer_reported (the fund's own filing), or current_carried_back (today's symbol carried back: nothing we hold dates it, and nothing shows it was assigned later). Where our journal or the issuer's own price tape shows today's symbol was assigned after the report date, ticker is null with ticker_unavailable_reason — never today's symbol. The first page also carries meta.sector_allocation, whole-portfolio weights, and meta.issuer_resolution (unresolved equity rows, their share of NAV and the reasons). Fixed income and cash resolve to their own segments (Treasury, Agency, Corporate Bond, Municipal, Sovereign, Bank Loan, Cash) from the position's own N-PORT fields, so a bond fund gets a meaningful breakdown rather than one blob; only positions we genuinely cannot classify roll into Unclassified, keeping the weights a true fraction of NAV.

Units differ between the two holdings endpoints — do not copy values between them. Here pct_of_nav is a fraction (0.101478 = 10.1478%). The legacy /holdings/{identifier} returns the same quantity as percentage, multiplied by 100 (10.1478).

{
  "data": [{"name": "Tesla Inc", …, "issuer_unresolved_reason": null,
            "shares_or_par": 2521820.0, "market_value": 978567032.8,
            "pct_of_nav": 0.101478, …},
           {"name": "Invitae Corp", "issuer_synapse_id": null,
            "issuer_unresolved_reason": "no_ingest_link", "pct_of_nav": 0.071785, …}, …],
  "meta": {"report_date": "2020-10-30", "filing_date": "2020-12-28",
           "point_in_time": true, "total_holdings": 49,
           "sector_allocation": […], "issuer_resolution": {…}, …}
}

Returns, volatility and max drawdown are decimals (0.12 = 12%; max_drawdown is negative, so -0.34 is a 34% drawdown). Sharpe is a plain dimensionless ratio, not a percentage. expense_percentile is a fraction 0–1 within category, where lower is cheaper.

synapse_star_rating is our own: the within-category percentile of the Sharpe ratio from our NAV history. It is a first-party rating — ours, computed from our own data, and not interchangeable with any industry-standard score. It is honestly null for young funds and thin categories — meta.coverage tells you which, so render “—” rather than zero. A fund with no ratings row at all returns data: null and meta.available: false (with no coverage block) — check that first.

Use POST /funds/ratings/batch to fetch many funds in one call.

Parameters: action_type, limit (default 100, max 500), offset.

Splits are served only when arithmetically verified against the raw price series — a real 1-for-N reverse makes the per-share value jump about N×. Regex or model confidence alone is never enough. That is a deliberate precision floor: recall is bounded by that series' coverage, so a real split we cannot verify is withheld rather than served wrong.

Ratios are (ratio_num, ratio_den) = (new, old) shares; a reverse split is ratio_num < ratio_den. Today only splits are extracted as structured actions. Liquidations, mergers and name/ticker/fee changes exist so far as captured raw filings and are not yet in this feed.

Filters

Required — at least one of ticker (issuer) or insider (CIK, or a name). Optional: code · is_10b5_1 · start / end · limit (default 50, max 200) · offset.

Transaction codes

The common ones: S open-market sale · P open-market purchase · A grant or award · M option exercise · F shares withheld for tax · G gift · C conversion. Other SEC codes appear in the data and are returned unfiltered; the parameter accepts any single letter and is not validated against a whitelist.

Two things that will bite you

start/end and the ordering apply to transaction_date — the trade date, not filing_date, the date the market learned of it. For a point-in-time study, filter on the filing_date field in the returned rows.

Rows are newest-first and there is no order parameter — the opposite of /prices and /funds/{id}/nav, which are oldest-first. Sort before computing anything sequential.

is_10b5_1 is tri-state: true, false, or null. Null is honest and means the SEC checkbox did not exist for that filing — it is never silently reported as false. The flag was introduced in 2023, so it is null for essentially everything before then. It is declared at the filing level and denormalized onto every row of that form — it tells you the filing asserted Rule 10b5-1(c) reliance, not that this specific line did.

Current beneficial ownership of non-derivative (Table I) positions only — options and RSUs are not included. One row per (insider, security class, direct/indirect, nature of ownership): someone holding common stock directly, through a trust and through an LLC appears as three rows, and every row carries that insider's total for the issuer in insider_total_shares_owned (the sum of their rows on today's share basis). A row the rule supersedes — the same holding re-titled or re-described in a later filing — is not summed and is listed only with include_superseded=true. Ordered by shares_owned descending, limit default 100 (max 500).

shares_owned is a raw share count, not a percentage of the company. as_of is per-row staleness — the transaction date of the most recent non-superseded filing for that position, falling back to period-of-report then filing date. It is a trade date, not a query date. This endpoint is current-state only; it has no as_of parameter.

IPO lock-up expiry calendar extracted from SEC 424B4 final prospectuses — the dates on which insider shares become sellable. The lock-up period is model-extracted from the prospectus body and every row carries extraction_confidence; expiry = prospectus date + lock-up days. Coverage is recent IPOs with live or upcoming lock-ups.

as_of=YYYY-MM-DD (default today), limit (default 0 = the full book, max 5000), offset.

This route rejects unknown parameters with a 400 rather than ignoring them, which is stricter than the rest of the API. Two consequences: authenticate with the X-API-Key header (a ?api_key= query parameter is a 400 here), and ?envelope=false is rejected as unrecognized — send Accept: application/json+raw instead if you want an unenveloped response here.

weight is a fraction (0.002914 = 0.2914%) and is the weight at addition, not a live weight. It is populated for SD2000 only — SPX, NDX and DJI return weight: null and, despite meta.ordering = weight_desc, fall through to alphabetical ticker order.

GET /indexes lists every index price series we hold — US headline benchmarks and their total-return twins (for example SP500TR, the S&P 500 Total Return), equal-weight, S&P 500 and Composite 1500 sectors, strategy, volatility, commodity, bond, rates, currency and non-US equity indices — each with its family, the return basis we serve (index_kind and how it was decided), its total-return counterpart and depth, first date and rows. Filter with family, index_kind, q; fetch a series from the prices endpoint under its caret symbol (^SP500TR: the caret names the index); MCP agents call list_indexes. Its meta.membership (or ?view=membership) lists which symbols actually carry membership data, with each index's provenance. SD2000 is our own rules-based US small-cap index, reconstituted annually with real add and remove history; its membership is computed by our published rules from our own data, not taken from any third-party index.

{
  "data": [{"ticker": "ACLS", "synapse_id": "…", "weight": 0.002914,
            "added_date": "2021-06-25", "is_synthetic_added_date": false}],
  "meta": {"index_symbol": "SD2000", "asof": "2022-06-30",
           "ordering": "weight_desc"}
}

List all available economic series with optional category filter.

Treasury yield curve with the 2-year/10-year spread and an inversion flag. Yields and spread_2_10 are in percentage points.

{
  "data": {
    "date": "2020-03-16",
    "yields": {
      "3M": 0.24, "6M": 0.29, "1Y": 0.29,
      "2Y": 0.36, "5Y": 0.49,
      "10Y": 0.73, "30Y": 1.34
    },
    "spread_2_10": 0.37,
    "inverted": false,
    "pit_basis": "market_observed",
    "pit_bases": ["market_observed"],
    "pit_basis_note": "Treasury constant-maturity yields are market-observed and published the same day; they carry no revision vintages."
  },
  "meta": { "source": "economic_observations", "cached": false }
}

A date inside our stored daily curves (recent dates, or no date) is answered from the stored row instead: data is a one-element list, the flag is is_inverted, the 3-month/10-year spread rides beside it as spread_3m_10y, and pit_basis is captured.

Aggregated market indicators for a specific date. Perfect for backtesting context.

Rate Limit Headers