Caching and freshness
The x-cache header, fresh=true, and what each freshness class means.
Popular content returns in milliseconds because responses are stored for a while. Storage is visible and under your control:
- Every response carries
x-cache: hitorx-cache: miss. - A hit costs the same credits as a live read. The difference is latency.
- Add
fresh=trueto any call to read live at the same price.
Freshness classes
Each endpoint page names its class.
| Class | Behaviour | Typical endpoints |
|---|---|---|
| Stored once, served forever | Content that never changes | Transcripts, summaries |
| Refreshed weekly | Media metadata; the media URLs themselves expire sooner | Download |
| Refreshed every 12 hours | Slow-moving profile and tag data | Profile, hashtag stats, places |
| Refreshed every 3 hours | Recent-content lists; page 1 refreshes sooner | Profile posts and reels |
| Age-aware, 15 minutes to 7 days | Fresher content refreshes faster | Post stats, comments, search |
Use fresh=true for point-in-time measurements such as end-of-campaign reporting. For dashboards and monitoring, the defaults are almost always the better trade.