> ## Documentation Index > Fetch the complete documentation index at: https://docs.getdialed.ai/llms.txt > Use this file to discover all available pages before exploring further. # Reference data status > Freshness of every shared reference data source and what is installed in each collection built from them — access rule, record shape, and the status vocabulary This endpoint reports the freshness of the shared number reference data: one entry per declared source, and one entry per derived collection built from those sources. Access follows one rule, and it is stricter than the admin gate used everywhere else: reads require **an admin role *and* the platform organization**. Every other caller — including an admin of a customer organization — receives `404`, never `403`. The `404` is deliberate: a `403` would confirm that a platform-wide reference surface exists, which is itself the disclosure. The operation is published here so that it carries a typed client, not because it is callable by a customer organization. | Method | Endpoint | Access | Success | | - | - | - | - | | `GET` | `/admin/reference/status` | Admin **and** platform organization | `200` — the status record below | ## The status record ```json theme={null} { "sources": [ { "id": "overlay_complexes", "cadence_seconds": 2592000, "mode": "scheduled", "last_success_at": "2026-09-08T09:04:11Z", "last_attempt_at": "2026-09-08T09:04:11Z", "age_seconds": 2246269.0, "status": "fresh", "drift": { "row_count_delta": 2, "changed_keys": 11 } }, { "id": "exchange_geography", "cadence_seconds": 2592000, "mode": "scheduled", "last_success_at": "2026-08-20T09:06:52Z", "last_attempt_at": "2026-10-04T09:06:48Z", "age_seconds": 3887708.0, "status": "stale", "drift": { "row_count_delta": -148, "changed_keys": 3104 } }, { "id": "zip_area_codes", "cadence_seconds": 31536000, "mode": "manual", "last_success_at": "2026-02-14T18:22:05Z", "last_attempt_at": "2026-02-14T18:22:05Z", "age_seconds": 20010235.0, "status": "fresh", "drift": { "row_count_delta": null, "changed_keys": null } }, { "id": "us_postal_codes", "cadence_seconds": 31536000, "mode": "scheduled", "last_success_at": "2024-11-08T09:03:40Z", "last_attempt_at": "2024-11-08T09:03:40Z", "age_seconds": 60048500.0, "status": "aging", "drift": { "row_count_delta": 0, "changed_keys": 0 } }, { "id": "ca_postal_codes", "cadence_seconds": 31536000, "mode": "manual", "last_success_at": null, "last_attempt_at": null, "age_seconds": null, "status": "failed", "drift": { "row_count_delta": null, "changed_keys": null } } ], "collections": { "ref__area_codes": { "live_snapshot_ids": ["snp_4b1f0c7a9d2e5831"], "swapped_at": "2026-09-08T09:11:02Z", "doc_count": 800 }, "ref__exchanges": { "live_snapshot_ids": [ "snp_4b1f0c7a9d2e5831", "snp_7c93ad04e15b6620" ], "swapped_at": "2026-09-08T09:19:47Z", "doc_count": 236045 }, "ref__postal_codes": { "live_snapshot_ids": ["snp_2e58a1d94b0c7f33"], "swapped_at": "2024-11-08T09:12:30Z", "doc_count": 33791 } } } ``` Two entries in that sample are worth reading together. `exchange_geography` is only one and a half cadences old, which on age alone would be `aging` — it reads `stale` because its most recent refresh (`last_attempt_at`, later than `last_success_at`) ran and did not install. `ca_postal_codes` has never loaded at all, which is `failed` rather than a missing entry. ### Source fields `sources` carries **one entry per declared source, always** — including a source that has never loaded. A source is never omitted, because an omitted source is one nobody notices has broken. | Field | Meaning | | - | - | | `id` | Stable identifier for the source, named for what it supplies: `overlay_complexes`, `exchange_geography`, `zip_area_codes`, `us_postal_codes`, `ca_postal_codes`. | | `cadence_seconds` | How often this source is expected to refresh. The freshness thresholds below are multiples of this value, not fixed day counts. | | `mode` | `scheduled` when the source refreshes on its own schedule; `manual` when a new release has to be supplied by an operator. A manual source still ages and still goes stale — that is how it asks for the upload. | | `last_success_at` | When the newest usable data for this source was obtained. This dates the **data**, not the run: a refresh that succeeded by reusing the previous file does not move this timestamp. `null` when the source has never produced usable data. | | `last_attempt_at` | When this source was last attempted, successfully or not. Equal to `last_success_at` on a healthy source; later than it on a source whose most recent refresh did not install. | | `age_seconds` | Age of the newest usable data, in seconds. `null` when the source has never produced usable data. | | `status` | `fresh`, `aging`, `stale`, or `failed` — see below. | | `drift.row_count_delta` | Rows gained (positive) or lost (negative) versus the previous snapshot, summed across the files that make up the source. | | `drift.changed_keys` | How many keys changed value between the previous corpus and the one currently installed. | `drift`'s two fields distinguish `null` from `0`, and the distinction matters: `null` means *unknown — there is nothing earlier to compare against*, while `0` means *measured, and nothing moved*. Collapsing the first into the second would make a brand-new source look like a perfectly stable one. ### Status vocabulary The status is computed **on the server**, from the source's own declared cadence, by the same code that drives the monitoring alerts. A source reported here as `stale` or `failed` is already alerting — this value is never only a colour. | Status | When | | - | - | | `fresh` | Age is within one cadence. | | `aging` | Age is between one and two cadences. The boundaries are half-open at the bottom: a monthly source that is exactly a month old is already `aging`. | | `stale` | Age is beyond two cadences, **or** the most recent refresh failed validation. A refresh that ran and did not install is not a fresh refresh, however recently it ran. | | `failed` | The most recent attempt errored outright, or the source has never been attempted. `failed` wins over age. | ### Collection fields `collections` is keyed by collection name. The key set is declared server-side and is the same on every response. | Field | Meaning | | - | - | | `live_snapshot_ids` | The snapshots the **live** corpus was built from. Empty when nothing has been installed yet. | | `swapped_at` | When the live corpus was last replaced. `null` when nothing has been installed yet. | | `doc_count` | How many records the live corpus holds. `null` when nothing has been installed yet. | These three fields describe the **installed** corpus, not the most recent attempt. A refresh that fails validation leaves the previous corpus serving untouched, so they keep describing that corpus — the failure is visible in the relevant source's `status`, which is where it belongs. ## Errors The endpoint uses the standard `{"detail": "..."}` envelope. | Status | When | | - | - | | `401` | Missing or invalid credentials. | | `404` | The surface is not available to this organization — returned instead of a `403`, so the answer does not depend on whether the surface exists. | | `422` | The request failed validation. | | `429` | Request rate limit exceeded — retry after the `Retry-After` header. | A `403` is deliberately **not** part of this endpoint's documented surface. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.