API/docs feedback: snapshot day/min zero-filled as unset (not documented)

[jsolly]

Context

This is product/API + docs feedback for the Massive REST stocks snapshot (not an SDK bug). Filing here per Massive’s data-discrepancy guidance (support email + GitHub). Also emailed support@massive.com.

Summary

After the documented daily snapshot clear (3:30 AM EST), GET /v2/snapshot/locale/us/markets/stocks/tickers/{ticker} often returns day and min objects with all numeric fields set to 0 and updated: 0 when there is no current session activity, instead of omitting those objects (or using JSON null).

This is surprising because:

1. Single ticker snapshot docs never document 0 as “unset”
2. Aggregates / missing aggregates KB omit bars when there are no eligible trades
3. In the same snapshot payload, lastTrade / lastQuote are omitted when unavailable

Clients using nullish coalescing (??) treat 0 as a real price and never fall through.

Repro

• Endpoint: GET /v2/snapshot/locale/us/markets/stocks/tickers/CHKP
• Observed: 2026-08-10T11:42:00Z (US premarket)
• request_id: 13acbb2342e8b650464494f4099af50a
• status: OK

{
  "ticker": {
    "ticker": "CHKP",
    "todaysChangePerc": 0,
    "todaysChange": 0,
    "updated": 0,
    "day": { "o": 0, "h": 0, "l": 0, "c": 0, "v": 0, "vw": 0 },
    "min": { "av": 0, "t": 0, "n": 0, "o": 0, "h": 0, "l": 0, "c": 0, "v": 0, "vw": 0 },
    "prevDay": {
      "o": 126.15, "h": 127.84, "l": 124.43, "c": 127.82,
      "v": 582977.1251, "vw": 126.9216
    }
  },
  "status": "OK",
  "request_id": "13acbb2342e8b650464494f4099af50a"
}

Liquid names with premarket prints (e.g. NVDA) populate min.c with a real price while day.* can still be zero before RTH — so zeros act as sentinels for “no bar yet,” not as a $0 trade.

Request

1. Document that snapshot day/min numeric zeros (and updated: 0) mean “no current session aggregate,” not a traded price of $0.
2. Prefer omitting empty day/min (or null) for consistency with aggregates and omitted lastTrade/lastQuote.
3. If zero-fill must stay for compatibility, call it out explicitly in the snapshot docs.

Thanks!
John Solly (github@jsolly.com)

[jsolly]

Prior search (added after filing)

I should have documented this up front — apologize for filing before posting the search notes.

Searches run

• gh search issues --owner massive-com "snapshot"
• gh search issues --owner massive-com "snapshot day OR min OR zero OR null OR cleared"
• gh search issues --repo massive-com/client-js "snapshot"
• gh search issues --repo massive-com/client-python "snapshot"
• gh search issues --owner polygon-io "snapshot zero|null|cleared|prevDay"
• Web search for public discussions of snapshot day/min zero-fill / "updated": 0

Closest related issues (not duplicates)

Issue	Why related	Why not a duplicate
client-js#17 (closed) — weekend snapshot 404; staff: “Snapshot only works during market hours”	Same general “empty / unavailable snapshot outside full session” theme	Different symptom (HTTP 404 on weekend vs HTTP 200 with zero-filled day/min + valid prevDay in extended hours). Does not document zero-as-unset.
client-go#569 (open) — min.av typed as int but API returns float	Snapshot field semantics / OpenAPI accuracy	Type mismatch only; not about zero sentinels or docs for empty session bars.
client-js#72, #223	Snapshot TypeScript shape	Typo / missing fmv — unrelated to runtime zero-fill.

Docs already reviewed (also not duplicates)

• Single ticker snapshot — documents clear at 3:30 AM EST / repopulate from ~4:00 AM; does not say zeros mean unset.
• Missing aggregates KB — aggregates omit bars with no eligible trades (contrasts with snapshot zero-fill).

Conclusion

No existing open/closed issue found that asks to document or change the zero-filled day/min / updated: 0 sentinel behavior. Happy to close this as duplicate if maintainers know of an internal ticket or issue I missed.