> ## Documentation Index
> Fetch the complete documentation index at: https://api.nektir.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Freshness and coverage

> Use retrieval and publication metadata without overstating upstream freshness.

## Three different times

* `source_updated_at` is when Utah DABS says its data changed. It remains `null` when the source does not provide that information.
* `retrieved_at` is when Nektir successfully observed the upstream response.
* `published_at` is when the validated observation became visible through the API.

A recent retrieval does not prove that the source data was recently updated. An unchanged response does not establish the upstream refresh cadence.

## Retrieval policy

When a response says an observation is within policy, that policy concerns the age of our successful retrieval—not the unknown age of Utah DABS data. Policy identifiers and maximum ages are published in `/v1/meta`.

## Coverage

Inventory-scoped responses include the exact candidate-product and reviewed-store denominator used for coverage. Inspect:

* `expected_pair_count`
* `reported_positive_pair_count`
* `reported_zero_pair_count`
* `row_absent_pair_count`
* `unchecked_pair_count`
* `retrieved_at_min` and `retrieved_at_max`

Sequential collection naturally produces mixed observation times. A store or radius response can therefore be useful and still have partial coverage.

<Warning>
  When coverage is `partial` or `none`, an empty filtered result does not mean that no matching stock exists.
</Warning>

## Catalog and directory presence

Product and store responses distinguish source presence from inventory. Collection rows carry a compact `catalog_presence` or `directory_presence` summary; detail endpoints include the complete lifecycle record.

* `present` means the entity appeared in the latest complete validated source snapshot.
* `suspect_missing` means it was absent, but no retirement conclusion has been made.
* `retirement_review_required` means it was absent from at least three complete snapshots spanning at least 14 days and needs an owner decision.
* `reviewed_retired` means the absence was explicitly reviewed. Last-known-good data remains available.

An incomplete or failed source run cannot advance these states. Missing presence never means zero inventory, and a reappearing entity returns to `present` automatically.