elasticsearch/docs/reference/ilm/apis/get-lifecycle.asciidoc

[role="xpack"]
[[ilm-get-lifecycle]]
=== Get lifecycle policy API
++++
<titleabbrev>Get policy</titleabbrev>
++++

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-ilm[{ilm-cap} APIs].
--

Retrieves a <<index-lifecycle-management,lifecycle>> policy.

[[ilm-get-lifecycle-request]]
==== {api-request-title}

`GET _ilm/policy`

`GET _ilm/policy/<policy_id>`

[[ilm-get-lifecycle-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the `manage_ilm` or
`read_ilm` or both cluster privileges to use this API. For more information, see
<<security-privileges>>.

[[ilm-get-lifecycle-desc]]
==== {api-description-title}

Returns the specified policy definition. Includes the policy version and last
modified date. If no policy is specified, returns all defined policies.

[[ilm-get-lifecycle-path-params]]
==== {api-path-parms-title}

`<policy_id>`::
  (Optional, string) Identifier for the policy.

[[ilm-get-lifecycle-query-params]]
==== {api-query-parms-title}

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]

[[ilm-get-lifecycle-example]]
==== {api-examples-title}

The following example retrieves `my_policy`:

//////////////////////////

[source,console]
--------------------------------------------------
PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "warm": {
        "min_age": "10d",
        "actions": {
          "forcemerge": {
            "max_num_segments": 1
          }
        }
      },
      "delete": {
        "min_age": "30d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}
--------------------------------------------------

//////////////////////////

[source,console]
--------------------------------------------------
GET _ilm/policy/my_policy
--------------------------------------------------
// TEST[continued]


If the request succeeds, the body of the response contains the policy definition:

[source,console-result]
--------------------------------------------------
{
  "my_policy": {
    "version": 1, <1>
    "modified_date": 82392349, <2>
    "policy": {
      "phases": {
        "warm": {
          "min_age": "10d",
          "actions": {
            "forcemerge": {
              "max_num_segments": 1
            }
          }
        },
        "delete": {
          "min_age": "30d",
          "actions": {
            "delete": {
              "delete_searchable_snapshot": true
            }
          }
        }
      }
    },
    "in_use_by" : { <3>
      "indices" : [],
      "data_streams" : [],
      "composable_templates" : []
    }
  }
}
--------------------------------------------------
// TESTRESPONSE[s/"modified_date": 82392349/"modified_date": $body.my_policy.modified_date/]

<1> The policy version is incremented whenever the policy is updated
<2> When this policy was last modified
<3> Which indices, data streams, or templates currently use this policy