> ## 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 & Staleness

> How the agentic envelope reports data freshness and a quality verdict, and how a client should react to each.

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

```json theme={null}
"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

```json theme={null}
"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](/trust/methodology/oracle-classification) for that model.

## See also

* [Response envelope](/develop/concepts/response-envelope) — the full `{ data, meta }` contract.
* [Agentic envelope](/develop/concepts/agentic-envelope) — consuming these signals as an automated agent.
* [Errors](/develop/get-started/errors) — retry guidance for failed requests.