Alterscope Developer API

Every agentic response answers two questions before you act on it: how fresh is this data? (meta._agentic.freshness) and is it fit for automated use? (meta._agentic.quality_gate). Both are first-class fields, so a client can branch on them instead of guessing.

Freshness

"freshness": {
  "computed_at": "2026-05-26T12:00:00Z",
  "age_seconds": 4,
  "update_cadence_seconds": 60,
  "next_update_at": "2026-05-26T12:01:00Z",
  "status": "realtime",
  "should_retry": false,
  "retry_after_seconds": null
}

Field	Meaning
`computed_at`	When the underlying data was computed (UTC).
`age_seconds`	How old the data is, in seconds.
`update_cadence_seconds`	How often this data is expected to refresh.
`next_update_at`	When the next refresh is expected (when a cadence is known).
`status`	The freshness classification — see below.
`should_retry`	Whether the client should retry to get fresher data.
`retry_after_seconds`	Suggested wait before retrying, when `should_retry` is true.

Status values

status is derived from age_seconds relative to update_cadence_seconds:

Status	When	How to react
`realtime`	Age under 10 seconds.	Act on it directly.
`fresh`	Age under twice the update cadence.	Act on it; within the expected refresh window.
`stale`	Age at or beyond twice the update cadence.	Treat with caution; consider retrying or surfacing the age to a human.
`unknown`	No update cadence is defined for this data.	Freshness can’t be determined — don’t assume it’s current.

Quality gate

"quality_gate": {
  "verdict": "pass",
  "reason": "…",
  "degraded_fields": []
}

The verdict summarizes whether the response is fit for unsupervised automated use, from confidence (0.0–1.0) and whether any fields are degraded:

Verdict	When	How to react
`pass`	Confidence ≥ 0.70 and no degraded fields.	Safe to act on automatically.
`warn`	Confidence between 0.50 and 0.70, or one or more degraded fields.	Act with caution; check `degraded_fields` and `reason`.
`fail`	Confidence below 0.50.	Do not act unsupervised — fall back to a cached or alternative source, or escalate to a human.

degraded_fields lists which fields drove a warn/fail; reason is a human-readable explanation. Per-field confidence and provenance are available in meta._agentic.field_confidence. The verdict is also returned in the X-Quality-Gate header.

Not the same as oracle staleness

The envelope freshness.status above describes the response data. It is distinct from the oracle-feed staleness vocabulary (fresh, approaching_stale, stale, unverifiable, not_applicable) returned by the oracle classification endpoints, which describes how stale a specific price feed is. See Oracle classification for that model.

Freshness & Staleness

Freshness

Status values

Quality gate

Not the same as oracle staleness

See also

​Freshness

​Status values

​Quality gate

​Not the same as oracle staleness

​See also

Freshness

Status values

Quality gate

Not the same as oracle staleness

See also