Caching & freshness
URLpipe caches the result of every operation per URL. When you ask for the same thing again, you can accept the cached result — instantly, and without spending any quota.
The max_age parameter
Every endpoint accepts an optional max_age parameter that says how fresh a cached result must be for you to accept it. If a cached result exists and is younger than max_age, URLpipe returns it as-is. Otherwise it does the work again and caches the new result.
- Name
max_age- Type
- string | integer
- Description
- How old a cached result may be and still be accepted. Accepts a bare number of seconds (
3600), or a human duration like"2 hours","3 days","30m"or"45 sec". Defaults to7 days.
# Accept a cached result up to 2 hours old
curl -X POST https://urlpipe.dev/markdown \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com", "max_age": "2 hours"}'Accepted units & limits
- Seconds:
s,sec,second(s) - Minutes:
m,min,minute(s) - Hours:
h,hr,hour(s) - Days:
d,day(s) - Weeks:
w,week(s)
Values are clamped to a range of 0 to 30 days. Set max_age=0 to always bypass the cache and fetch fresh. An unrecognised value returns a 422 with error invalid_max_age.
Cache hits are free
This makes max_age a direct cost lever. Polling a set of URLs every few minutes but happy with hourly freshness? Set max_age="1 hour" and most requests are served from cache for free. Need the absolute latest? Use max_age=0 and every request does real work and counts toward quota.
What counts as the same request
A cached result is keyed by the operation, the URL, and any request options that change the output. For /lighthouse, for example, the device and include_audits options are part of the key, so a mobile audit and a desktop audit are cached separately.