Skip to content
Cloudflare Docs

Browser TTL

Browser TTL controls how long an image stays in a browser's cache and specifically configures the cache-control response header.

Default TTL

By default, an image's TTL is set to two days to meet user needs, such as re-uploading an image under the same Custom ID.

Custom setting

You can use two custom settings to control the Browser TTL, an account or a named variant. To adjust how long a browser should keep an image in the cache, set the TTL in seconds, similar to how the max-age header is set. The value should be an interval between one hour to one year.

Browser TTL for an account

Setting the Browser TTL per account overrides the default TTL.

Example
curl --request PATCH 'https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/config' \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "browser_ttl": 31536000
}'

When the Browser TTL is set to one year for all images, the response for the cache-control header is essentially public, max-age=31536000, stale-while-revalidate=7200.

Browser TTL for a named variant

Setting the Browser TTL for a named variant is a more granular option that overrides all of the above when creating or updating an image variant, specifically the browser_ttl option in seconds.

Example
curl 'https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_TAG>/images/v1/variants' \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "id":"avatar",
  "options": {
    "width":100,
    "browser_ttl": 86400
  }
}'

When the Browser TTL is set to one day for images requested with this variant, the response for the cache-control header is essentially public, max-age=86400, stale-while-revalidate=7200.