Freshness & caching

How old your data is, how to ask for something newer, and why we do not claim real-time.

Every response says how old it is

Four fields, on every object:

Build reports on source_timestamp where it is present and fetched_at otherwise. A number without a time attached is not evidence of anything.

Asking for a fresh copy

By default you get a cached copy if we have a recent one. To force a live fetch, pass freshness=fresh:

curl https://api.sourcevine.io/v1/profile \
  -H "Authorization: Bearer $SOURCEVINE_API_KEY" \
  --data-urlencode "url=https://www.tiktok.com/@atlas.makes" \
  --data-urlencode "freshness=fresh" -G

A fresh fetch is charged at the operation’s credit class. A cached one is free. Most workloads do not need fresh — if you are comparing two readings taken hours apart, cache age of a few minutes is noise.

How long things stay cached

Windows are short and vary by what changes fastest:

These are tuned from real hit rates rather than fixed forever. cache_age_seconds always tells you the truth for the response in your hand, so do not hard-code these numbers.

Why we do not say “real-time”

Our upstream providers publish no cache TTL and no freshness SLA. We can tell you exactly when we fetched something, because we measured it. We cannot tell you that it was live at the source at that instant, because we have no way to verify that — so we do not claim it.

What we do claim: a fresh request triggers a live fetch from the provider, and fetched_at is the moment we received the response.

Designing around it

Snapshot before and after. Delivery, growth and drop are differences between two readings. Take one at the start and one at the end, and keep both timestamps.

Poll freely on cached. It costs nothing. Cache hits are free precisely so that repeated checking is not a billing decision.

Reserve fresh for moments that matter — the reading you are going to put in front of a client, or the one that triggers an action.

Last updated 27 August 2026