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.
| Parameter | Description |
|---|---|
v | Provides 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. |
help | Lists the default and other available headers for a given operation. |
h | Limits the output to specific headers. |
format | The format in which to return the result. Valid values are json, yaml, cbor, and smile. |
s | Sorts 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
GET _list/indices?v
Response
health status index uuid pri rep docs.count docs.deleted
green open .kibana_1 - - - -
yellow open sample-index-1 - - - -
next_token null
Get all available headers
To see all the available headers, use the help parameter with the following syntax:
GET _list/<operation_name>?help
Request
The following example list indices operation returns all the available headers:
GET _list/indices?help
Response
The following example displays the indexes and their health status in a table:
health | h | current health status
status | s | open/close status
index | i,idx | index name
uuid | id,uuid | index uuid
pri | p,shards.primary,shardsPrimary | number of primary shards
rep | r,shards.replica,shardsReplica | number of replica shards
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:
GET _list/<operation_name>?h=<header_name_1>,<header_name_2>&v
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:
GET _list/indices?h=health,index
Response
green .kibana_1
yellow sample-index-1
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:
GET _list/<operation_name>?s=<header_name_1>,<header_name_2>
Request
The following example request sorts indexes by index name:
GET _list/indices?s=h,i
Response
green sample-index-2
yellow sample-index-1
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
GET _list/<operation_name>?format=json
Request
GET _list/indices?format=json
Response
The response contains data in JSON format:
{"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":"-"}]}