Get a document count
Generally available
Get quick access to a document count for a data stream, an index, or an entire cluster. The document count only includes live documents, not deleted documents which have not yet been removed by the merge process.
IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the count API.
Required authorization
- Index privileges:
read
Path parameters
-
index
string | array[string] Required A comma-separated list of data streams, indices, and aliases used to limit the request. It supports wildcards (
*
). To target all data streams and indices, omit this parameter or use*
or_all
.
GET /_cat/count/my-index-000001?v=true&format=json
resp = client.cat.count(
index="my-index-000001",
v=True,
format="json",
)
const response = await client.cat.count({
index: "my-index-000001",
v: "true",
format: "json",
});
response = client.cat.count(
index: "my-index-000001",
v: "true",
format: "json"
)
$resp = $client->cat()->count([
"index" => "my-index-000001",
"v" => "true",
"format" => "json",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/count/my-index-000001?v=true&format=json"
[
{
"epoch": "1475868259",
"timestamp": "15:24:20",
"count": "120"
}
]
[
{
"epoch": "1475868259",
"timestamp": "15:24:20",
"count": "121"
}
]
Get field data cache information
Generally available
Get the amount of heap memory currently used by the field data cache on every data node in the cluster.
IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes stats API.
Required authorization
- Cluster privileges:
monitor
Query parameters
-
bytes
string The unit used to display byte values.
Values are
b
,kb
,mb
,gb
,tb
, orpb
. -
fields
string | array[string] Comma-separated list of fields used to limit returned information.
-
h
string | array[string] List of columns to appear in the response. Supports simple wildcards.
-
s
string | array[string] List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting
:asc
or:desc
as a suffix to the column name.
GET /_cat/fielddata?v=true&fields=body&format=json
resp = client.cat.fielddata(
v=True,
fields="body",
format="json",
)
const response = await client.cat.fielddata({
v: "true",
fields: "body",
format: "json",
});
response = client.cat.fielddata(
v: "true",
fields: "body",
format: "json"
)
$resp = $client->cat()->fielddata([
"v" => "true",
"fields" => "body",
"format" => "json",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/fielddata?v=true&fields=body&format=json"
[
{
"id": "Nqk-6inXQq-OxUfOUI8jNQ",
"host": "127.0.0.1",
"ip": "127.0.0.1",
"node": "Nqk-6in",
"field": "body",
"size": "544b"
}
]
[
{
"id": "Nqk-6inXQq-OxUfOUI8jNQ",
"host": "1127.0.0.1",
"ip": "127.0.0.1",
"node": "Nqk-6in",
"field": "body",
"size": "544b"
},
{
"id": "Nqk-6inXQq-OxUfOUI8jNQ",
"host": "127.0.0.1",
"ip": "127.0.0.1",
"node": "Nqk-6in",
"field": "soul",
"size": "480b"
}
]
Get pending task information
Generally available
Get information about cluster-level changes that have not yet taken effect. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the pending cluster tasks API.
Required authorization
- Cluster privileges:
monitor
Query parameters
-
h
string | array[string] List of columns to appear in the response. Supports simple wildcards.
-
s
string | array[string] List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting
:asc
or:desc
as a suffix to the column name. -
local
boolean If
true
, the request computes the list of selected nodes from the local cluster state. Iffalse
the list of selected nodes are computed from the cluster state of the master node. In both cases the coordinating node will send requests for further information to each selected node. -
master_timeout
string Period to wait for a connection to the master node.
Values are
-1
or0
. -
time
string Unit used to display time values.
Values are
nanos
,micros
,ms
,s
,m
,h
, ord
.
GET /_cat/pending_tasks?v=trueh=insertOrder,timeInQueue,priority,source&format=json
resp = client.cat.pending_tasks(
v="trueh=insertOrder,timeInQueue,priority,source",
format="json",
)
const response = await client.cat.pendingTasks({
v: "trueh=insertOrder,timeInQueue,priority,source",
format: "json",
});
response = client.cat.pending_tasks(
v: "trueh=insertOrder,timeInQueue,priority,source",
format: "json"
)
$resp = $client->cat()->pendingTasks([
"v" => "trueh=insertOrder,timeInQueue,priority,source",
"format" => "json",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/pending_tasks?v=trueh=insertOrder,timeInQueue,priority,source&format=json"
[
{ "insertOrder": "1685", "timeInQueue": "855ms", "priority": "HIGH", "source": "update-mapping [foo][t]"},
{ "insertOrder": "1686", "timeInQueue": "843ms", "priority": "HIGH", "source": "update-mapping [foo][t]"},
{ "insertOrder": "1693", "timeInQueue": "753ms", "priority": "HIGH", "source": "refresh-mapping [foo][[t]]"},
{ "insertOrder": "1688", "timeInQueue": "816ms", "priority": "HIGH", "source": "update-mapping [foo][t]"},
{ "insertOrder": "1689", "timeInQueue": "802ms", "priority": "HIGH", "source": "update-mapping [foo][t]"},
{ "insertOrder": "1690", "timeInQueue": "787ms", "priority": "HIGH", "source": "update-mapping [foo][t]"},
{ "insertOrder": "1691", "timeInQueue": "773ms", "priority": "HIGH", "source": "update-mapping [foo][t]"}
]
Get shard information
Generally available
Get information about the shards in a cluster. For data streams, the API returns information about the backing indices. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications.
Required authorization
- Index privileges:
monitor
- Cluster privileges:
monitor
Path parameters
-
index
string | array[string] Required A comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (
*
). To target all data streams and indices, omit this parameter or use*
or_all
.
Query parameters
-
bytes
string The unit used to display byte values.
Values are
b
,kb
,mb
,gb
,tb
, orpb
. -
h
string | array[string] List of columns to appear in the response. Supports simple wildcards.
-
s
string | array[string] List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting
:asc
or:desc
as a suffix to the column name. -
master_timeout
string Period to wait for a connection to the master node.
Values are
-1
or0
. -
time
string Unit used to display time values.
Values are
nanos
,micros
,ms
,s
,m
,h
, ord
.
GET _cat/shards?format=json
resp = client.cat.shards(
format="json",
)
const response = await client.cat.shards({
format: "json",
});
response = client.cat.shards(
format: "json"
)
$resp = $client->cat()->shards([
"format" => "json",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/shards?format=json"
[
{
"index": "my-index-000001",
"shard": "0",
"prirep": "p",
"state": "STARTED",
"docs": "3014",
"store": "31.1mb",
"dataset": "249b",
"ip": "192.168.56.10",
"node": "H5dfFeA"
}
]
[
{
"index": "my-index-000001",
"shard": "0",
"prirep": "p",
"state": "STARTED",
"docs": "3014",
"store": "31.1mb",
"dataset": "249b",
"ip": "192.168.56.10",
"node": "H5dfFeA"
}
]
[
{
"index": "my-index-000001",
"shard": "0",
"prirep": "p",
"state": "RELOCATING",
"docs": "3014",
"store": "31.1mb",
"dataset": "249b",
"ip": "192.168.56.10",
"node": "H5dfFeA -> -> 192.168.56.30 bGG90GE"
}
]
[
{
"index": "my-index-000001",
"shard": "0",
"prirep": "p",
"state": "STARTED",
"docs": "3014",
"store": "31.1mb",
"dataset": "249b",
"ip": "192.168.56.10",
"node": "H5dfFeA"
},
{
"index": "my-index-000001",
"shard": "0",
"prirep": "r",
"state": "INITIALIZING",
"docs": "0",
"store": "14.3mb",
"dataset": "249b",
"ip": "192.168.56.30",
"node": "bGG90GE"
}
]
[
{
"index": "my-index-000001",
"shard": "0",
"prirep": "p",
"state": "STARTED",
"unassigned.reason": "3014 31.1mb 192.168.56.10 H5dfFeA"
},
{
"index": "my-index-000001",
"shard": "0",
"prirep": "r",
"state": "STARTED",
"unassigned.reason": "3014 31.1mb 192.168.56.30 bGG90GE"
},
{
"index": "my-index-000001",
"shard": "0",
"prirep": "r",
"state": "STARTED",
"unassigned.reason": "3014 31.1mb 192.168.56.20 I8hydUG"
},
{
"index": "my-index-000001",
"shard": "0",
"prirep": "r",
"state": "UNASSIGNED",
"unassigned.reason": "ALLOCATION_FAILED"
}
]
Get snapshot information
Generally available; Added in 2.1.0
Get information about the snapshots stored in one or more repositories. A snapshot is a backup of an index or running Elasticsearch cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get snapshot API.
Required authorization
- Cluster privileges:
monitor_snapshot
Query parameters
-
h
string | array[string] List of columns to appear in the response. Supports simple wildcards.
-
s
string | array[string] List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting
:asc
or:desc
as a suffix to the column name. -
master_timeout
string Period to wait for a connection to the master node.
Values are
-1
or0
. -
time
string Unit used to display time values.
Values are
nanos
,micros
,ms
,s
,m
,h
, ord
.
GET /_cat/snapshots/repo1?v=true&s=id&format=json
resp = client.cat.snapshots(
repository="repo1",
v=True,
s="id",
format="json",
)
const response = await client.cat.snapshots({
repository: "repo1",
v: "true",
s: "id",
format: "json",
});
response = client.cat.snapshots(
repository: "repo1",
v: "true",
s: "id",
format: "json"
)
$resp = $client->cat()->snapshots([
"repository" => "repo1",
"v" => "true",
"s" => "id",
"format" => "json",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/snapshots/repo1?v=true&s=id&format=json"
[
{
"id": "snap1",
"repository": "repo1",
"status": "FAILED",
"start_epoch": "1445616705",
"start_time": "18:11:45",
"end_epoch": "1445616978",
"end_time": "18:16:18",
"duration": "4.6m",
"indices": "1",
"successful_shards": "4",
"failed_shards": "1",
"total_shards": "5"
},
{
"id": "snap2",
"repository": "repo1",
"status": "SUCCESS",
"start_epoch": "1445634298",
"start_time": "23:04:58",
"end_epoch": "1445634672",
"end_time": "23:11:12",
"duration": "6.2m",
"indices": "2",
"successful_shards": "10",
"failed_shards": "0",
"total_shards": "10"
}
]
Get task information
Technical preview; Added in 5.0.0
Get information about tasks currently running in the cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the task management API.
Required authorization
- Cluster privileges:
monitor
Query parameters
-
actions
array[string] The task action names, which are used to limit the response.
-
detailed
boolean If
true
, the response includes detailed information about shard recoveries. -
nodes
array[string] Unique node identifiers, which are used to limit the response.
-
parent_task_id
string The parent task identifier, which is used to limit the response.
-
h
string | array[string] List of columns to appear in the response. Supports simple wildcards.
-
s
string | array[string] List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting
:asc
or:desc
as a suffix to the column name. -
time
string Unit used to display time values.
Values are
nanos
,micros
,ms
,s
,m
,h
, ord
. -
timeout
string Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are
-1
or0
. -
wait_for_completion
boolean If
true
, the request blocks until the task has completed.
GET _cat/tasks?v=true&format=json
resp = client.cat.tasks(
v=True,
format="json",
)
const response = await client.cat.tasks({
v: "true",
format: "json",
});
response = client.cat.tasks(
v: "true",
format: "json"
)
$resp = $client->cat()->tasks([
"v" => "true",
"format" => "json",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/tasks?v=true&format=json"
[
{
"action": "cluster:monitor/tasks/lists[n]",
"task_id": "oTUltX4IQMOUUVeiohTt8A:124",
"parent_task_id": "oTUltX4IQMOUUVeiohTt8A:123",
"type": "direct",
"start_time": "1458585884904",
"timestamp": "01:48:24",
"running_time": "44.1micros",
"ip": "127.0.0.1:9300",
"node": "oTUltX4IQMOUUVeiohTt8A"
},
{
"action": "cluster:monitor/tasks/lists",
"task_id": "oTUltX4IQMOUUVeiohTt8A:123",
"parent_task_id": "-",
"type": "transport",
"start_time": "1458585884904",
"timestamp": "01:48:24",
"running_time": "186.2micros",
"ip": "127.0.0.1:9300",
"node": "oTUltX4IQMOUUVeiohTt8A"
}
]