Funds & ETFs

Derived per-ETF filing-cadence net flow estimate (creation/redemption proxy)

Changed on

Derived endpoint that computes per-ETF net flow estimates for one ETF over the requested lookback window by walking the ETF snapshot history and emitting ONE period per CHANGE of the SEC-derived (aum_usd, nav) pair. Formula per period: net_flow = Δ(shares_outstanding) × to_nav where shares_outstanding = aum_usd / nav, from_date is the last snapshot carrying the old pair and to_date is the first snapshot carrying the new pair. This is the standard ETF creation/redemption proxy used by analysts; results are an ESTIMATE, not ICI-authoritative numbers. Snapshot aum_usd/nav derive from SEC filings (NPORT-P monthly, 485BPOS annual) and are constant between filings, so flows are reported on FILING CADENCE, not per calendar day (the previous per-day contract read 0.0 on every non-filing day). Consecutive snapshots with unchanged (aum_usd, nav) are a single plateau and produce NO entry. When fewer than 2 distinct plateaus exist in the window the response is 200 with period_flows=[] and total_net_flow_dollar_estimate=null (honest 'no change observed', not an error) - and the BODY says why: reason (single_filing_plateau / no_computable_shares), plateaus_observed, and the backing filing's rep_pd_date + accession. Days where the snapshot blob is missing are silently skipped; plateaus span across missing dates. Use case: sector rotation detection, a per-ETF accumulation signal, complemented by ICI aggregate at /etf/flows/aggregate. BREAKING: this endpoint replaced the per-calendar-day series contract with filing-cadence period_flows, and renamed the days query param to lookback_days. The old days param is SILENTLY IGNORED (FastAPI drops undeclared query params; it is not rejected) - a mid-migration client sending ?days=30 gets 200 with the default lookback window. The body also carries sec_monthly_flows - the fund's OFFICIAL monthly creations and redemptions from SEC Form NPORT-P Part B item B.6 (sales / reinvestment / redemption / net, USD, oldest month first, with rep_pd_date + accession) - next to the estimated period_flows; null with sec_monthly_flows_reason for 10-K filers, for symbols without an NPORT-P blob, and for blobs stored before B.6 parsing.

get/api/v1/etf/{symbol}/flows

Request

  • Base URL: https://sugra.ai
  • URL: https://sugra.ai/api/v1/etf/{symbol}/flows
  • Auth: API key in header x-api-key

Path parameters

symbolstring required

ETF ticker.

Example:SPY

Query parameters

lookback_daysinteger

Lookback window in days (1..90, default 90). Bounded by the 90-day ETF snapshot retention - a wider window can never hold more data (dated snapshots are swept after 90 days). Out-of-range returns 400. NOTE: the former param days is no longer declared, so it is silently ignored, not rejected.

Response

Per-symbol derived filing-cadence period flows + total, plus the official NPORT-P monthly flows.

Example response

{
  "data": {
    "symbol": "SPY",
    "lookback_days": 90,
    "period_flows": [
      {
        "from_date": "2026-04-30",
        "to_date": "2026-05-31",
        "from_nav_method": "monthly_derived",
        "to_nav_method": "monthly_derived",
        "from_shares_as_of": "2025-05-31",
        "to_shares_as_of": "2025-05-31",
        "from_aum_source": "sec_nport",
        "to_aum_source": "sec_nport",
        "basis_kind": "nport_refresh",
        "split_ratio_applied": 0.2,
        "split_events_applied": [
          {
            "date": "2024-11-07",
            "kind": "reverse",
            "ratio": 0.2,
            "text": "1-for-5 reverse stock split"
          }
        ],
        "split_adjustment_reason": "filing_date_unknown"
      }
    ],
    "reason": "single_filing_plateau",
    "rep_pd_date": "2026-03-31",
    "accession": "0001067839-26-000024",
    "sec_monthly_flows": [
      {
        "month": "2026-05",
        "sales": 2939442051.02,
        "redemption": 4505646790.68,
        "net": -1566204739.66,
        "rep_pd_date": "2026-05-31",
        "accession": "0002071691-26-017348"
      }
    ],
    "sec_monthly_flows_reason": "blob_predates_monthly_flows"
  },
  "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": 8.532,
    "source": "sugra_crypto",
    "attribution": "Short interest and Reg SHO daily short volume data is owned by and sourced from FINRA (Financial Industry Regulatory Authority).",
    "fallback_chain": [
      "sugra_crypto",
      "sugra_finance"
    ],
    "stale_since": "2026-09-08T12:00:00Z",
    "period": "2026-Q1",
    "notes": "the UKMTO report behind these counts is dated 2026-08-21 and is 11 days old"
  }
}

Changes