How do datasets stay current, and how do I detect changes?

1. The refresh cadence

Every dataset refreshes on a published cadence, exposed as metadata.accrualPeriodicity on the dataset record (for example monthly). Knowing the cadence tells you how often it is worth checking for changes.

2. Watch metadata.modified (available today)

Poll the dataset record and compare metadata.modified to the value you last saw. When it advances, the dataset has been refreshed. This is public and costs no credits.

curl "https://api.topolab.nl/v1/dataset/nl-domino-poi" \
  | jq '.metadata.modified'

Poll no more often than the dataset's cadence — a monthly dataset needs a daily check at most. That respects the rate limits and avoids wasted requests.

3. Watch the archive list

GET /v1/dataset/:table/archives/list returns the retained monthly snapshots (also public, zero credits). A new month appearing means a new refresh landed. To compute exactly what changed, download two archive months and diff them — historical archives are a Team / Enterprise plan capability and cost 20 credits each.

4. The planned refresh hooks

Push-based refresh webhooks are planned and not yet available. When they ship, you will register an HTTPS endpoint and Topolab will POST a change set on every refresh, describing which records were added, updated and removed (keyed by the dataset's primary key). That lets a consumer fetch only the changed records instead of re-downloading the full export. The payload shape is the current design and may change before release.

What is live today

Polling metadata.modified and polling archives/list are both GA. The outbound dataset.refreshed webhook is planned — until it ships, poll one of the two free signals above.