Coverage and freshness

Coverage is the measured output of the waterfall: what the whole cascade, taken together, can actually fill in for a given channel and market. It is also the part of the unified model that keeps it honest. A schema promising the same fields everywhere is only useful if it also tells you where those fields are real.

The coverage report

GET /v1/coverage answers one question: for this entity, on this channel, in this market — what can I actually rely on?

curl "https://api.unif.dev/v1/coverage?entity=creator&channel=tiktok_shop&market=ID" \
  -H "Authorization: Bearer $UNIF_API_KEY"

{
  "object": "coverage",
  "entity": "creator",
  "fields": [
    {
      "field": "metrics.revenue",
      "channel": "tiktok_shop",
      "market": "ID",
      "availability": "full",
      "filterable": true,
      "sortable": true,
      "typical_lag_hours": 24,
      "note": null
    },
    {
      "field": "metrics.engagement_rate",
      "channel": "tiktok_shop",
      "market": "ID",
      "availability": "partial",
      "filterable": false,
      "sortable": false,
      "typical_lag_hours": 48,
      "note": "Populated for creators above 10k followers."
    },
    {
      "field": "agency",
      "channel": "tiktok_shop",
      "market": "ID",
      "availability": "unavailable",
      "filterable": false,
      "sortable": false,
      "typical_lag_hours": null,
      "note": "Not disclosed by the channel in this market."
    }
  ]
}

Reading the fields

string

full — some source in the cascade fills this for essentially every entity. partial — filled for a defined subset, described in note. unavailable — no source in the cascade reports it here; the field is always null, and running more sources would not change that.

boolean

Whether the field can be used in filters or as a sort key for this channel and market. A partial field is often readable but not filterable, because filtering on it would silently drop every entity where it is missing.

integer | null

The usual delay between something happening on the channel and it being reflected here. Pair it with meta.refreshed_at on a record to know how current a number is.

Filtering on a partial field narrows your result set in a way that is invisible in the response. Entities missing the field are excluded, not returned with null. If filterable is false, Unif rejects the query with coverage_error rather than returning a quietly biased list.

Per-record completeness

Coverage describes a channel and market. meta on each record describes that record.

"meta": {
  "refreshed_at": "2026-09-15T04:12:00Z",
  "completeness": 0.85,
  "missing_fields": ["metrics.engagement_rate", "agency"]
}

number

The share of requested fields that came back populated. With fields set on an enrich call, it is measured against exactly what you asked for.

string[]

Which fields are null and why they are absent — either unavailable for this channel and market, or not populated for this particular entity.

An enrich result reports status: "partial" when some requested fields could not be filled. That is a successful call with an incomplete answer, and it is worth branching on:

for result in response["data"]:
    if result["status"] == "partial":
        log.warning("row %s missing %s", result["ref"], result["meta"]["missing_fields"])
    elif result["status"] != "enriched":
        queue_for_review(result)

Freshness

Refresh cadence varies by entity, and it follows how fast the underlying thing actually changes.

Entity	Typical cadence	Typical lag
Shop	Daily	24h
Product	Daily	24h
Creator	Daily	24–48h
Video	Hourly for trending, daily otherwise	2–24h
Livestream	On session end	1–6h
Category	Daily	24h

meta.refreshed_at is when Unif last refreshed the record — not when you called. Two records in the same response can legitimately carry different timestamps, because they were refreshed on different cycles.

Building against coverage rather than around it

Check coverage when you add a market

Not on every request — coverage changes on the order of weeks, usually when the cascade gains a source or one is re-tuned. A weekly sync into your own config is the right cadence.

Degrade filters rather than failing

If gpm is not filterable in a market, fall back to filtering on revenue and ranking by gpm client-side over a wider result set.

Alert on completeness drops

A sustained fall in meta.completeness for an entity you track is an upstream change worth knowing about before your dashboards start looking wrong.

Getting started

Core concepts

Workflows

Guides

Platform

Release notes

Coverage and freshness

The coverage report

Reading the fields

Per-record completeness

Freshness

Building against coverage rather than around it

​The coverage report

​Reading the fields

​Per-record completeness

​Freshness

​Building against coverage rather than around it

The coverage report

Reading the fields

Per-record completeness

Freshness

Building against coverage rather than around it