Create or update a lifecycle policy | Elasticsearch API documentation (8x-unreleased)

Create or update a lifecycle policy Generally available; Added in 6.6.0

PUT /_ilm/policy/{policy}

If the specified policy exists, it is replaced and the policy version is incremented.

NOTE: Only the latest version of the policy is stored, you cannot revert to previous versions. ##Required authorization

Index privileges: manage* Cluster privileges: manage_ilm

External documentation

Path parameters

policy string Required

Identifier for the policy.

Query parameters

master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
timeout string

Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

application/json

Body

policy object
Hide policy attributes Show policy attributes object
- phases object Required
  Hide phases attributes Show phases attributes object
  
  cold object
  
  Hide cold attributes Show cold attributes object
  
  actions object
  
  Hide actions attributes Show actions attributes object
  
  allocate object
  
  Hide allocate attributes Show allocate attributes object
  
  number_of_replicas number
  
  total_shards_per_node number
  
  include object
  
  Hide include attribute Show include attribute object
  
  * string Additional properties
  
  exclude object
  
  Hide exclude attribute Show exclude attribute object
  
  * string Additional properties
  
  require object
  
  Hide require attribute Show require attribute object
  
  * string Additional properties
  
  delete object
  
  Hide delete attribute Show delete attribute object
  
  delete_searchable_snapshot boolean
  
  downsample object
  
  Hide downsample attributes Show downsample attributes object
  
  fixed_interval string Required
  
  A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)
  
  wait_timeout string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  freeze object
  
  forcemerge object
  
  Hide forcemerge attributes Show forcemerge attributes object
  
  max_num_segments number Required
  
  index_codec string
  
  migrate object
  
  Hide migrate attribute Show migrate attribute object
  
  enabled boolean
  
  readonly object
  
  rollover object
  
  Hide rollover attributes Show rollover attributes object
  
  max_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  max_docs number
  
  max_primary_shard_docs number
  
  min_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  min_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  min_docs number
  
  min_primary_shard_docs number
  
  set_priority object
  
  Hide set_priority attribute Show set_priority attribute object
  
  priority number
  
  searchable_snapshot object
  
  Hide searchable_snapshot attributes Show searchable_snapshot attributes object
  
  snapshot_repository string Required
  
  force_merge_index boolean
  
  shrink object
  
  Hide shrink attributes Show shrink attributes object
  
  number_of_shards number
  
  max_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  allow_write_after_shrink boolean
  
  unfollow object
  
  wait_for_snapshot object
  
  Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
  
  policy string Required
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  delete object
  
  Hide delete attributes Show delete attributes object
  
  actions object
  
  Hide actions attributes Show actions attributes object
  
  allocate object
  
  Hide allocate attributes Show allocate attributes object
  
  number_of_replicas number
  
  total_shards_per_node number
  
  include object
  
  Hide include attribute Show include attribute object
  
  * string Additional properties
  
  exclude object
  
  Hide exclude attribute Show exclude attribute object
  
  * string Additional properties
  
  require object
  
  Hide require attribute Show require attribute object
  
  * string Additional properties
  
  delete object
  
  Hide delete attribute Show delete attribute object
  
  delete_searchable_snapshot boolean
  
  downsample object
  
  Hide downsample attributes Show downsample attributes object
  
  fixed_interval string Required
  
  A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)
  
  wait_timeout string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  freeze object
  
  forcemerge object
  
  Hide forcemerge attributes Show forcemerge attributes object
  
  max_num_segments number Required
  
  index_codec string
  
  migrate object
  
  Hide migrate attribute Show migrate attribute object
  
  enabled boolean
  
  readonly object
  
  rollover object
  
  Hide rollover attributes Show rollover attributes object
  
  max_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  max_docs number
  
  max_primary_shard_docs number
  
  min_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  min_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  min_docs number
  
  min_primary_shard_docs number
  
  set_priority object
  
  Hide set_priority attribute Show set_priority attribute object
  
  priority number
  
  searchable_snapshot object
  
  Hide searchable_snapshot attributes Show searchable_snapshot attributes object
  
  snapshot_repository string Required
  
  force_merge_index boolean
  
  shrink object
  
  Hide shrink attributes Show shrink attributes object
  
  number_of_shards number
  
  max_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  allow_write_after_shrink boolean
  
  unfollow object
  
  wait_for_snapshot object
  
  Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
  
  policy string Required
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  frozen object
  
  Hide frozen attributes Show frozen attributes object
  
  actions object
  
  Hide actions attributes Show actions attributes object
  
  allocate object
  
  Hide allocate attributes Show allocate attributes object
  
  number_of_replicas number
  
  total_shards_per_node number
  
  include object
  
  Hide include attribute Show include attribute object
  
  * string Additional properties
  
  exclude object
  
  Hide exclude attribute Show exclude attribute object
  
  * string Additional properties
  
  require object
  
  Hide require attribute Show require attribute object
  
  * string Additional properties
  
  delete object
  
  Hide delete attribute Show delete attribute object
  
  delete_searchable_snapshot boolean
  
  downsample object
  
  Hide downsample attributes Show downsample attributes object
  
  fixed_interval string Required
  
  A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)
  
  wait_timeout string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  freeze object
  
  forcemerge object
  
  Hide forcemerge attributes Show forcemerge attributes object
  
  max_num_segments number Required
  
  index_codec string
  
  migrate object
  
  Hide migrate attribute Show migrate attribute object
  
  enabled boolean
  
  readonly object
  
  rollover object
  
  Hide rollover attributes Show rollover attributes object
  
  max_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  max_docs number
  
  max_primary_shard_docs number
  
  min_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  min_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  min_docs number
  
  min_primary_shard_docs number
  
  set_priority object
  
  Hide set_priority attribute Show set_priority attribute object
  
  priority number
  
  searchable_snapshot object
  
  Hide searchable_snapshot attributes Show searchable_snapshot attributes object
  
  snapshot_repository string Required
  
  force_merge_index boolean
  
  shrink object
  
  Hide shrink attributes Show shrink attributes object
  
  number_of_shards number
  
  max_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  allow_write_after_shrink boolean
  
  unfollow object
  
  wait_for_snapshot object
  
  Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
  
  policy string Required
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  hot object
  
  Hide hot attributes Show hot attributes object
  
  actions object
  
  Hide actions attributes Show actions attributes object
  
  allocate object
  
  Hide allocate attributes Show allocate attributes object
  
  number_of_replicas number
  
  total_shards_per_node number
  
  include object
  
  Hide include attribute Show include attribute object
  
  * string Additional properties
  
  exclude object
  
  Hide exclude attribute Show exclude attribute object
  
  * string Additional properties
  
  require object
  
  Hide require attribute Show require attribute object
  
  * string Additional properties
  
  delete object
  
  Hide delete attribute Show delete attribute object
  
  delete_searchable_snapshot boolean
  
  downsample object
  
  Hide downsample attributes Show downsample attributes object
  
  fixed_interval string Required
  
  A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)
  
  wait_timeout string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  freeze object
  
  forcemerge object
  
  Hide forcemerge attributes Show forcemerge attributes object
  
  max_num_segments number Required
  
  index_codec string
  
  migrate object
  
  Hide migrate attribute Show migrate attribute object
  
  enabled boolean
  
  readonly object
  
  rollover object
  
  Hide rollover attributes Show rollover attributes object
  
  max_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  max_docs number
  
  max_primary_shard_docs number
  
  min_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  min_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  min_docs number
  
  min_primary_shard_docs number
  
  set_priority object
  
  Hide set_priority attribute Show set_priority attribute object
  
  priority number
  
  searchable_snapshot object
  
  Hide searchable_snapshot attributes Show searchable_snapshot attributes object
  
  snapshot_repository string Required
  
  force_merge_index boolean
  
  shrink object
  
  Hide shrink attributes Show shrink attributes object
  
  number_of_shards number
  
  max_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  allow_write_after_shrink boolean
  
  unfollow object
  
  wait_for_snapshot object
  
  Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
  
  policy string Required
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  warm object
  
  Hide warm attributes Show warm attributes object
  
  actions object
  
  Hide actions attributes Show actions attributes object
  
  allocate object
  
  Hide allocate attributes Show allocate attributes object
  
  number_of_replicas number
  
  total_shards_per_node number
  
  include object
  
  Hide include attribute Show include attribute object
  
  * string Additional properties
  
  exclude object
  
  Hide exclude attribute Show exclude attribute object
  
  * string Additional properties
  
  require object
  
  Hide require attribute Show require attribute object
  
  * string Additional properties
  
  delete object
  
  Hide delete attribute Show delete attribute object
  
  delete_searchable_snapshot boolean
  
  downsample object
  
  Hide downsample attributes Show downsample attributes object
  
  fixed_interval string Required
  
  A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)
  
  wait_timeout string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  freeze object
  
  forcemerge object
  
  Hide forcemerge attributes Show forcemerge attributes object
  
  max_num_segments number Required
  
  index_codec string
  
  migrate object
  
  Hide migrate attribute Show migrate attribute object
  
  enabled boolean
  
  readonly object
  
  rollover object
  
  Hide rollover attributes Show rollover attributes object
  
  max_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  max_docs number
  
  max_primary_shard_docs number
  
  min_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  min_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  min_docs number
  
  min_primary_shard_docs number
  
  set_priority object
  
  Hide set_priority attribute Show set_priority attribute object
  
  priority number
  
  searchable_snapshot object
  
  Hide searchable_snapshot attributes Show searchable_snapshot attributes object
  
  snapshot_repository string Required
  
  force_merge_index boolean
  
  shrink object
  
  Hide shrink attributes Show shrink attributes object
  
  number_of_shards number
  
  max_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  allow_write_after_shrink boolean
  
  unfollow object
  
  wait_for_snapshot object
  
  Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
  
  policy string Required
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
- _meta object
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

PUT /_ilm/policy/{policy}

PUT _ilm/policy/my-lifecycle-policy
{
  "policy": {
    "phases": {
      "hot": {
        "actions": {
          "rollover": {
            "max_primary_shard_size": "50gb"
          }
        }
      },
      "warm": {
        "min_age": "30d",
        "actions": {
          "shrink": {
            "number_of_shards": 1
          },
          "forcemerge": {
            "max_num_segments": 1
          }
        }
      },
      "cold": {
        "min_age": "60d",
        "actions": {
          "searchable_snapshot": {
            "snapshot_repository": "found-snapshots"
          }
        }
      },
      "frozen": {
        "min_age": "90d",
        "actions": {
          "searchable_snapshot": {
            "snapshot_repository": "found-snapshots"
          }
        }
      },
      "delete": {
        "min_age": "735d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}

curl \
 --request PUT 'http://api.example.com/_ilm/policy/{policy}' \
 --header "Content-Type: application/json" \
 --data '"{\n  \"policy\": {\n    \"phases\": {\n      \"hot\": {\n        \"actions\": {\n          \"rollover\": {\n            \"max_primary_shard_size\": \"50gb\"\n          }\n        }\n      },\n      \"warm\": {\n        \"min_age\": \"30d\",\n        \"actions\": {\n          \"shrink\": {\n            \"number_of_shards\": 1\n          },\n          \"forcemerge\": {\n            \"max_num_segments\": 1\n          }\n        }\n      },\n      \"cold\": {\n        \"min_age\": \"60d\",\n        \"actions\": {\n          \"searchable_snapshot\": {\n            \"snapshot_repository\": \"found-snapshots\"\n          }\n        }\n      },\n      \"frozen\": {\n        \"min_age\": \"90d\",\n        \"actions\": {\n          \"searchable_snapshot\": {\n            \"snapshot_repository\": \"found-snapshots\"\n          }\n        }\n      },\n      \"delete\": {\n        \"min_age\": \"735d\",\n        \"actions\": {\n          \"delete\": {}\n        }\n      }\n    }\n  }\n}"'

Request examples

An example body for a `PUT _ilm/policy/my-lifecycle-policy` request.

{
  "policy": {
    "phases": {
      "hot": {
        "actions": {
          "rollover": {
            "max_primary_shard_size": "50gb"
          }
        }
      },
      "warm": {
        "min_age": "30d",
        "actions": {
          "shrink": {
            "number_of_shards": 1
          },
          "forcemerge": {
            "max_num_segments": 1
          }
        }
      },
      "cold": {
        "min_age": "60d",
        "actions": {
          "searchable_snapshot": {
            "snapshot_repository": "found-snapshots"
          }
        }
      },
      "frozen": {
        "min_age": "90d",
        "actions": {
          "searchable_snapshot": {
            "snapshot_repository": "found-snapshots"
          }
        }
      },
      "delete": {
        "min_age": "735d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}

Run `PUT _ilm/policy/my_policy` to create a new policy with arbitrary metadata.

{
  "policy": {
    "_meta": {
      "description": "used for nginx log",
      "project": {
        "name": "myProject",
        "department": "myDepartment"
      }
    },
    "phases": {
      "warm": {
        "min_age": "10d",
        "actions": {
          "forcemerge": {
            "max_num_segments": 1
          }
        }
      },
      "delete": {
        "min_age": "30d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}

Response examples (200)

A successful response when creating a new lifecycle policy.

{
  "acknowledged": true
}

Documentation preview

This is a preview of your version @2025-06-09 which is not yet released.

View current documentation

Create or update a lifecycle policy Generally available; Added in 6.6.0

Path parameters

Query parameters

Body

max_size number | string

max_primary_shard_size number | string

min_size number | string

min_primary_shard_size number | string

max_primary_shard_size number | string

max_size number | string

max_primary_shard_size number | string

min_size number | string

min_primary_shard_size number | string

max_primary_shard_size number | string

max_size number | string

max_primary_shard_size number | string

min_size number | string

min_primary_shard_size number | string

max_primary_shard_size number | string

max_size number | string

max_primary_shard_size number | string

min_size number | string

min_primary_shard_size number | string

max_primary_shard_size number | string

max_size number | string

max_primary_shard_size number | string

min_size number | string

min_primary_shard_size number | string

max_primary_shard_size number | string

Responses

Documentation preview