[[data-streams-explain-lifecycle]]
=== Explain data stream lifecycle
++++
<titleabbrev>Explain Data Stream Lifecycle</titleabbrev>
++++

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

Retrieves the current <<data-stream-lifecycle,data stream lifecycle>> status for one or more data stream backing indices.

[[explain-lifecycle-api-prereqs]]
==== {api-prereq-title}

If the {es} {security-features} are enabled, you must have at least the `manage_data_stream_lifecycle` index privilege or
`view_index_metadata` index privilege to use this API. For more information, see <<security-privileges>>.

[[data-streams-explain-lifecycle-request]]
==== {api-request-title}

`GET <target>/_lifecycle/explain`

[[data-streams-explain-lifecycle-desc]]
==== {api-description-title}

Retrieves information about the index or data stream's current data stream lifecycle state, such as
time since index creation, time since rollover, the lifecycle configuration
managing the index, or any error that {es} might've encountered during the lifecycle
execution.

[[data-streams-explain-lifecycle-path-params]]
==== {api-path-parms-title}

`<target>`::
(Required, string) Comma-separated list of indices or data streams.

[[data-streams-explain-lifecycle-query-params]]
==== {api-query-parms-title}

`include_defaults`::
  (Optional, Boolean) Includes default configurations related to the lifecycle of the target.
  Defaults to `false`.

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

[[data-streams-explain-lifecycle-example]]
==== {api-examples-title}

If you want to retrieve the lifecycle state of all the backing indices of a data stream, you can use the data stream name.
For simplicity, the following example retrieves the lifecycle state of one backing index `.ds-metrics-2023.03.22-000001`:

[source,console]
--------------------------------------------------
GET .ds-metrics-2023.03.22-000001/_lifecycle/explain
--------------------------------------------------
// TEST[skip:we're not setting up data stream lifecycle in these tests]

If the index is managed by a data stream lifecycle `explain` will show the `managed_by_lifecycle` field
set to `true` and the rest of the response will contain information about the
lifecycle execution status for this index:

[source,console-result]
--------------------------------------------------
{
  "indices": {
    ".ds-metrics-2023.03.22-000001": {
      "index" : ".ds-metrics-2023.03.22-000001",
      "managed_by_lifecycle" : true,                        <1>
      "index_creation_date_millis" : 1679475563571,   <2>
      "time_since_index_creation" : "843ms",          <3>
      "rollover_date_millis" : 1679475564293,         <4>
      "time_since_rollover" : "121ms",                <5>
      "lifecycle" : { },                              <6>
      "generation_time" : "121ms"                     <7>
  }
}
--------------------------------------------------
// TESTRESPONSE[skip:the result is for illustrating purposes only]

<1> Shows if the index is being managed by data stream lifecycle. If the index is not managed by
a data stream lifecycle the other fields will not be shown
<2> When the index was created, this timestamp is used to determine when to
rollover
<3> The time since the index creation (used for calculating when to rollover
the index via the `max_age`)
<4> When the index was rolled over. If the index was not rolled over this will not be
shown.
<5> The time since rollover. If the index was not rolled over this will not be shown.
<6> The lifecycle configuration that applies to this index (which is configured on the parent
data stream)
<7> The generation time of the index represents the time since the index started progressing
towards the user configurable / business specific parts of the lifecycle (e.g. retention).
The `generation_time` is calculated from the origination date if it exists, or from the
rollover date if it exists, or from the creation date if neither of the other two exist.
If the index is the write index the `generation_time` will not be reported because it is not
eligible for retention or other parts of the lifecycle.

The `explain` will also report any errors related to the lifecycle execution for the target
index:

[source,console-result]
--------------------------------------------------
{
  "indices": {
    ".ds-metrics-2023.03.22-000001": {
      "index" : ".ds-metrics-2023.03.22-000001",
      "managed_by_lifecycle" : true,
      "index_creation_date_millis" : 1679475563571,
      "time_since_index_creation" : "843ms",
      "lifecycle" : {
        "enabled": true
      },
      "error": "{\"type\":\"validation_exception\",\"reason\":\"Validation Failed: 1: this action would add [2] shards, but this cluster
currently has [4]/[3] maximum normal shards open;\"}"        <1>
  }
}
--------------------------------------------------
// TESTRESPONSE[skip:the result is for illustrating purposes only]

<1> The target index could not be rolled over due to a limitation in the number of shards
allowed in the cluster.