Data Freshness & Caching
The API automatically manages data freshness for every request. There is no mode segment in the URL — the cache strategy is smart by default, and you opt into a live re-scrape only when you need it.
GET /v2/users/dymerz ← cache-first, always free
GET /v2/users/dymerz?refresh=true ← force live scrape, costs 1 daily request
(See Refresh Intervals for the full table of maximum data ages.)
How It Works
Default (no ?refresh): Every request checks the cache first (a fast in-memory layer, then the database).
- Fresh cache: the cached data is returned immediately, at no quota cost.
- Stale or missing cache: the request itself triggers a live scrape of the RSI website, stores the result, and returns it. This automatic re-scrape is free — it does not touch your daily quota (it still counts toward the per-minute scrape limits).
- Slow scrape: if the scrape takes too long and cached data exists, the cached data is returned while the scrape finishes in the background.
- Failed scrape: if the scrape fails and cached data exists, the cached data is returned instead of an error.
There is no scheduled background refresh: data is refreshed when someone asks for it after it has expired.
With ?refresh=true: Bypasses the cache and forces an immediate live scrape from the RSI website. The result is stored in the cache before being returned.
Live scrapes cost quota.
?refresh=true counts as 1 daily request (10 for GET /v2/ships) even if the data hasn't actually changed. Only use it when you genuinely need the latest data from RSI right now.
Quick Reference
| Scenario | What to do | Quota cost |
|---|---|---|
| General use | No extra parameter | Free |
| Need guaranteed up-to-date data | Add ?refresh=true | 1 per call (10 for ships) |
| Quota running low | No extra parameter | Free |
| Checking if data changed (polling) | Use ETags and expiresAt | Free |
Reading Freshness from Responses
Every response served from the cache or a live scrape includes two timestamps:
| Field | What it tells you |
|---|---|
updatedAt | When the data was last scraped from the RSI website |
expiresAt | When the cached data may next be automatically re-scraped |
Once expiresAt has passed, the next request re-scrapes automatically — no ?refresh=true needed, and no quota spent. Use this timestamp to schedule your next poll rather than polling on a fixed interval.
Every response also carries an X-Data-Source header: cache when the data came from the cache (including a fallback), live when it was just scraped.
Each endpoint group has a fixed maximum data age. See Refresh Intervals for the full table.
For quota limits and how to check your remaining balance, see Rate Limits & Quota.