List APIs

Introduced 2.18

The List API retrieves statistics about indexes and shards in a paginated format. This streamlines the task of processing responses that include many indexes.

The List API supports two operations:

Shared query parameters

All List API operations support the following optional query parameters.

ParameterDescription
vProvides verbose output by adding headers to the columns. It also adds some formatting to help align each of the columns. All examples in this section include the v parameter.
helpLists the default and other available headers for a given operation.
hLimits the output to specific headers.
formatThe format in which to return the result. Valid values are json, yaml, cbor, and smile.
sSorts the output by the specified columns.

Examples

The following examples show how to use the optional query parameters to customize all List API responses.

Get verbose output

To query indexes and their statistics with a verbose output that includes all column headings in the response, use the v query parameter, as shown in the following example.

Request

  1. GET _list/indices?v

copy

Response

  1. health status index           uuid    pri rep  docs.count  docs.deleted
  2. green  open   .kibana_1 - - - -              
  3. yellow open    sample-index-1 - - - -
  4. next_token null

Get all available headers

To see all the available headers, use the help parameter with the following syntax:

  1. GET _list/<operation_name>?help

copy

Request

The following example list indices operation returns all the available headers:

  1. GET _list/indices?help

copy

Response

The following example displays the indexes and their health status in a table:

  1. health     | h                              | current health status
  2. status     | s                              | open/close status
  3. index      | i,idx                          | index name
  4. uuid       | id,uuid                        | index uuid
  5. pri        | p,shards.primary,shardsPrimary | number of primary shards
  6. rep        | r,shards.replica,shardsReplica | number of replica shards
  7. docs.count | dc,docsCount                   | available docs

Get a subset of headers

To limit the output to a subset of headers, use the h parameter with the following syntax:

  1. GET _list/<operation_name>?h=<header_name_1>,<header_name_2>&v

copy

For any operation, you can determine which headers are available by using the help parameter and then using the h parameter to limit the output to only a subset of headers.

Request

The following example limits the indexes in the response to only the index name and health status headers:

  1. GET _list/indices?h=health,index

copy

Response

  1. green  .kibana_1
  2. yellow sample-index-1
  3. next_token null

Sort by a header

To sort the output on a single page by a header, use the s parameter with the following syntax:

  1. GET _list/<operation_name>?s=<header_name_1>,<header_name_2>

copy

Request

The following example request sorts indexes by index name:

  1. GET _list/indices?s=h,i

copy

Response

  1. green sample-index-2
  2. yellow sample-index-1
  3. next_token null

Retrieve data in JSON format

By default, List APIs return data in a text/plain format. Other supported formats are YAML, CBOR, and Smile.

To retrieve data in the JSON format, use the format=json parameter with the following syntax.

If you use the Security plugin, ensure you have the appropriate permissions.

Request

  1. GET _list/<operation_name>?format=json

copy

Request

  1. GET _list/indices?format=json

copy

Response

The response contains data in JSON format:

  1. {"next_token":null,"indices":[{"health":"green","status":"-","index":".kibana_1","uuid":"-","pri":"-","rep":"-","docs.count":"-","docs.deleted":"-","store.size":"-","pri.store.size":"-"},{"health":"yellow","status":"-","index":"sample-index-1","uuid":"-","pri":"-","rep":"-","docs.count":"-","docs.deleted":"-","store.size":"-","pri.store.size":"-"}]}