Get the status for a data stream lifecycle Generally available; Added in 8.11.0

GET /{index}/_lifecycle/explain
Api key auth Basic auth Bearer auth

Get information about an index or data stream's current data stream lifecycle status, such as time since index creation, time since rollover, the lifecycle configuration managing the index, or any errors encountered during lifecycle execution.

About data stream lifecycle

Path parameters

  • index string | array[string] Required

    Comma-separated list of index names to explain

Query parameters

  • include_defaults boolean

    Indicates if the API should return the default values the system uses for the index's lifecycle

    Default value is false.

  • master_timeout string

    The period to wait for a connection to the master node.

    Default value is 30s.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • indices object Required
      Hide indices attribute Show indices attribute object
      • * object Additional properties
        Hide * attributes Show * attributes object
        • index string Required
        • managed_by_lifecycle boolean Required
        • index_creation_date_millis number

          Time unit for milliseconds

        • time_since_index_creation 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.

          External documentation
        • rollover_date_millis number

          Time unit for milliseconds

        • time_since_rollover 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.

          External documentation
        • lifecycle object

          Data stream lifecycle with rollover can be used to display the configuration including the default rollover conditions, if asked.

          Hide lifecycle attributes Show lifecycle attributes object
          • downsampling array[object]

            The list of downsampling rounds to execute as part of this downsampling configuration

          • enabled boolean

            If defined, it turns data stream lifecycle on/off (true/false) for this data stream. A data stream lifecycle that's disabled (enabled: false) will have no effect on the data stream.

            Default value is true.

        • generation_time 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.

          External documentation
        • error string
        • frozen_transition_status string
        • unmanaged_reason string
GET /{index}/_lifecycle/explain 
GET .ds-metrics-2023.03.22-000001/_lifecycle/explain

resp = client.indices.explain_data_lifecycle(
    index=".ds-metrics-2023.03.22-000001",
)
const response = await client.indices.explainDataLifecycle({
  index: ".ds-metrics-2023.03.22-000001",
});
response = client.indices.explain_data_lifecycle(
  index: ".ds-metrics-2023.03.22-000001"
)
$resp = $client->indices()->explainDataLifecycle([
    "index" => ".ds-metrics-2023.03.22-000001",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/.ds-metrics-2023.03.22-000001/_lifecycle/explain"
var response = await client.Indices.ExplainDataLifecycleAsync(indices: new[] { ".ds-metrics-2023.03.22-000001" });
client.indices().explainDataLifecycle(e -> e
    .index(".ds-metrics-2023.03.22-000001")
);
Response examples (200)
A successful response from `GET .ds-metrics-2023.03.22-000001/_lifecycle/explain`, which retrieves the lifecycle status for a data stream backing index. If the index is managed by a data stream lifecycle, the API will show the `managed_by_lifecycle` field set to `true` and the rest of the response will contain information about the lifecycle status for this index. 
{
  "indices": {
    ".ds-my-data-stream-test-4-2026.10.20-000001": {
      "index": ".ds-my-data-stream-test-4-2026.10.20-000001",
      "managed_by_lifecycle": true,
      "index_creation_date_millis": 1792460913455,
      "time_since_index_creation": "1.31m",
      "lifecycle": {
        "enabled": true,
        "data_retention": "7d",
        "effective_retention": "7d",
        "retention_determined_by": "data_stream_configuration",
        "frozen_after": "30d"
      },
      "frozen_transition_status": "waiting"
    }
  }
}
The API reports any errors related to the lifecycle execution for the target index. 
{
  "indices": {
    ".ds-my-data-stream-test-2026.10.17-000001": {
      "index": ".ds-my-data-stream-test-2026.10.17-000001",
      "managed_by_lifecycle": true,
      "index_creation_date_millis": 1792195511314,
      "time_since_index_creation": "3.07d",
      "rollover_date_millis": 1792440980120,
      "time_since_rollover": "5.51h",
      "generation_time": "5.51h",
      "lifecycle": {
        "enabled": true,
        "data_retention": "30d",
        "effective_retention": "30d",
        "retention_determined_by": "data_stream_configuration"
      },
      "error": {
        "first_occurrence_millis": 1792441580075,
        "message": """{"type":"exception","reason":"Force merge request only had 1 successful shards out of a total of 2"}""",
        "last_recorded_millis": 1792460779960,
        "retry_count": 52
      }
    },
    ".ds-my-data-stream-test-2026.10.19-000002": {
      "index": ".ds-my-data-stream-test-2026.10.19-000002",
      "managed_by_lifecycle": true,
      "index_creation_date_millis": 1792440980129,
      "time_since_index_creation": "5.51h",
      "lifecycle": {
        "enabled": true,
        "data_retention": "30d",
        "effective_retention": "30d",
        "retention_determined_by": "data_stream_configuration"
      }
    }
  }
}