Latest or dated ETF snapshot

Single ETF snapshot at the latest cycle (default) or at a specific calendar date via ?date=YYYY-MM-DD. Returns the full payload: pricing (nav, price, premium/discount), fund characteristics (AUM, expense ratio, yields), top-10 holdings sample, sector weightings (both raw + canonical), asset-class and country exposure, and trailing returns. Returns 410 Gone when the symbol is flagged as delisted_candidate by the upstream cycle, and also when its universe row carries removed_at - the fund was delisted and the date in the response body is its own Form 25, the exchange's notice of removal from listing. Those rows stay listed by /etf/snapshot/universe with status removed rather than vanishing, so a client that integrated against a covered symbol gets a dated explanation instead of unknown_symbol.

The canonical snapshot is rebuilt purely from Tier S sources (regulated-exchange price + SEC NPORT-P holdings), with no commercial aggregator in the chain. A field with no source yet is returned as null and tagged in the internal _sources.deferred map. That set has SHRUNK: nav/aum_usd and expense_ratio_pct/yield_dividend_pct/yield_distribution_pct/inception_date are now POPULATED from SEC filings, and premium_discount_pct is derived from the SEC NAV against the regulated-exchange price above. All are re-deferred only PER SYMBOL when that symbol's own input is missing. The following exceptions are deliberate rather than gaps: premium_discount_pct is null for a daily-reset leveraged or inverse fund because its NAV is period-stale; premium_discount_pct is also null where the fund's share basis moved by a split that the filing we read for it does not carry, so the NAV and the price are on different bases and a ratio between them would be the split factor rather than a premium (that symbol's deferred reason names the filing and the split's effective date); and inception_date is null wherever the filing states none for that fund. Still deferred for every symbol: returns_* and fifty_two_week_high/fifty_two_week_low.

When price is null but a NAV is available, an additive price_proxy block surfaces the NAV as an explicitly-stale proxy (basis = nav with an as_of SEC-filing date that can be months old and a note disclaiming a current quote). price itself stays null - the proxy is never presented as a live quote. The block is absent when price is present or when nav is also null.

price is also null when a quote WAS read and refused because nothing in it establishes that it is current. Five reasons, named in _sources.deferred.price with the upstream instant appended when one can be stated: no_trade_time (the feed's own placeholder instead of a last-trade time), last_trade_stale and quote_stale (the feed's timestamps are past the ceiling), quote_not_refetched (our own ingest has not re-read the symbol), and freshness_unverifiable (timestamps present but unreadable). On a refusal the _sources.price entry is ABSENT - it exists only for a published value - so read deferred.price, not a missing as_of, to detect the case. When price IS published, _sources.price.as_of is the feed's own timestamp in UTC (when it last rebuilt that quote), never our download time, which rides beside it as fetched_at; as_of can be null when no upstream instant is available, and it does not fall back.

Responses

🟢200OK

application/json

Latest or dated ETF snapshot payload.

Bodyapplication/json

Example

{
    "data": {
        "symbol": "SPY",
        "name": "string",
        "category": "string",
        "snapshot_date": "2026-05-19",
        "snapshot_taken_at": "string",
        "manifest_version": "string",
        "nav": 0,
        "price": 0,
        "price_proxy": {
            "value": 0,
            "basis": "nav",
            "as_of": "string",
            "method": "string",
            "note": "string"
        },
        "premium_discount_pct": 0,
        "fifty_two_week_high": 0,
        "fifty_two_week_low": 0,
        "aum_usd": 0,
        "expense_ratio_pct": 0,
        "expense_ratio_total_pct": 0,
        "yield_dividend_pct": 0,
        "yield_distribution_pct": 0,
        "inception_date": "string",
        "top_holdings": [
            {
                "symbol": "string",
                "name": "Apple Inc",
                "weight_pct": 7.21,
                "sector": "string",
                "asset_class": "string"
            }
        ],
        "sector_yahoo_raw": [
            {
                "label": "Information Technology",
                "weight_pct": 28.5
            }
        ],
        "sector_canonical": [
            {
                "sector": "technology",
                "weight_pct": 28.5
            }
        ],
        "asset_class_weightings": {
            "equity_pct": 0,
            "bond_pct": 0,
            "cash_pct": 0,
            "other_pct": 0
        },
        "country_weightings": [
            {
                "country_code": "US",
                "weight_pct": 99.5
            }
        ],
        "returns_1m": 0,
        "returns_ytd": 0,
        "returns_1y": 0,
        "returns_3y": 0,
        "returns_5y": 0,
        "returns_10y": 0,
        "data_source": "string",
        "license_attribution": "string",
        "_sources": {
            "property1": "string",
            "property2": "string"
        }
    },
    "meta": {
        "endpoint": "/api/v1/fred/us/cpi",
        "data_time": "2026-04-16T14:30:00Z",
        "response_time": "2026-04-16T14:30:12Z",
        "provider": "Sugra API v1.0.1",
        "data_age_days": 0,
        "source": "string",
        "attribution": "string",
        "fallback_used": true,
        "fallback_chain": [
            "string"
        ],
        "cached": true,
        "stale": true,
        "stale_since": "string",
        "period": "string",
        "notes": "string"
    }
}

🟠401Unauthorized

🟠422Parameter Error

🟠429

🔴500Server Error

🔴503Service Unavailable

Latest or dated ETF snapshot

Request

Request Code Samples

Responses