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.
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.