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

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

Retrieves a lifecycle policy.

==== Request

`GET _ilm/policy`
`GET _ilm/policy/<policy_id>`

==== Description

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

==== Path Parameters

`policy` (optional)::
  (string) Identifier for the policy.

==== Request Parameters

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

==== Authorization

You must have the `manage_ilm` or `read_ilm` or both cluster privileges to use this API.
For more information, see <<security-privileges>>.

==== Examples

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": {}
          }
        }
      }
    }
  }
}
--------------------------------------------------
// 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