Skip to main content

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. Every product list and detail object includes inventory_retrieved_at so an application can display inventory freshness without interpreting response-level diagnostics. It is the most recent successful Nektir inventory retrieval for that product in the requested store or radius scope. For an unscoped product search, it is the latest retrieval across that product’s published store observations. It is null when the product has not been checked. Failed refresh attempts do not advance it, and it must not be presented as the time Utah DABS changed its data. For a store or radius browse, use each product’s timestamp rather than presenting one timestamp for the whole result set. Inventory is collected sequentially, so products in the same response can legitimately have different retrieval times.

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 a compact coverage summary by default. Inspect:
  • status
  • candidate_product_count
  • checked_product_count
  • unchecked_pair_count
  • retrieved_at_min and retrieved_at_max
Add include=coverage_details when diagnostics need scope_store_count, expected_pair_count, within_policy_product_count, and the positive, zero, and row-absent pair counts. The denominator is always candidate products after non-inventory filters multiplied by reviewed stores in scope. Retrieval policy definitions live in /v1/meta rather than being repeated in every response. Sequential collection naturally produces mixed observation times. A store or radius response can therefore be useful and still have partial coverage.
When coverage is partial or none, an empty filtered result does not mean that no matching stock exists.

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.