Caching & freshness

Responses arrive in seconds; popular content returns in milliseconds because we cache aggressively. Caching is visible and controllable:

• Every response carries x-cache: hit or x-cache: miss.
• Cache hits cost the same credits as fresh fetches — the difference is latency.
• Add fresh=true to any call to bypass the cache at the same price.

curl -sD - "https://api.scrapersocial.com/v1/twitter/stats?url=..." \
  -H "Authorization: Bearer sk_live_..." -o /dev/null | grep -i x-cache
# x-cache: hit

Cache classes

Each endpoint has a freshness class, shown on its reference page:

Class	Behavior	Typical endpoints
Cached forever	Content that never changes	Transcripts, AI summaries
Cached 7 days	Media metadata (resolved media URLs expire within 1 hour)	Downloads
Cached 12 hours	Slow-moving profile data	Channel/profile/company stats
Cached 3 hours	Recent-content lists (page 1 refreshes hourly)	Channel posts, timelines
Age-aware	Fresher content refreshes faster (15 min floor, 7 day max)	Post stats, comments, search

“Age-aware” scales with how old the content is: stats for a video posted an hour ago refresh every few minutes; stats for a two-year-old video refresh daily.

When to force freshness

r = httpx.get(f"{BASE}/v1/tiktok/stats",
              params={"url": video_url, "fresh": "true"},
              headers=H)

Use fresh=true for point-in-time measurements (end-of-campaign reporting, billing reconciliations). For dashboards and monitoring, the default freshness windows are almost always the better trade.

Next: Errors · Rate limits