Caching: free cached reads
Pass cache_max_age and accept a result up to 30 days old. Cached responses return in about a second and cost nothing. You are only billed for live scrapes.
Plenty of scraping does not need a result from this second. A profile you enriched last Tuesday, a post whose engagement you are trending weekly, a catalogue you re-check monthly: for all of it, a recent answer is as good as a live one and a lot faster to get.
Add cache_max_age to any supported call and we will serve a stored result if one that fresh exists. It comes back in about a second instead of a live scrape, and it is free: a cached read is not billed at all.
cache_max_age is never worse than omitting it: at best you pay nothing and get an instant answer, at worst you pay the normal price for a live result.How to use it
| Parameter | Type | Required | Description |
|---|---|---|---|
cache_max_age | 1d | 3d | 7d | 14d | 30d | optional | The oldest result you are willing to accept. Anything outside this set returns a 400. Omit the parameter entirely for a guaranteed-live scrape. |
# Happy with a result up to a week old, and pay nothing if we have one
curl "https://hproxy.com/api/v1/scrape/tiktok/profile?handle=levelsio&cache_max_age=7d" \
-H "X-API-Key: hpx_your_key_here"Reading the response
A cached response carries two extra fields so you always know what you got and what it cost. A live response carries neither.
| Field | Type | Description |
|---|---|---|
cached | boolean | true when the result came from cache. Absent on a live scrape. |
cached_at | timestamp | When the cached copy was originally scraped, so you can judge the age yourself. |
walletDebitUsd | number | 0 on a cached read. This is the field to reconcile against, on any call. |
What it does and does not do
cache_max_age is an acceptance threshold, not a cache selector. Every value reads the same stored copy; you are only saying how old a copy you will take. So asking for 1d and asking for 30d can return the identical response, and asking for 1d when the stored copy is a week old triggers a fresh live scrape (and a normal charge) which then refreshes the cache for everyone.
It is available on the endpoints where a cached answer is meaningful: profiles, posts, transcripts, channels, ad details and link-in-bio pages. Search, trending and comment feeds are always live, because a stale answer there is not an answer. The Scraper catalog lists cache_max_age in the inputs of every endpoint that accepts it.
Need a hand wiring this up? Email [email protected]. A real person reads every message.