Concepts
Freshness and caching
Choose how fresh your data must be, and pay less when older data is acceptable.
Every read accepts a freshness parameter: live, 24h, 7d, or 30d.
Fresher costs more. If you do not pass the parameter, the default is 24h.
curl "https://api.openhandle.dev/v1/tiktok/profiles/@tiktok?freshness=7d" \
-H "Authorization: Bearer $OPENHANDLE_API_KEY"The tiers
| Freshness | You get | Price behavior |
|---|---|---|
live | Data fetched right now | Live price, always |
24h | Data at most 24 hours old | Cache price on a hit, live price on a miss |
7d | Data at most 7 days old | Cache price on a hit, live price on a miss |
30d | Data at most 30 days old | Free on a hit, live price on a miss |
See pricing for the exact per-request rates.
Cache misses cost the live price
A freshness tier is a maximum acceptable age, not a guaranteed discount. When no answer within your accepted age exists, we fetch live data and the request bills at the live price. Every successful answer meets the freshness limit you selected.
Some answers are always read live:
- Empty lists are never cached. An empty page looks the same as a temporary provider problem, so it is not stored. A request that answers an empty list is read live every time and bills at the live price.
- Later pages never come from an older capture. When you paginate, each page after the first must be captured at the same time as the first page or later. If the cached copy of a later page is older than your first page, that page is read live again, so pages do not repeat or skip.
Know what you received
The envelope always tells you the truth about what you got:
sourceisliveorcache.capturedAtis when the data was actually captured.
If your application logs these two fields, you can audit exactly what you paid for and how old every answer was.
Choosing a tier
- Rendering a dashboard someone refreshes often:
24his usually right. - Analytics or trend jobs over many accounts:
7dor30dcuts cost sharply. - Moderation, alerting, or anything user-triggered:
live.