Documentation Index
Fetch the complete documentation index at: https://docs.alterscope.org/llms.txt
Use this file to discover all available pages before exploring further.
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": []
}
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.
See also
