# Freshness and availability

> What meta.status means, why a dataset can be empty or answer terms_unread, and how revisions are kept as versions.

Page: https://docs.aggre.org/concepts/freshness · Section: Concepts · All pages: https://docs.aggre.org/llms.txt

Aggre reads each source from its publisher on a schedule and serves what it stored. Three mechanisms tell you what you are looking at; none of them is hidden behind a status page you have to find.

## `meta.status` {#status}

| Value | Meaning |
|---|---|
| `ok` | The data is within the dataset's freshness window. |
| `stale` | Aggre's last successful read is older than the window for this dataset (the window is stated per route: 5 minutes for latest tickers, 24 hours for funding rates, 72 hours for several daily sets, 14 days for standard-form contracts, and so on). The rows are still the last ones read. |
| `empty` | Nothing matched your filters, or nothing has ever been read for this dataset. |

`stale` is judged on the newest data, and only when you did not pin the view: a request with `to`, `date` or `as_of` is a historical view and is not reported stale. `meta.fetchedAt` and `meta.dataDate` give you the dates to judge for yourself.

## The terms gate {#terms}

A source is read, and served, only after a person has read the publisher's terms and recorded that (`terms_read_on`). Until then:

- the collector for that source does not run, and
- on families that gate at the route (health, on-chain, standard-form contracts, derived macro series over entity files), the API answers `503 terms_unread` rather than serving rows whose licence is unknown; on others, `license` and `attribution` are `null` and the response says "Terms not read".

`503 terms_unread` is not transient: retrying does not help. It means the dataset exists and its route works, but its source is not yet switched on.

## Which datasets have data {#availability}

Do not infer availability from the list of routes. Ask the API:

- `GET /v1/datasets` lists every dataset and where to read it.
- A normal call tells you the state in `meta.status` (`ok`, `stale`, `empty`) or with `503 terms_unread`.
- For a dataset you depend on, store `meta.fetchedAt` and alert on `stale`.

Sources are switched on one at a time as their terms are recorded, so a dataset that is empty today may hold data tomorrow. These pages describe what a dataset **is** and how it behaves when it holds data.

## Revisions are versions {#versions}

Publishers revise numbers. Aggre never overwrites: a changed value is stored as the next `version` and the earlier ones are kept.

- Macro observations and Taiwan monthly revenue and statements: the default (`versions=latest`) returns the highest version per period; `versions=all` returns every version; `as_of=<Unix ms>` returns each period **as Aggre knew it then** (the highest version first seen at or before that instant), which is what you need for honest backtests.
- `revision` is the publisher's own label (`advance`, `preliminary`, `revised`, `final`, ...) and is `null` when the publisher states none. It is never invented.
- Candles carry a `version`; a higher version replaces a lower one, and only confirmed bars are stored.

## Removed records {#removed}

When a source stops listing a record (a repealed statute, a delisted sanctions entry), Aggre keeps the last content it saw and marks it removed (`removed_on`) instead of deleting it. Lists hide removed records by default; `include_removed=true` (statutes, contracts) or `removed=include|only` (name lists) shows them, and `updated_since` plus `include_removed` lets you track both changes and disappearances.