---
type: api
title: Explain the lifecycle state
description: Get the current lifecycle status for one or more indices.
url: https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-ilm-explain-lifecycle
resource: https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-ilm-explain-lifecycle
products:
  - Elasticsearch
---

# Explain the lifecycle state

Authentication: required

Availability: Generally available since 6.6

## Paths

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

#### Path parameters

- `index` (string) — required
  Comma-separated list of data streams, indices, and aliases to target. Supports wildcards (`*`).
To target all data streams and indices, use `*` or `_all`.

## Description

Get the current lifecycle status for one or more indices.
For data streams, the API retrieves the current lifecycle status for the stream's backing indices.

The response indicates when the index entered each lifecycle state, provides the definition of the running phase, and information about any failures.

## Required privileges

- Index privileges: `view_index_metadata`, `manage_ilm`

## Query string parameters

- `only_errors` (boolean) — optional
  Filters the returned indices to only indices that are managed by ILM and are in an error state, either due to an encountering an error while executing the policy, or attempting to use a policy that does not exist.
- `only_managed` (boolean) — optional
  Filters the returned indices to only indices that are managed by ILM.
- `master_timeout` (union oneOf · default: 30s) — optional
  Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
  Values: `-1`, `0`

## Response

`application/json`

- `indices` (map string to oneOf)
  Map values (union oneOf)
  One of:
  - **managed: true** (`managed: true`)
    - `managed` (enum)
      Values: `true`
    - `action` (string)
    - `action_time` (union oneOf)
      One of: `string` or `number`
    - `action_time_millis` (number)
    - `age` (union oneOf)
      Values: `-1`, `0`
    - `failed_step` (string)
    - `failed_step_retry_count` (number)
    - `index` (string)
    - `index_creation_date` (union oneOf)
      One of: `string` or `number`
    - `index_creation_date_millis` (number)
    - `is_auto_retryable_error` (boolean)
    - `lifecycle_date` (union oneOf)
      One of: `string` or `number`
    - `lifecycle_date_millis` (number)
    - `phase` (string)
    - `phase_time` (union oneOf)
      One of: `string` or `number`
    - `phase_time_millis` (number)
    - `policy` (string)
    - `previous_step_info` (map string to object)
    - `repository_name` (string)
    - `snapshot_name` (string)
    - `shrink_index_name` (string)
    - `step` (string)
    - `step_info` (map string to object)
    - `step_time` (union oneOf)
      One of: `string` or `number`
    - `step_time_millis` (number)
    - `phase_execution` (object)
      - `phase_definition` (object)
        - `actions` (object)
          - `allocate` (object)
            Phases allowed: warm, cold.
            - `number_of_replicas` (number)
            - `total_shards_per_node` (number)
            - `include` (map string to string)
            - `exclude` (map string to string)
            - `require` (map string to string)
          - `delete` (object)
            Phases allowed: delete.
            - `delete_searchable_snapshot` (boolean)
          - `downsample` (object)
            Phases allowed: hot, warm, cold.
            - `fixed_interval` (string)
            - `wait_timeout` (union oneOf)
              Values: `-1`, `0`
          - `freeze` (object) — deprecated
            The freeze action is a noop in 8.x
          - `forcemerge` (object)
            Phases allowed: hot, warm.
            - `max_num_segments` (number)
            - `index_codec` (string)
          - `migrate` (object)
            Phases allowed: warm, cold.
            - `enabled` (boolean)
          - `readonly` (object)
            Phases allowed: hot, warm, cold.
          - `rollover` (object)
            Phases allowed: hot.
            - `max_size` (number | string)
            - `max_primary_shard_size` (number | string)
            - `max_age` (union oneOf)
              Values: `-1`, `0`
            - `max_docs` (number)
            - `max_primary_shard_docs` (number)
            - `min_size` (number | string)
            - `min_primary_shard_size` (number | string)
            - `min_age` (union oneOf)
              Values: `-1`, `0`
            - `min_docs` (number)
            - `min_primary_shard_docs` (number)
          - `set_priority` (object)
            Phases allowed: hot, warm, cold.
            - `priority` (number)
          - `searchable_snapshot` (object)
            Phases allowed: hot, cold, frozen.
            - `snapshot_repository` (string)
            - `force_merge_index` (boolean)
            - `total_shards_per_node` (number)
              The maximum number of shards, including primaries and replicas, that can be allocated to any single node for the mounted index.
Must be at least 1.
            - `replicate_for` (union oneOf)
              The period for which the mounted index keeps one replica before the replica is removed.
By default, the index is mounted without replicas.
Must be positive.
Only the first `searchable_snapshot` action in a policy may set this.
It must fit before the next phase starts: for example, if this phase has a `min_age` of 5d and the next phase has 12d, it can be at most 7d.
              Values: `-1`, `0`
          - `shrink` (object)
            Phases allowed: hot, warm.
            - `number_of_shards` (number)
            - `max_primary_shard_size` (number | string)
            - `allow_write_after_shrink` (boolean)
          - `unfollow` (object)
            Phases allowed: hot, warm, cold, frozen.
          - `wait_for_snapshot` (object)
            Phases allowed: delete.
            - `policy` (string)
        - `min_age` (union oneOf)
          Values: `-1`, `0`
      - `policy` (string)
      - `version` (number)
      - `modified_date_in_millis` (number)
    - `time_since_index_creation` (union oneOf)
      Values: `-1`, `0`
    - `skip` (boolean)
  - **managed: false** (`managed: false`)
    - `managed` (enum)
      Values: `false`
    - `index` (string)
## Code examples

#### Console

```console
GET .ds-timeseries-*/_ilm/explain
```

#### JavaScript

```javascript
const response = await client.ilm.explainLifecycle({
  index: ".ds-timeseries-*",
});
```

#### Python

```python
resp = client.ilm.explain_lifecycle(
    index=".ds-timeseries-*",
)
```

#### curl

```curl
curl -X GET "$ELASTICSEARCH_URL/.ds-timeseries-*/_ilm/explain" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY"
```

#### Java

```java
client.ilm().explainLifecycle(e -> e
    .index(".ds-timeseries-*")
);
```

#### C#

```c#
var response = await client.IndexLifecycleManagement.ExplainLifecycleAsync(index: ".ds-timeseries-*");
```

#### PHP

```php
$resp = $client->ilm()->explainLifecycle([
    "index" => ".ds-timeseries-*",
]);
```

#### Ruby

```ruby
response = client.ilm.explain_lifecycle(
  index: ".ds-timeseries-*"
)
```

## Response examples

#### Explain lifecycle response example1

`application/json`

A successful response when retrieving the current ILM status for an index.

```json
{
  "indices": {
    "my-index-000001": {
      "index": "my-index-000001",
      "index_creation_date_millis": 1538475653281,
      "index_creation_date": "2018-10-15T13:45:21.981Z",
      "time_since_index_creation": "15s",
      "managed": true,
      "policy": "my_policy",
      "lifecycle_date_millis": 1538475653281,
      "lifecycle_date": "2018-10-15T13:45:21.981Z",
      "age": "15s",
      "phase": "new",
      "phase_time_millis": 1538475653317,
      "phase_time": "2018-10-15T13:45:22.577Z",
      "action": "complete"
      "action_time_millis": 1538475653317,
      "action_time": "2018-10-15T13:45:22.577Z",
      "step": "complete",
      "step_time_millis": 1538475653317,
      "step_time": "2018-10-15T13:45:22.577Z"
    }
  }
}
```