> ## 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.

# Freshness & Quality

> Every Alterscope response states how fresh and how trustworthy its numbers are, as a first-class field.

A risk number is only useful if you know how much to trust it. Alterscope answers that on **every response**, not in a separate report: each wrapped API response carries a small metadata block that states how fresh the underlying data is and whether it passed an automated quality check. Staleness and degradation are surfaced as data, never hidden.

## Two questions, answered on every response

**How fresh is this?** Each response reports when the data was computed, how old it is, how often it refreshes, and a plain status:

| Status     | Meaning                                                              |
| ---------- | -------------------------------------------------------------------- |
| `realtime` | Computed within the last few seconds.                                |
| `fresh`    | Within the expected refresh window.                                  |
| `stale`    | Older than two refresh windows — treat with caution.                 |
| `unknown`  | The data is event-driven, so a fixed freshness window doesn't apply. |

**Is it fit to act on?** Each response also carries a quality verdict derived from the platform's confidence in the answer and whether any inputs were degraded:

| Verdict | Meaning                                                                                              |
| ------- | ---------------------------------------------------------------------------------------------------- |
| `pass`  | High confidence, no degraded inputs — safe to rely on.                                               |
| `warn`  | Moderate confidence or a degraded input — usable, but worth a second look for high-stakes decisions. |
| `fail`  | Low confidence — do not rely on it unsupervised.                                                     |

When a verdict is `warn` or `fail`, the response names exactly which fields were degraded, so there's no guessing about what to trust.

## Why this matters

* **No silent staleness.** A number that's an hour old looks identical to a fresh one unless the response tells you — so it does. This is the single most common failure mode in DeFi risk data, and it's designed out here.
* **Auditable.** The freshness timestamp and quality verdict are part of the response payload, so they can be logged and reviewed after the fact alongside the decision they informed.
* **Machine- and human-readable.** Automated systems branch on the verdict; people read the same signal in plain language.

## How staleness is detected, per source

Freshness is not one global timer — it is measured against the expected update cadence of whichever source backed the answer. That source is named on the response itself (`meta._agentic.sources`), so the freshness status is always tied to its origin. How each source is detected:

| Source                          | How staleness is decided                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Oracle feeds**                | Each feed is registered with an **expected heartbeat**. If the latest observed update is older than that heartbeat, the feed is marked `stale` — the staleness check is mandatory, never skipped. In a multi-feed oracle, if *any* leg cannot be verified, the whole oracle is escalated to `unknown` rather than reported as fresh. See [Oracle classification](/trust/methodology/oracle-classification). |
| **Price & time-series history** | Freshness is the age of the most recent stored data point against the feed's cadence, sourced from the [archive node and time-series store](/trust/data/provenance).                                                                                                                                                                                                                                        |
| **Knowledge graph**             | Graph metrics and communities are **batch-computed** and can lag live state by up to their refresh interval; every response reports its last-computed time, so a graph-derived number always carries its own age.                                                                                                                                                                                           |
| **Cached endpoints**            | Endpoints with a fixed cache (for example, the [data manifest](/trust/data/coverage-and-gaps) at five minutes) report the true cache age in `age_seconds` — a non-zero age means the snapshot is genuinely that old.                                                                                                                                                                                        |

The quality verdict then layers on top: it reflects the platform's confidence and whether any input was degraded — so a response can be `fresh` but `warn` if one of its inputs was incomplete.

## Where the data comes from

How the underlying data is sourced and normalized — connectors, archive node, time-series store, knowledge graph, and indexers — is covered in [Data provenance](/trust/data/provenance). What is covered, and where the gaps are, is in [Coverage & gaps](/trust/data/coverage-and-gaps).

For the developer-facing field reference and agent-consumption guidance, see [Response envelope](/develop/concepts/response-envelope) and [Agentic envelope](/develop/concepts/agentic-envelope).