---
type: api
title: Get the status for a data stream lifecycle
description: 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.
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch-serverless/operation/operation-indices-explain-data-lifecycle
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch-serverless/operation/operation-indices-explain-data-lifecycle
products:
  - Elasticsearch Serverless
---

# Get the status for a data stream lifecycle

Availability:

## Paths

- `GET` `/{index}/_lifecycle/explain`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch-serverless/authentication#apikeyauth)

#### Path Parameters

- `index` (union IndexName | [] IndexName)
  Comma-separated list of index names to explain

## Description

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](https://www.elastic.co/docs/manage-data/lifecycle/data-stream)

## Query String Parameters

- `include_defaults` (boolean · default: false)
  Indicates if the API should return the default values the system uses for the index's lifecycle
- `master_timeout` (string Duration · default: 30s)
  The period to wait for a connection to the master node.

## Response

`application/json`

- `indices` (map string to DataStreamLifecycleExplain)
  Map values ({} DataStreamLifecycleExplain)
  - `index` (string IndexName)
  - `managed_by_lifecycle` (boolean)
  - `index_creation_date_millis` (EpochTimeUnitMillis)
  - `time_since_index_creation` (string Duration)
  - `rollover_date_millis` (EpochTimeUnitMillis)
  - `time_since_rollover` (string Duration)
  - `lifecycle` ({} DataStreamLifecycleWithRollover)
    - `data_retention` (string Duration)
      If defined, every document added to this data stream will be stored at least for this time frame.
Any time after this duration the document could be deleted.
When empty, every document in this data stream will be stored indefinitely.
    - `effective_retention` (string Duration)
      The least amount of time data should be kept by elasticsearch.
    - `retention_determined_by` (enum RetentionSource)
      Configuration source that can influence the retention of a data stream.
      Values: `data_stream_configuration`, `default_global_retention`, `max_global_retention`, `default_failures_retention`
    - `downsampling` ([] DownsamplingRound)
      The list of downsampling rounds to execute as part of this downsampling configuration
      - `after` (string Duration)
        The duration since rollover when this downsampling round should execute
      - `fixed_interval` (string)
        The downsample interval.
    - `downsampling_method` (enum SamplingMethod)
      The method used to downsample the data. There are two options `aggregate` and `last_value`. It requires
`downsampling` to be defined. Defaults to `aggregate`.
      Values: `aggregate`, `last_value`
    - `enabled` (boolean · default: true)
      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.
    - `rollover` ({} DataStreamLifecycleRolloverConditions)
      The conditions which will trigger the rollover of a backing index as configured by the cluster setting `cluster.lifecycle.default.rollover`.
This property is an implementation detail and it will only be retrieved when the query param `include_defaults` is set to true.
The contents of this field are subject to change.
      - `min_age` (string Duration)
      - `max_age` (string)
      - `min_docs` (number)
      - `max_docs` (number)
      - `min_size` (number | string ByteSize)
      - `max_size` (number | string ByteSize)
      - `min_primary_shard_size` (number | string ByteSize)
      - `max_primary_shard_size` (number | string ByteSize)
      - `min_primary_shard_docs` (number)
      - `max_primary_shard_docs` (number)
  - `generation_time` (string Duration)
  - `error` (string)
## Code Examples

#### Console

```console
GET .ds-metrics-2023.03.22-000001/_lifecycle/explain
```

#### JavaScript

```javascript
const response = await client.indices.explainDataLifecycle({
  index: ".ds-metrics-2023.03.22-000001",
});
```

#### Python

```python
resp = client.indices.explain_data_lifecycle(
    index=".ds-metrics-2023.03.22-000001",
)
```

#### curl

```curl
curl -X GET "$ELASTICSEARCH_URL/.ds-metrics-2023.03.22-000001/_lifecycle/explain" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY"
```

#### Java

```java
client.indices().explainDataLifecycle(e -> e
    .index(".ds-metrics-2023.03.22-000001")
);
```

#### C#

```c#
var response = await client.Indices.ExplainDataLifecycleAsync(indices: new[] { ".ds-metrics-2023.03.22-000001" });
```

#### PHP

```php
$resp = $client->indices()->explainDataLifecycle([
    "index" => ".ds-metrics-2023.03.22-000001",
]);
```

#### Ruby

```ruby
response = client.indices.explain_data_lifecycle(
  index: ".ds-metrics-2023.03.22-000001"
)
```

## Response Examples

#### Successful response

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 execution status for this index.

```json
{
  "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",
      "rollover_date_millis" : 1679475564293,
      "time_since_rollover" : "121ms",
      "lifecycle" : { },
      "generation_time" : "121ms"
  }
}
```

#### Successful response with error messages

The API reports any errors related to the lifecycle execution for the target index.

```json
{
  "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;\"}"
  }
}
```