Concepts

Freshness and availability

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

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

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#

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#

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#

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#

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.