Cached vs Live Social Data: Latency, Cost and When Each Mode Wins

Quickstart

Every request needs one header: Authorization: Bearer $FETCHPI_API_KEY. Create a free key in the console and you can replay every snippet on this page as-is.

curl -s -H "Authorization: Bearer $FETCHPI_API_KEY"   "https://fetchpi.com/v1/tiktok/users/{username}?freshness=live"

The three modes

• freshness=live — always fetch from the upstream now. Maximum recency, full price.
• freshness=default — serve the response cache when a copy is at most max_age seconds old; otherwise fetch live and backfill the cache. The everyday mode.
• freshness=cache — only the cache. A miss answers 404 DATA_NOT_FOUND; the cheapest reads when you already know the data exists.

What the response tells you

Every response carries meta.freshness (the mode you asked for, which source_layer actually served it, the data age) and meta.billing (the credits charged, whether it was a cache hit). You never have to guess whether you paid for an upstream trip.

{
  "meta": {
    "freshness": {"mode": "default", "age_seconds": 42, "source_layer": "cache", "stale": false},
    "billing": {"amount_credits": 150, "cache_hit": true}
  }
}

Choosing max_age

Profile analytics, dashboards and monitoring recaps tolerate 10–15 minutes — max_age=600 to 900 turns repeat reads into cache hits at the catalog cache tier (most capabilities half price). Breaking-event search wants live. The search explorer demo lets you flip modes on real queries and watch both meta blocks respond.