Completeness and contribution health

Every list and lookup response states whether the inventory holds all of its sources' data (completeness) and how each source's refreshes are going (contribution health). A consumer uses them to tell a complete inventory from a partial one before acting on the data.

Completeness

"completeness": {
  "complete": false,
  "causes": [
    { "cause": "no_snapshot", "contribution": "netbox" },
    { "cause": "duplicate_hfid", "contribution": "infrahub", "records": 2 }
  ]
}

An inventory is complete when both conditions hold:

• Every contribution has published at least one full refresh.
• No record is excluded because of its HFID.

Otherwise complete is false and causes lists each reason:

Cause	Meaning	What fixes it
no_snapshot	The contribution has not published a full refresh since it was added, since its collection settings changed, or since the cache was emptied.	A successful refresh of the contribution.
missing_hfid	records records of the contribution have no HFID.	Setting the HFID field in the source.
duplicate_hfid	records records of the contribution share an HFID with another record of the same contribution.	Making the HFIDs unique in the source.

These do not make an inventory incomplete:

• A value that is unmapped or of the wrong type. It is reported in full detail and the diagnostics.
• A stale value. It is reported in the freshness of the entity and of the value.
• A contribution whose last refresh failed, if it published one before. It keeps its last data and is reported as degraded.

To make a query fail on an incomplete inventory, add require_complete=true: the response is 409 inventory-incomplete with the same causes.

Contribution health

"contributions": [
  { "id": "infrahub", "connection": "infrahub-prod", "health": "ok",
    "snapshot": "published", "last_published_at": "2026-10-25T09:00:00.000000Z",
    "last_error": null },
  { "id": "netbox", "connection": "netbox-prod", "health": "degraded",
    "snapshot": "published", "last_published_at": "2026-10-25T07:00:00.000000Z",
    "last_error": "source unreachable: connection refused" }
]

Key	Meaning
health	ok: the last refresh was published. refreshing: a refresh is running after a published one. degraded: the last refresh failed.
snapshot	published once a full refresh was published, otherwise none.
last_published_at	When the last full refresh was published.
last_error	The error of the last failed refresh, without credentials.

In an entity list the health block is contributions; in a lookup it is health.

A source that is down

When a source cannot be reached:

• Census keeps serving the source's last published values, and the source keeps its priority.
• The contribution's health becomes degraded, with the error in last_error.
• The values become stale once their freshness budget runs out.
• The inventory stays complete if the contribution had published before.

A consumer decides from health, last_published_at and freshness whether to use these values.