Freshness - StockContext

Read freshness before you display, cache, or summarize a result. It tells you how current the data is and whether the endpoint even applies to this symbol. The five values are a closed set.

Value	Meaning	What an agent does
`intraday`	A live intraday quote or market-context figure is included.	Use it for current context. Do not present it as exchange-grade real-time or as an execution price.
`end_of_day`	Last complete end-of-day close, statement, filing, dividend, or historical series.	Use it as the current value for fundamentals, filings, history, and after-hours market context.
`stale`	A cached fallback older than the normal window was served.	Show it with a “as of `as_of`” caveat; re-request if you need fresher.
`degraded`	A partial response: one source path was slow, limited, or unavailable.	Use what is present, keep `null`s and reasons, and avoid conclusions that depend on the missing block.
`unsupported`	The endpoint does not apply to this symbol or asset type.	Show `reason`; do not re-request the same endpoint for the same symbol.

`as_of`

as_of is the timestamp the payload represents, in UTC ISO-8601 (2026-06-05T14:19:06Z).

When the source supplies a timestamp, as_of is that upstream timestamp.
When it does not, as_of is the moment StockContext generated the response.

Put as_of in any answer or label that asserts a current value, and do not silently swap it for local time:

AAPL snapshot as of 2026-06-05T14:19:06Z, freshness: intraday.

`market_status`

market_status is "open" or "closed", computed from request time against the regular NYSE/NASDAQ session: 09:30–16:00 ET, Monday through Friday, excluding US market holidays (about ten per year: New Year’s Day, MLK Day, Presidents’ Day, Good Friday, Memorial Day, Juneteenth, Independence Day, Labor Day, Thanksgiving, Christmas). A weekday holiday reads "closed" even during what would be session hours. It is a session hint, not an exchange operations feed. Do not read halts, auction state, venue status, or execution readiness into it. The stateless lookup routes /v2/search and /v2/coverage omit it entirely.

Detecting staleness yourself

freshness is the headline; as_of and cache_age_seconds are the precise instruments. cache_age_seconds is how many seconds the served payload has been cached: 0 means it was computed on this request, and a large value means a cached read (response model owns this field). To decide whether a number is current enough for your product, compare against as_of and cache_age_seconds rather than guessing from freshness alone:

Python
TypeScript

staleness.py

from datetime import datetime, timezone

def is_stale(data: dict, max_age_seconds: int) -> bool:
    # Cache age is the direct signal: how long this payload has been held.
    if data.get("cache_age_seconds", 0) > max_age_seconds:
        return True
    # as_of guards against an old upstream timestamp behind a fresh cache.
    as_of = datetime.fromisoformat(data["as_of"].replace("Z", "+00:00"))
    age = (datetime.now(timezone.utc) - as_of).total_seconds()
    return age > max_age_seconds

staleness.ts

function isStale(data: {
  as_of: string;
  cache_age_seconds?: number;
}, maxAgeSeconds: number): boolean {
  if ((data.cache_age_seconds ?? 0) > maxAgeSeconds) return true;
  const ageSeconds = (Date.now() - Date.parse(data.as_of)) / 1000;
  return ageSeconds > maxAgeSeconds;
}

Pick max_age_seconds by data family: seconds-to-minutes for an intraday quote, hours for fundamentals (a real /v2/fundamentals read returned cache_age_seconds: 16096, about four and a half hours, which is normal, since statements do not move intraday).

Unsupported is a 200, not an error

When an endpoint does not apply, you get HTTP 200 with freshness: "unsupported" and a machine-readable reason. This is a live /v2/valuation for SPY:

GET /v2/valuation?symbol=SPY, HTTP 200

{
  "data": {
    "symbol": "SPY",
    "asset_type": "etf",
    "freshness": "unsupported",
    "reason": "etf_no_valuation_multiples",
    "as_of": "2026-06-05T14:19:10Z",
    "market_status": "open",
    "cache_age_seconds": 0
  }
}

The reasons are stable strings you can branch on: etf_no_valuation_multiples, symbol_does_not_file_us_domestic_forms, not_applicable_for_etf. Retrying will not change the answer; which families return unsupported for which assets is documented in coverage and gaps.

When to re-request

freshness controls retry behavior for successful responses; error.retryable controls it for failures.

stale: re-request only if your product needs fresher data right now.
degraded: re-request only when the missing block is the one you need.
unsupported: do not re-request without changing the endpoint or the symbol.
For RATE_LIMITED, UPSTREAM_UNAVAILABLE, and AUTH_UPSTREAM_UNAVAILABLE, follow error.retryable and Retry-After per the error codes.

​as_of

​market_status

​Detecting staleness yourself

​Unsupported is a 200, not an error

​When to re-request

`as_of`

`market_status`

Detecting staleness yourself

Unsupported is a 200, not an error

When to re-request