---
title: Cache settings
summary: >-
  Configures cache lifetime for objects stored in the Fastly cache, overriding
  cache freshness information that would otherwise be determined from
  cache-related headers on the HTTP response. When used in conjunction with
  conditions, cache settings objects provide detailed control over how long
  content persists in the cache.
url: https://www.fastly.com/documentation/reference/api/vcl-services/cache-settings
---

Configures cache lifetime for objects stored in the Fastly cache, overriding cache freshness information that would otherwise be determined from cache-related headers on the HTTP response. When used in conjunction with conditions, cache settings objects provide detailed control over how long content persists in the cache.

## Data model

| Field | Type | Description |
|-------|------|-------------|
| `action` | string | If set, will cause vcl_fetch to terminate after processing this rule with the return state specified. If not set, other configuration logic in vcl_fetch with a lower priority will run after this rule. |
| `cache_condition` | string | Name of the cache condition controlling when this configuration applies. |
| `name` | string | Name for the cache settings object. |
| `stale_ttl` | string | Maximum time in seconds to continue to use a stale version of the object if future requests to your backend server fail (also known as 'stale if error'). |
| `ttl` | string | Maximum time to consider the object fresh in the cache (the cache 'time to live'). |
| `created_at` | string | Date and time in ISO 8601 format. (Read-only) |
| `deleted_at` | string | Date and time in ISO 8601 format. (Read-only) |
| `service_id` | string | Alphanumeric string identifying the service. (Read-only) |
| `updated_at` | string | Date and time in ISO 8601 format. (Read-only) |
| `version` | string | String identifying a service version. (Read-only) |

## API endpoints

### List cache settings objects

**GET** `/service/{service_id}/version/{version_id}/cache_settings`

Get a list of all cache settings for a particular service and version.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `service_id` | string | path | Yes | Alphanumeric string identifying the service. |
| `version_id` | integer | path | Yes | Integer identifying a service version. |

### Create a cache settings object

**POST** `/service/{service_id}/version/{version_id}/cache_settings`

Create a cache settings object.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `service_id` | string | path | Yes | Alphanumeric string identifying the service. |
| `version_id` | integer | path | Yes | Integer identifying a service version. |

### Get a cache settings object

**GET** `/service/{service_id}/version/{version_id}/cache_settings/{cache_settings_name}`

Get a specific cache settings object.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `cache_settings_name` | string | path | Yes | Name for the cache settings object. |
| `service_id` | string | path | Yes | Alphanumeric string identifying the service. |
| `version_id` | integer | path | Yes | Integer identifying a service version. |

### Update a cache settings object

**PUT** `/service/{service_id}/version/{version_id}/cache_settings/{cache_settings_name}`

Update a specific cache settings object.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `cache_settings_name` | string | path | Yes | Name for the cache settings object. |
| `service_id` | string | path | Yes | Alphanumeric string identifying the service. |
| `version_id` | integer | path | Yes | Integer identifying a service version. |

### Delete a cache settings object

**DELETE** `/service/{service_id}/version/{version_id}/cache_settings/{cache_settings_name}`

Delete a specific cache settings object.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `cache_settings_name` | string | path | Yes | Name for the cache settings object. |
| `service_id` | string | path | Yes | Alphanumeric string identifying the service. |
| `version_id` | integer | path | Yes | Integer identifying a service version. |