Skip to main content

Freshness

Freshness tells a consumer how recently a source confirmed a value. Each inventory sets a freshness budget per field: a value is fresh while its last confirmation is younger than the budget, and stale after that. Census reports freshness and still returns stale values; the consumer decides what to do with them.

Entity freshness​

Every entity in a list or lookup has a freshness block:

"freshness": { "state": "stale", "oldest_confirmed_at": "2026-10-25T08:10:00.000000Z" }
  • state is stale if at least one non-null resolved value of the entity, or its location, is stale. Otherwise it is fresh.
  • oldest_confirmed_at is the oldest confirmation time among those values.

Value freshness​

With detail=full, each observation has confirmed_at and freshness:

"status": { "state": "value", "value": "active", "outcome": "mapped",
            "original": "in-service", "path": "status.value",
            "confirmed_at": "2026-10-25T08:59:12.000000Z", "freshness": "fresh" }

The budget of each field is in the inventory definition, GET /v1/inventories/{inventory}, in seconds: freshness_default_secs, and freshness for fields with their own budget.

When a value is confirmed​

  • A successful full refresh confirms every value it reads, including values that did not change.
  • A webhook confirms the values of the object Census fetched for it.
  • A failed refresh confirms nothing.

Freshness, completeness and priority are separate​

A stale value does not make an inventory incomplete, and it keeps its source's priority: Census does not replace it with a fresher value from a lower-priority source.