Developer Docs

Provenance & Coverage

Why observed data ships with a provenance envelope and a coverage gate.

We report public TikTok activity we observed, not an official feed. So every data answer ships a provenance envelope stating how current it is and how far it sits inside our published Coverage Set. This honesty is the product — treat these fields as part of the data.

The envelope

Data resources are wrapped as { data, provenance }. The provenance block:

Field	Meaning
`observedAt`	RFC 3339 instant of the newest observation in this response.
`freshness`	How current the observation is — one of near_realtime, historical, stale.
`source`	The collector or persisted dataset that produced the observation.
`coverageStatus`	Honest position inside the Coverage Set — one of observed, partial, not-covered, not-offered, stale.
`methodologyVersion`	Version of the calculation/projection used, so derived numbers are reproducible.

freshness

Refreshes are always asynchronous — we never block a read on a synchronous TikTok fetch. A read tells you how current it is:

Value	Meaning
`near_realtime`	Observed within the realtime window (live events, just-refreshed reads).
`historical`	A stable past observation — accurate as of observedAt, not a live value.
`stale`	Older than the dataset's freshness target; a refresh is warranted.

coverageStatus

Coverage is a stated, expanding subset of public TikTok — never a claim to all of it:

Value	Meaning
`observed`	Directly observed and inside the published Coverage Set.
`partial`	Inside coverage, but this answer is a sample or an incomplete walk (stated in the payload).
`not-covered`	Outside the current Coverage Set — we do not claim this data.
`not-offered`	TikTok does not currently publish this board in the selected region.
`stale`	Was covered, but the observation is past its freshness target.

To pull a fresher observation on demand, request a refresh (billed live-refresh) or an on-demand resolve where the dataset supports it — see Rate limits & Credits.