API Documentation

Caching

Supported endpoints can serve responses from our response cache instead of scraping the source live. If the data was scraped recently enough for your needs, you get it back in about a second instead of waiting on a live scrape — ideal for data that doesn't change often, like profiles, posts, and transcripts.

FREE

Cache hits cost 0 credits. You only pay when we scrape live — every response served from cache is completely free and comes back with "credits_charged": 0.

How to Use It

Add the cache_max_age query parameter to any endpoint that supports caching (it's listed in the endpoint's query parameters). The value is the maximum age you'll accept for a cached response:

1d3d7d14d30d
curl --request GET \
  --url 'https://api.scrapecreators.com/v1/tiktok/profile?handle=stoolpresidente&cache_max_age=7d' \
  --header 'x-api-key: YOUR_API_KEY'

If we have a cached response that's 7 days old or newer, you get it back instantly — free of charge — with "cached": true, "credits_charged": 0, and a "cached_at" timestamp telling you exactly when the cached copy was scraped. If the cached copy is older than 7 days (or doesn't exist yet), we scrape fresh, return the live result, and update the cache for next time.

Any other value returns a 400 with the list of allowed values. On endpoints that don't support caching, the parameter is ignored.

How It Works

Cache Hit

The cached copy is newer than your cache_max_age — it's returned immediately with "cached": true and "cached_at" (when it was scraped) in the body. No live scrape happens.

Cache Miss

The cached copy is too old or doesn't exist — we scrape live, return the fresh result, and overwrite the cache so its age resets to zero.

Always Warming

Every successful request to a cacheable endpoint refreshes the cache — even without cache_max_age. Popular resources stay fresh automatically.

CreditsHITS ARE FREE

Cache hits cost 0 credits. A cache miss runs a normal live scrape and is charged the endpoint's regular credit cost. Every response includes a credits_charged field showing what the request cost.

💡One Cache Per Resource

The cache is keyed by the endpoint plus the parameters that identify the resource. Different cache_max_age values read the same cached copy — the value only controls how old a copy you'll accept. Extra or reordered query parameters don't fragment the cache.

⚡Want Caching on Another Endpoint?

We're rolling caching out to more endpoints over time. If there's one you'd like supported, email support@scrapecreators.com.