The API accepts 3 different authentication methods:
Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example:
curl -X GET "${ES_URL}/_cat/indices?v=true" \
-H "Authorization: ApiKey ${API_KEY}"
To get API keys, use the /_security/api_key APIs.
Basic auth tokens are constructed with the Basic keyword, followed by a space, followed by a base64-encoded string of your username:password
(separated by a : colon).
Example: send a Authorization: Basic aGVsbG86aGVsbG8=
HTTP header with your requests to authenticate with the API.
Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API.
For examples, refer to Token-based authentication services
NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
the name of the autoscaling policy
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.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request DELETE 'http://api.example.com/_autoscaling/policy/{name}' \
--header "Authorization: $API_KEY"{
"acknowledged": true
}The name of the behavioral analytics collection.
The analytics event type.
Values are page_view, search, or search_click.
Whether the response type has to include more details
curl \
--request POST 'http://api.example.com/_application/analytics/{collection_name}/event/{event_type}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"session\": {\n \"id\": \"1797ca95-91c9-4e2e-b1bd-9c38e6f386a9\"\n },\n \"user\": {\n \"id\": \"5f26f01a-bbee-4202-9298-81261067abbd\"\n },\n \"search\":{\n \"query\": \"search term\",\n \"results\": {\n \"items\": [\n {\n \"document\": {\n \"id\": \"123\",\n \"index\": \"products\"\n }\n }\n ],\n \"total_results\": 10\n },\n \"sort\": {\n \"name\": \"relevance\"\n },\n \"search_application\": \"website\"\n },\n \"document\":{\n \"id\": \"123\",\n \"index\": \"products\"\n }\n}"'{
"session": {
"id": "1797ca95-91c9-4e2e-b1bd-9c38e6f386a9"
},
"user": {
"id": "5f26f01a-bbee-4202-9298-81261067abbd"
},
"search":{
"query": "search term",
"results": {
"items": [
{
"document": {
"id": "123",
"index": "products"
}
}
],
"total_results": 10
},
"sort": {
"name": "relevance"
},
"search_application": "website"
},
"document":{
"id": "123",
"index": "products"
}
}The compact and aligned text (CAT) APIs aim are intended only for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, it's recommend to use a corresponding JSON API.
All the cat commands accept a query string parameter help to see all the headers and info they provide, and the /_cat command alone lists all the available commands.
Get a snapshot of the number of shards allocated to each data node and their disk space.
IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications.
A comma-separated list of node identifiers or names used to limit the returned information.
The unit used to display byte values.
Values are b, kb, mb, gb, tb, or pb.
List of columns to appear in the response. Supports simple wildcards.
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.
If true, the request computes the list of selected nodes from the
local cluster state. If false 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.
Period to wait for a connection to the master node.
curl \
--request GET 'http://api.example.com/_cat/allocation/{node_id}' \
--header "Authorization: $API_KEY"[
{
"shards": "1",
"shards.undesired": "0",
"write_load.forecast": "0.0",
"disk.indices.forecast": "260b",
"disk.indices": "260b",
"disk.used": "47.3gb",
"disk.avail": "43.4gb",
"disk.total": "100.7gb",
"disk.percent": "46",
"host": "127.0.0.1",
"ip": "127.0.0.1",
"node": "CSUXak2",
"node.role": "himrst"
}
]Get information about component templates in a cluster. Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.
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 component template API.
The name of the component template. It accepts wildcard expressions. If it is omitted, all component templates are returned.
List of columns to appear in the response. Supports simple wildcards.
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.
If true, the request computes the list of selected nodes from the
local cluster state. If false 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.
The period to wait for a connection to the master node.
curl \
--request GET 'http://api.example.com/_cat/component_templates/{name}' \
--header "Authorization: $API_KEY"[
{
"name": "my-template-1",
"version": "null",
"alias_count": "0",
"mapping_count": "0",
"settings_count": "1",
"metadata_count": "0",
"included_in": "[my-index-template]"
},
{
"name": "my-template-2",
"version": null,
"alias_count": "0",
"mapping_count": "3",
"settings_count": "0",
"metadata_count": "0",
"included_in": "[my-index-template]"
}
]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.
curl \
--request GET 'http://api.example.com/_cat/count' \
--header "Authorization: $API_KEY"[
{
"epoch": "1475868259",
"timestamp": "15:24:20",
"count": "120"
}
][
{
"epoch": "1475868259",
"timestamp": "15:24:20",
"count": "121"
}
]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.
Comma-separated list of fields used to limit returned information. To retrieve all fields, omit this parameter.
The unit used to display byte values.
Values are b, kb, mb, gb, tb, or pb.
Comma-separated list of fields used to limit returned information.
List of columns to appear in the response. Supports simple wildcards.
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.
curl \
--request GET 'http://api.example.com/_cat/fielddata/{fields}' \
--header "Authorization: $API_KEY"[
{
"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"
}
]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 cluster health API.
This API is often used to check malfunctioning clusters.
To help you track cluster health alongside log files and alerting systems, the API returns timestamps in two formats:
HH:MM:SS, which is human-readable but includes no date information;
Unix epoch time, which is machine-sortable and includes date information.
The latter format is useful for cluster recoveries that take multiple days.
You can use the cat health API to verify cluster health across multiple nodes.
You also can use the API to track the recovery of a large cluster over a longer period of time.
The unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
If true, returns HH:MM:SS and Unix epoch timestamps.
List of columns to appear in the response. Supports simple wildcards.
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.
curl \
--request GET 'http://api.example.com/_cat/health' \
--header "Authorization: $API_KEY"[
{
"epoch": "1475871424",
"timestamp": "16:17:04",
"cluster": "elasticsearch",
"status": "green",
"node.total": "1",
"node.data": "1",
"shards": "1",
"pri": "1",
"relo": "0",
"init": "0",
"unassign": "0",
"unassign.pri": "0",
"pending_tasks": "0",
"max_task_wait_time": "-",
"active_shards_percent": "100.0%"
}
]curl \
--request GET 'http://api.example.com/_cat' \
--header "Authorization: $API_KEY"Get configuration and usage information about datafeeds.
This API returns a maximum of 10,000 datafeeds.
If the Elasticsearch security features are enabled, you must have monitor_ml, monitor, manage_ml, or manage
cluster privileges to use this API.
IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get datafeed statistics API.
Specifies what to do when the request:
_all string or no identifiers and there are no matches.If true, the API returns an empty datafeeds array when there are no matches and the subset of results when
there are partial matches. If false, the API returns a 404 status code when there are no matches or only
partial matches.
Comma-separated list of column names to display.
Supported values include:
ae (or assignment_explanation): For started datafeeds only, contains messages relating to the selection of
a node.bc (or buckets.count, bucketsCount): The number of buckets processed.id: A numerical character string that uniquely identifies the datafeed.na (or node.address, nodeAddress): For started datafeeds only, the network address of the node where the
datafeed is started.ne (or node.ephemeral_id, nodeEphemeralId): For started datafeeds only, the ephemeral ID of the node where the
datafeed is started.ni (or node.id, nodeId): For started datafeeds only, the unique identifier of the node where the
datafeed is started.nn (or node.name, nodeName): For started datafeeds only, the name of the node where the datafeed is
started.sba (or search.bucket_avg, searchBucketAvg): The average search time per bucket, in milliseconds.sc (or search.count, searchCount): The number of searches run by the datafeed.seah (or search.exp_avg_hour, searchExpAvgHour): The exponential average search time per hour, in milliseconds.st (or search.time, searchTime): The total time the datafeed spent searching, in milliseconds.s (or state): The status of the datafeed: starting, started, stopping, or stopped.
If starting, the datafeed has been requested to start but has not yet
started. If started, the datafeed is actively receiving data. If
stopping, the datafeed has been requested to stop gracefully and is
completing its final action. If stopped, the datafeed is stopped and will
not receive data until it is re-started.Comma-separated list of column names or column aliases used to sort the response.
Supported values include:
ae (or assignment_explanation): For started datafeeds only, contains messages relating to the selection of
a node.bc (or buckets.count, bucketsCount): The number of buckets processed.id: A numerical character string that uniquely identifies the datafeed.na (or node.address, nodeAddress): For started datafeeds only, the network address of the node where the
datafeed is started.ne (or node.ephemeral_id, nodeEphemeralId): For started datafeeds only, the ephemeral ID of the node where the
datafeed is started.ni (or node.id, nodeId): For started datafeeds only, the unique identifier of the node where the
datafeed is started.nn (or node.name, nodeName): For started datafeeds only, the name of the node where the datafeed is
started.sba (or search.bucket_avg, searchBucketAvg): The average search time per bucket, in milliseconds.sc (or search.count, searchCount): The number of searches run by the datafeed.seah (or search.exp_avg_hour, searchExpAvgHour): The exponential average search time per hour, in milliseconds.st (or search.time, searchTime): The total time the datafeed spent searching, in milliseconds.s (or state): The status of the datafeed: starting, started, stopping, or stopped.
If starting, the datafeed has been requested to start but has not yet
started. If started, the datafeed is actively receiving data. If
stopping, the datafeed has been requested to stop gracefully and is
completing its final action. If stopped, the datafeed is stopped and will
not receive data until it is re-started.The unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
curl \
--request GET 'http://api.example.com/_cat/ml/datafeeds' \
--header "Authorization: $API_KEY"[
{
"id": "datafeed-high_sum_total_sales",
"state": "stopped",
"buckets.count": "743",
"search.count": "7"
},
{
"id": "datafeed-low_request_rate",
"state": "stopped",
"buckets.count": "1457",
"search.count": "3"
},
{
"id": "datafeed-response_code_rates",
"state": "stopped",
"buckets.count": "1460",
"search.count": "18"
},
{
"id": "datafeed-url_scanning",
"state": "stopped",
"buckets.count": "1460",
"search.count": "18"
}
]Get configuration and usage information about datafeeds.
This API returns a maximum of 10,000 datafeeds.
If the Elasticsearch security features are enabled, you must have monitor_ml, monitor, manage_ml, or manage
cluster privileges to use this API.
IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get datafeed statistics API.
A numerical character string that uniquely identifies the datafeed.
Specifies what to do when the request:
_all string or no identifiers and there are no matches.If true, the API returns an empty datafeeds array when there are no matches and the subset of results when
there are partial matches. If false, the API returns a 404 status code when there are no matches or only
partial matches.
Comma-separated list of column names to display.
Supported values include:
ae (or assignment_explanation): For started datafeeds only, contains messages relating to the selection of
a node.bc (or buckets.count, bucketsCount): The number of buckets processed.id: A numerical character string that uniquely identifies the datafeed.na (or node.address, nodeAddress): For started datafeeds only, the network address of the node where the
datafeed is started.ne (or node.ephemeral_id, nodeEphemeralId): For started datafeeds only, the ephemeral ID of the node where the
datafeed is started.ni (or node.id, nodeId): For started datafeeds only, the unique identifier of the node where the
datafeed is started.nn (or node.name, nodeName): For started datafeeds only, the name of the node where the datafeed is
started.sba (or search.bucket_avg, searchBucketAvg): The average search time per bucket, in milliseconds.sc (or search.count, searchCount): The number of searches run by the datafeed.seah (or search.exp_avg_hour, searchExpAvgHour): The exponential average search time per hour, in milliseconds.st (or search.time, searchTime): The total time the datafeed spent searching, in milliseconds.s (or state): The status of the datafeed: starting, started, stopping, or stopped.
If starting, the datafeed has been requested to start but has not yet
started. If started, the datafeed is actively receiving data. If
stopping, the datafeed has been requested to stop gracefully and is
completing its final action. If stopped, the datafeed is stopped and will
not receive data until it is re-started.Comma-separated list of column names or column aliases used to sort the response.
Supported values include:
ae (or assignment_explanation): For started datafeeds only, contains messages relating to the selection of
a node.bc (or buckets.count, bucketsCount): The number of buckets processed.id: A numerical character string that uniquely identifies the datafeed.na (or node.address, nodeAddress): For started datafeeds only, the network address of the node where the
datafeed is started.ne (or node.ephemeral_id, nodeEphemeralId): For started datafeeds only, the ephemeral ID of the node where the
datafeed is started.ni (or node.id, nodeId): For started datafeeds only, the unique identifier of the node where the
datafeed is started.nn (or node.name, nodeName): For started datafeeds only, the name of the node where the datafeed is
started.sba (or search.bucket_avg, searchBucketAvg): The average search time per bucket, in milliseconds.sc (or search.count, searchCount): The number of searches run by the datafeed.seah (or search.exp_avg_hour, searchExpAvgHour): The exponential average search time per hour, in milliseconds.st (or search.time, searchTime): The total time the datafeed spent searching, in milliseconds.s (or state): The status of the datafeed: starting, started, stopping, or stopped.
If starting, the datafeed has been requested to start but has not yet
started. If started, the datafeed is actively receiving data. If
stopping, the datafeed has been requested to stop gracefully and is
completing its final action. If stopped, the datafeed is stopped and will
not receive data until it is re-started.The unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
curl \
--request GET 'http://api.example.com/_cat/ml/datafeeds/{datafeed_id}' \
--header "Authorization: $API_KEY"[
{
"id": "datafeed-high_sum_total_sales",
"state": "stopped",
"buckets.count": "743",
"search.count": "7"
},
{
"id": "datafeed-low_request_rate",
"state": "stopped",
"buckets.count": "1457",
"search.count": "3"
},
{
"id": "datafeed-response_code_rates",
"state": "stopped",
"buckets.count": "1460",
"search.count": "18"
},
{
"id": "datafeed-url_scanning",
"state": "stopped",
"buckets.count": "1460",
"search.count": "18"
}
]Get configuration and usage information for anomaly detection jobs.
This API returns a maximum of 10,000 jobs.
If the Elasticsearch security features are enabled, you must have monitor_ml,
monitor, manage_ml, or manage cluster privileges to use this API.
IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get anomaly detection job statistics API.
Specifies what to do when the request:
_all string or no identifiers and there are no matches.If true, the API returns an empty jobs array when there are no matches and the subset of results when there
are partial matches. If false, the API returns a 404 status code when there are no matches or only partial
matches.
The unit used to display byte values.
Values are b, kb, mb, gb, tb, or pb.
Comma-separated list of column names to display.
Supported values include:
assignment_explanation (or ae): For open anomaly detection jobs only, contains messages relating to the
selection of a node to run the job.buckets.count (or bc, bucketsCount): The number of bucket results produced by the job.buckets.time.exp_avg (or btea, bucketsTimeExpAvg): Exponential moving average of all bucket processing times, in milliseconds.buckets.time.exp_avg_hour (or bteah, bucketsTimeExpAvgHour): Exponentially-weighted moving average of bucket processing times calculated
in a 1 hour time window, in milliseconds.buckets.time.max (or btmax, bucketsTimeMax): Maximum among all bucket processing times, in milliseconds.buckets.time.min (or btmin, bucketsTimeMin): Minimum among all bucket processing times, in milliseconds.buckets.time.total (or btt, bucketsTimeTotal): Sum of all bucket processing times, in milliseconds.data.buckets (or db, dataBuckets): The number of buckets processed.data.earliest_record (or der, dataEarliestRecord): The timestamp of the earliest chronologically input document.data.empty_buckets (or deb, dataEmptyBuckets): The number of buckets which did not contain any data.data.input_bytes (or dib, dataInputBytes): The number of bytes of input data posted to the anomaly detection job.data.input_fields (or dif, dataInputFields): The total number of fields in input documents posted to the anomaly
detection job. This count includes fields that are not used in the analysis.
However, be aware that if you are using a datafeed, it extracts only the
required fields from the documents it retrieves before posting them to the job.data.input_records (or dir, dataInputRecords): The number of input documents posted to the anomaly detection job.data.invalid_dates (or did, dataInvalidDates): The number of input documents with either a missing date field or a date
that could not be parsed.data.last (or dl, dataLast): The timestamp at which data was last analyzed, according to server time.data.last_empty_bucket (or dleb, dataLastEmptyBucket): The timestamp of the last bucket that did not contain any data.data.last_sparse_bucket (or dlsb, dataLastSparseBucket): The timestamp of the last bucket that was considered sparse.data.latest_record (or dlr, dataLatestRecord): The timestamp of the latest chronologically input document.data.missing_fields (or dmf, dataMissingFields): The number of input documents that are missing a field that the anomaly
detection job is configured to analyze. Input documents with missing fields
are still processed because it is possible that not all fields are missing.data.out_of_order_timestamps (or doot, dataOutOfOrderTimestamps): The number of input documents that have a timestamp chronologically
preceding the start of the current anomaly detection bucket offset by the
latency window. This information is applicable only when you provide data
to the anomaly detection job by using the post data API. These out of order
documents are discarded, since jobs require time series data to be in
ascending chronological order.data.processed_fields (or dpf, dataProcessedFields): The total number of fields in all the documents that have been processed by
the anomaly detection job. Only fields that are specified in the detector
configuration object contribute to this count. The timestamp is not
included in this count.data.processed_records (or dpr, dataProcessedRecords): The number of input documents that have been processed by the anomaly
detection job. This value includes documents with missing fields, since
they are nonetheless analyzed. If you use datafeeds and have aggregations
in your search query, the processed record count is the number of
aggregation results processed, not the number of Elasticsearch documents.data.sparse_buckets (or dsb, dataSparseBuckets): The number of buckets that contained few data points compared to the
expected number of data points.forecasts.memory.avg (or fmavg, forecastsMemoryAvg): The average memory usage in bytes for forecasts related to the anomaly
detection job.forecasts.memory.max (or fmmax, forecastsMemoryMax): The maximum memory usage in bytes for forecasts related to the anomaly
detection job.forecasts.memory.min (or fmmin, forecastsMemoryMin): The minimum memory usage in bytes for forecasts related to the anomaly
detection job.forecasts.memory.total (or fmt, forecastsMemoryTotal): The total memory usage in bytes for forecasts related to the anomaly
detection job.forecasts.records.avg (or fravg, forecastsRecordsAvg): The average number of model_forecast` documents written for forecasts
related to the anomaly detection job.forecasts.records.max (or frmax, forecastsRecordsMax): The maximum number of model_forecast documents written for forecasts
related to the anomaly detection job.forecasts.records.min (or frmin, forecastsRecordsMin): The minimum number of model_forecast documents written for forecasts
related to the anomaly detection job.forecasts.records.total (or frt, forecastsRecordsTotal): The total number of model_forecast documents written for forecasts
related to the anomaly detection job.forecasts.time.avg (or ftavg, forecastsTimeAvg): The average runtime in milliseconds for forecasts related to the anomaly
detection job.forecasts.time.max (or ftmax, forecastsTimeMax): The maximum runtime in milliseconds for forecasts related to the anomaly
detection job.forecasts.time.min (or ftmin, forecastsTimeMin): The minimum runtime in milliseconds for forecasts related to the anomaly
detection job.forecasts.time.total (or ftt, forecastsTimeTotal): The total runtime in milliseconds for forecasts related to the anomaly
detection job.forecasts.total (or ft, forecastsTotal): The number of individual forecasts currently available for the job.id: Identifier for the anomaly detection job.model.bucket_allocation_failures (or mbaf, modelBucketAllocationFailures): The number of buckets for which new entities in incoming data were not
processed due to insufficient model memory.model.by_fields (or mbf, modelByFields): The number of by field values that were analyzed by the models. This value
is cumulative for all detectors in the job.model.bytes (or mb, modelBytes): The number of bytes of memory used by the models. This is the maximum value
since the last time the model was persisted. If the job is closed, this
value indicates the latest size.model.bytes_exceeded (or mbe, modelBytesExceeded): The number of bytes over the high limit for memory usage at the last
allocation failure.model.categorization_status (or mcs, modelCategorizationStatus): The status of categorization for the job: ok or warn. If ok,
categorization is performing acceptably well (or not being used at all). If
warn, categorization is detecting a distribution of categories that
suggests the input data is inappropriate for categorization. Problems could
be that there is only one category, more than 90% of categories are rare,
the number of categories is greater than 50% of the number of categorized
documents, there are no frequently matched categories, or more than 50% of
categories are dead.model.categorized_doc_count (or mcdc, modelCategorizedDocCount): The number of documents that have had a field categorized.model.dead_category_count (or mdcc, modelDeadCategoryCount): The number of categories created by categorization that will never be
assigned again because another category’s definition makes it a superset of
the dead category. Dead categories are a side effect of the way
categorization has no prior training.model.failed_category_count (or mdcc, modelFailedCategoryCount): The number of times that categorization wanted to create a new category but
couldn’t because the job had hit its model memory limit. This count does
not track which specific categories failed to be created. Therefore, you
cannot use this value to determine the number of unique categories that
were missed.model.frequent_category_count (or mfcc, modelFrequentCategoryCount): The number of categories that match more than 1% of categorized documents.model.log_time (or mlt, modelLogTime): The timestamp when the model stats were gathered, according to server time.model.memory_limit (or mml, modelMemoryLimit): The timestamp when the model stats were gathered, according to server time.model.memory_status (or mms, modelMemoryStatus): The status of the mathematical models: ok, soft_limit, or hard_limit.
If ok, the models stayed below the configured value. If soft_limit, the
models used more than 60% of the configured memory limit and older unused
models will be pruned to free up space. Additionally, in categorization jobs
no further category examples will be stored. If hard_limit, the models
used more space than the configured memory limit. As a result, not all
incoming data was processed.model.over_fields (or mof, modelOverFields): The number of over field values that were analyzed by the models. This
value is cumulative for all detectors in the job.model.partition_fields (or mpf, modelPartitionFields): The number of partition field values that were analyzed by the models. This
value is cumulative for all detectors in the job.model.rare_category_count (or mrcc, modelRareCategoryCount): The number of categories that match just one categorized document.model.timestamp (or mt, modelTimestamp): The timestamp of the last record when the model stats were gathered.model.total_category_count (or mtcc, modelTotalCategoryCount): The number of categories created by categorization.node.address (or na, nodeAddress): The network address of the node that runs the job. This information is
available only for open jobs.node.ephemeral_id (or ne, nodeEphemeralId): The ephemeral ID of the node that runs the job. This information is
available only for open jobs.node.id (or ni, nodeId): The unique identifier of the node that runs the job. This information is
available only for open jobs.node.name (or nn, nodeName): The name of the node that runs the job. This information is available only
for open jobs.opened_time (or ot): For open jobs only, the elapsed time for which the job has been open.state (or s): The status of the anomaly detection job: closed, closing, failed,
opened, or opening. If closed, the job finished successfully with its
model state persisted. The job must be opened before it can accept further
data. If closing, the job close action is in progress and has not yet
completed. A closing job cannot accept further data. If failed, the job
did not finish successfully due to an error. This situation can occur due
to invalid input data, a fatal error occurring during the analysis, or an
external interaction such as the process being killed by the Linux out of
memory (OOM) killer. If the job had irrevocably failed, it must be force
closed and then deleted. If the datafeed can be corrected, the job can be
closed and then re-opened. If opened, the job is available to receive and
process data. If opening, the job open action is in progress and has not
yet completed.Comma-separated list of column names or column aliases used to sort the response.
Supported values include:
assignment_explanation (or ae): For open anomaly detection jobs only, contains messages relating to the
selection of a node to run the job.buckets.count (or bc, bucketsCount): The number of bucket results produced by the job.buckets.time.exp_avg (or btea, bucketsTimeExpAvg): Exponential moving average of all bucket processing times, in milliseconds.buckets.time.exp_avg_hour (or bteah, bucketsTimeExpAvgHour): Exponentially-weighted moving average of bucket processing times calculated
in a 1 hour time window, in milliseconds.buckets.time.max (or btmax, bucketsTimeMax): Maximum among all bucket processing times, in milliseconds.buckets.time.min (or btmin, bucketsTimeMin): Minimum among all bucket processing times, in milliseconds.buckets.time.total (or btt, bucketsTimeTotal): Sum of all bucket processing times, in milliseconds.data.buckets (or db, dataBuckets): The number of buckets processed.data.earliest_record (or der, dataEarliestRecord): The timestamp of the earliest chronologically input document.data.empty_buckets (or deb, dataEmptyBuckets): The number of buckets which did not contain any data.data.input_bytes (or dib, dataInputBytes): The number of bytes of input data posted to the anomaly detection job.data.input_fields (or dif, dataInputFields): The total number of fields in input documents posted to the anomaly
detection job. This count includes fields that are not used in the analysis.
However, be aware that if you are using a datafeed, it extracts only the
required fields from the documents it retrieves before posting them to the job.data.input_records (or dir, dataInputRecords): The number of input documents posted to the anomaly detection job.data.invalid_dates (or did, dataInvalidDates): The number of input documents with either a missing date field or a date
that could not be parsed.data.last (or dl, dataLast): The timestamp at which data was last analyzed, according to server time.data.last_empty_bucket (or dleb, dataLastEmptyBucket): The timestamp of the last bucket that did not contain any data.data.last_sparse_bucket (or dlsb, dataLastSparseBucket): The timestamp of the last bucket that was considered sparse.data.latest_record (or dlr, dataLatestRecord): The timestamp of the latest chronologically input document.data.missing_fields (or dmf, dataMissingFields): The number of input documents that are missing a field that the anomaly
detection job is configured to analyze. Input documents with missing fields
are still processed because it is possible that not all fields are missing.data.out_of_order_timestamps (or doot, dataOutOfOrderTimestamps): The number of input documents that have a timestamp chronologically
preceding the start of the current anomaly detection bucket offset by the
latency window. This information is applicable only when you provide data
to the anomaly detection job by using the post data API. These out of order
documents are discarded, since jobs require time series data to be in
ascending chronological order.data.processed_fields (or dpf, dataProcessedFields): The total number of fields in all the documents that have been processed by
the anomaly detection job. Only fields that are specified in the detector
configuration object contribute to this count. The timestamp is not
included in this count.data.processed_records (or dpr, dataProcessedRecords): The number of input documents that have been processed by the anomaly
detection job. This value includes documents with missing fields, since
they are nonetheless analyzed. If you use datafeeds and have aggregations
in your search query, the processed record count is the number of
aggregation results processed, not the number of Elasticsearch documents.data.sparse_buckets (or dsb, dataSparseBuckets): The number of buckets that contained few data points compared to the
expected number of data points.forecasts.memory.avg (or fmavg, forecastsMemoryAvg): The average memory usage in bytes for forecasts related to the anomaly
detection job.forecasts.memory.max (or fmmax, forecastsMemoryMax): The maximum memory usage in bytes for forecasts related to the anomaly
detection job.forecasts.memory.min (or fmmin, forecastsMemoryMin): The minimum memory usage in bytes for forecasts related to the anomaly
detection job.forecasts.memory.total (or fmt, forecastsMemoryTotal): The total memory usage in bytes for forecasts related to the anomaly
detection job.forecasts.records.avg (or fravg, forecastsRecordsAvg): The average number of model_forecast` documents written for forecasts
related to the anomaly detection job.forecasts.records.max (or frmax, forecastsRecordsMax): The maximum number of model_forecast documents written for forecasts
related to the anomaly detection job.forecasts.records.min (or frmin, forecastsRecordsMin): The minimum number of model_forecast documents written for forecasts
related to the anomaly detection job.forecasts.records.total (or frt, forecastsRecordsTotal): The total number of model_forecast documents written for forecasts
related to the anomaly detection job.forecasts.time.avg (or ftavg, forecastsTimeAvg): The average runtime in milliseconds for forecasts related to the anomaly
detection job.forecasts.time.max (or ftmax, forecastsTimeMax): The maximum runtime in milliseconds for forecasts related to the anomaly
detection job.forecasts.time.min (or ftmin, forecastsTimeMin): The minimum runtime in milliseconds for forecasts related to the anomaly
detection job.forecasts.time.total (or ftt, forecastsTimeTotal): The total runtime in milliseconds for forecasts related to the anomaly
detection job.forecasts.total (or ft, forecastsTotal): The number of individual forecasts currently available for the job.id: Identifier for the anomaly detection job.model.bucket_allocation_failures (or mbaf, modelBucketAllocationFailures): The number of buckets for which new entities in incoming data were not
processed due to insufficient model memory.model.by_fields (or mbf, modelByFields): The number of by field values that were analyzed by the models. This value
is cumulative for all detectors in the job.model.bytes (or mb, modelBytes): The number of bytes of memory used by the models. This is the maximum value
since the last time the model was persisted. If the job is closed, this
value indicates the latest size.model.bytes_exceeded (or mbe, modelBytesExceeded): The number of bytes over the high limit for memory usage at the last
allocation failure.model.categorization_status (or mcs, modelCategorizationStatus): The status of categorization for the job: ok or warn. If ok,
categorization is performing acceptably well (or not being used at all). If
warn, categorization is detecting a distribution of categories that
suggests the input data is inappropriate for categorization. Problems could
be that there is only one category, more than 90% of categories are rare,
the number of categories is greater than 50% of the number of categorized
documents, there are no frequently matched categories, or more than 50% of
categories are dead.model.categorized_doc_count (or mcdc, modelCategorizedDocCount): The number of documents that have had a field categorized.model.dead_category_count (or mdcc, modelDeadCategoryCount): The number of categories created by categorization that will never be
assigned again because another category’s definition makes it a superset of
the dead category. Dead categories are a side effect of the way
categorization has no prior training.model.failed_category_count (or mdcc, modelFailedCategoryCount): The number of times that categorization wanted to create a new category but
couldn’t because the job had hit its model memory limit. This count does
not track which specific categories failed to be created. Therefore, you
cannot use this value to determine the number of unique categories that
were missed.model.frequent_category_count (or mfcc, modelFrequentCategoryCount): The number of categories that match more than 1% of categorized documents.model.log_time (or mlt, modelLogTime): The timestamp when the model stats were gathered, according to server time.model.memory_limit (or mml, modelMemoryLimit): The timestamp when the model stats were gathered, according to server time.model.memory_status (or mms, modelMemoryStatus): The status of the mathematical models: ok, soft_limit, or hard_limit.
If ok, the models stayed below the configured value. If soft_limit, the
models used more than 60% of the configured memory limit and older unused
models will be pruned to free up space. Additionally, in categorization jobs
no further category examples will be stored. If hard_limit, the models
used more space than the configured memory limit. As a result, not all
incoming data was processed.model.over_fields (or mof, modelOverFields): The number of over field values that were analyzed by the models. This
value is cumulative for all detectors in the job.model.partition_fields (or mpf, modelPartitionFields): The number of partition field values that were analyzed by the models. This
value is cumulative for all detectors in the job.model.rare_category_count (or mrcc, modelRareCategoryCount): The number of categories that match just one categorized document.model.timestamp (or mt, modelTimestamp): The timestamp of the last record when the model stats were gathered.model.total_category_count (or mtcc, modelTotalCategoryCount): The number of categories created by categorization.node.address (or na, nodeAddress): The network address of the node that runs the job. This information is
available only for open jobs.node.ephemeral_id (or ne, nodeEphemeralId): The ephemeral ID of the node that runs the job. This information is
available only for open jobs.node.id (or ni, nodeId): The unique identifier of the node that runs the job. This information is
available only for open jobs.node.name (or nn, nodeName): The name of the node that runs the job. This information is available only
for open jobs.opened_time (or ot): For open jobs only, the elapsed time for which the job has been open.state (or s): The status of the anomaly detection job: closed, closing, failed,
opened, or opening. If closed, the job finished successfully with its
model state persisted. The job must be opened before it can accept further
data. If closing, the job close action is in progress and has not yet
completed. A closing job cannot accept further data. If failed, the job
did not finish successfully due to an error. This situation can occur due
to invalid input data, a fatal error occurring during the analysis, or an
external interaction such as the process being killed by the Linux out of
memory (OOM) killer. If the job had irrevocably failed, it must be force
closed and then deleted. If the datafeed can be corrected, the job can be
closed and then re-opened. If opened, the job is available to receive and
process data. If opening, the job open action is in progress and has not
yet completed.The unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
curl \
--request GET 'http://api.example.com/_cat/ml/anomaly_detectors' \
--header "Authorization: $API_KEY"[
{
"id": "high_sum_total_sales",
"s": "closed",
"dpr": "14022",
"mb": "1.5mb"
},
{
"id": "low_request_rate",
"s": "closed",
"dpr": "1216",
"mb": "40.5kb"
},
{
"id": "response_code_rates",
"s": "closed",
"dpr": "28146",
"mb": "132.7kb"
},
{
"id": "url_scanning",
"s": "closed",
"dpr": "28146",
"mb": "501.6kb"
}
]Get configuration and usage information about inference trained models.
IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get trained models statistics API.
Specifies what to do when the request: contains wildcard expressions and there are no models that match; contains the _all string or no identifiers and there are no matches; contains wildcard expressions and there are only partial matches.
If true, the API returns an empty array when there are no matches and the subset of results when there are partial matches.
If false, the API returns a 404 status code when there are no matches or only partial matches.
The unit used to display byte values.
Values are b, kb, mb, gb, tb, or pb.
A comma-separated list of column names to display.
Supported values include:
create_time (or ct): The time when the trained model was created.created_by (or c, createdBy): Information on the creator of the trained model.data_frame_analytics_id (or df, dataFrameAnalytics, dfid): Identifier for the data frame analytics job that created the model. Only
displayed if it is still available.description (or d): The description of the trained model.heap_size (or hs, modelHeapSize): The estimated heap size to keep the trained model in memory.id: Identifier for the trained model.ingest.count (or ic, ingestCount): The total number of documents that are processed by the model.ingest.current (or icurr, ingestCurrent): The total number of document that are currently being handled by the
trained model.ingest.failed (or if, ingestFailed): The total number of failed ingest attempts with the trained model.ingest.pipelines (or ip, ingestPipelines): The total number of ingest pipelines that are referencing the trained
model.ingest.time (or it, ingestTime): The total time that is spent processing documents with the trained model.license (or l): The license level of the trained model.operations (or o, modelOperations): The estimated number of operations to use the trained model. This number
helps measuring the computational complexity of the model.version (or v): The Elasticsearch version number in which the trained model was created.A comma-separated list of column names or aliases used to sort the response.
Supported values include:
create_time (or ct): The time when the trained model was created.created_by (or c, createdBy): Information on the creator of the trained model.data_frame_analytics_id (or df, dataFrameAnalytics, dfid): Identifier for the data frame analytics job that created the model. Only
displayed if it is still available.description (or d): The description of the trained model.heap_size (or hs, modelHeapSize): The estimated heap size to keep the trained model in memory.id: Identifier for the trained model.ingest.count (or ic, ingestCount): The total number of documents that are processed by the model.ingest.current (or icurr, ingestCurrent): The total number of document that are currently being handled by the
trained model.ingest.failed (or if, ingestFailed): The total number of failed ingest attempts with the trained model.ingest.pipelines (or ip, ingestPipelines): The total number of ingest pipelines that are referencing the trained
model.ingest.time (or it, ingestTime): The total time that is spent processing documents with the trained model.license (or l): The license level of the trained model.operations (or o, modelOperations): The estimated number of operations to use the trained model. This number
helps measuring the computational complexity of the model.version (or v): The Elasticsearch version number in which the trained model was created.Skips the specified number of transforms.
The maximum number of transforms to display.
Unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
curl \
--request GET 'http://api.example.com/_cat/ml/trained_models' \
--header "Authorization: $API_KEY"[
{
"id": "ddddd-1580216177138",
"heap_size": "0b",
"operations": "196",
"create_time": "2025-03-25T00:01:38.662Z",
"type": "pytorch",
"ingest.pipelines": "0",
"data_frame.id": "__none__"
},
{
"id": "lang_ident_model_1",
"heap_size": "1mb",
"operations": "39629",
"create_time": "2019-12-05T12:28:34.594Z",
"type": "lang_ident",
"ingest.pipelines": "0",
"data_frame.id": "__none__"
}
]Get configuration and usage information about inference trained models.
IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get trained models statistics API.
A unique identifier for the trained model.
Specifies what to do when the request: contains wildcard expressions and there are no models that match; contains the _all string or no identifiers and there are no matches; contains wildcard expressions and there are only partial matches.
If true, the API returns an empty array when there are no matches and the subset of results when there are partial matches.
If false, the API returns a 404 status code when there are no matches or only partial matches.
The unit used to display byte values.
Values are b, kb, mb, gb, tb, or pb.
A comma-separated list of column names to display.
Supported values include:
create_time (or ct): The time when the trained model was created.created_by (or c, createdBy): Information on the creator of the trained model.data_frame_analytics_id (or df, dataFrameAnalytics, dfid): Identifier for the data frame analytics job that created the model. Only
displayed if it is still available.description (or d): The description of the trained model.heap_size (or hs, modelHeapSize): The estimated heap size to keep the trained model in memory.id: Identifier for the trained model.ingest.count (or ic, ingestCount): The total number of documents that are processed by the model.ingest.current (or icurr, ingestCurrent): The total number of document that are currently being handled by the
trained model.ingest.failed (or if, ingestFailed): The total number of failed ingest attempts with the trained model.ingest.pipelines (or ip, ingestPipelines): The total number of ingest pipelines that are referencing the trained
model.ingest.time (or it, ingestTime): The total time that is spent processing documents with the trained model.license (or l): The license level of the trained model.operations (or o, modelOperations): The estimated number of operations to use the trained model. This number
helps measuring the computational complexity of the model.version (or v): The Elasticsearch version number in which the trained model was created.A comma-separated list of column names or aliases used to sort the response.
Supported values include:
create_time (or ct): The time when the trained model was created.created_by (or c, createdBy): Information on the creator of the trained model.data_frame_analytics_id (or df, dataFrameAnalytics, dfid): Identifier for the data frame analytics job that created the model. Only
displayed if it is still available.description (or d): The description of the trained model.heap_size (or hs, modelHeapSize): The estimated heap size to keep the trained model in memory.id: Identifier for the trained model.ingest.count (or ic, ingestCount): The total number of documents that are processed by the model.ingest.current (or icurr, ingestCurrent): The total number of document that are currently being handled by the
trained model.ingest.failed (or if, ingestFailed): The total number of failed ingest attempts with the trained model.ingest.pipelines (or ip, ingestPipelines): The total number of ingest pipelines that are referencing the trained
model.ingest.time (or it, ingestTime): The total time that is spent processing documents with the trained model.license (or l): The license level of the trained model.operations (or o, modelOperations): The estimated number of operations to use the trained model. This number
helps measuring the computational complexity of the model.version (or v): The Elasticsearch version number in which the trained model was created.Skips the specified number of transforms.
The maximum number of transforms to display.
Unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
curl \
--request GET 'http://api.example.com/_cat/ml/trained_models/{model_id}' \
--header "Authorization: $API_KEY"[
{
"id": "ddddd-1580216177138",
"heap_size": "0b",
"operations": "196",
"create_time": "2025-03-25T00:01:38.662Z",
"type": "pytorch",
"ingest.pipelines": "0",
"data_frame.id": "__none__"
},
{
"id": "lang_ident_model_1",
"heap_size": "1mb",
"operations": "39629",
"create_time": "2019-12-05T12:28:34.594Z",
"type": "lang_ident",
"ingest.pipelines": "0",
"data_frame.id": "__none__"
}
]Get a list of plugins running on each node of a 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 info API.
List of columns to appear in the response. Supports simple wildcards.
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.
Include bootstrap plugins in the response
If true, the request computes the list of selected nodes from the
local cluster state. If false 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.
Period to wait for a connection to the master node.
curl \
--request GET 'http://api.example.com/_cat/plugins' \
--header "Authorization: $API_KEY"[
{ "name": "U7321H6", "component": "analysis-icu", "version": "8.17.0", "description": "The ICU Analysis plugin integrates the Lucene ICU module into Elasticsearch, adding ICU-related analysis components."},
{"name": "U7321H6", "component": "analysis-kuromoji", "verison": "8.17.0", description: "The Japanese (kuromoji) Analysis plugin integrates Lucene kuromoji analysis module into elasticsearch."},
{"name" "U7321H6", "component": "analysis-nori", "version": "8.17.0", "description": "The Korean (nori) Analysis plugin integrates Lucene nori analysis module into elasticsearch."},
{"name": "U7321H6", "component": "analysis-phonetic", "verison": "8.17.0", "description": "The Phonetic Analysis plugin integrates phonetic token filter analysis with elasticsearch."},
{"name": "U7321H6", "component": "analysis-smartcn", "verison": "8.17.0", "description": "Smart Chinese Analysis plugin integrates Lucene Smart Chinese analysis module into elasticsearch."},
{"name": "U7321H6", "component": "analysis-stempel", "verison": "8.17.0", "description": "The Stempel (Polish) Analysis plugin integrates Lucene stempel (polish) analysis module into elasticsearch."},
{"name": "U7321H6", "component": "analysis-ukrainian", "verison": "8.17.0", "description": "The Ukrainian Analysis plugin integrates the Lucene UkrainianMorfologikAnalyzer into elasticsearch."},
{"name": "U7321H6", "component": "discovery-azure-classic", "verison": "8.17.0", "description": "The Azure Classic Discovery plugin allows to use Azure Classic API for the unicast discovery mechanism"},
{"name": "U7321H6", "component": "discovery-ec2", "verison": "8.17.0", "description": "The EC2 discovery plugin allows to use AWS API for the unicast discovery mechanism."},
{"name": "U7321H6", "component": "discovery-gce", "verison": "8.17.0", "description": "The Google Compute Engine (GCE) Discovery plugin allows to use GCE API for the unicast discovery mechanism."},
{"name": "U7321H6", "component": "mapper-annotated-text", "verison": "8.17.0", "description": "The Mapper Annotated_text plugin adds support for text fields with markup used to inject annotation tokens into the index."},
{"name": "U7321H6", "component": "mapper-murmur3", "verison": "8.17.0", "description": "The Mapper Murmur3 plugin allows to compute hashes of a field's values at index-time and to store them in the index."},
{"name": "U7321H6", "component": "mapper-size", "verison": "8.17.0", "description": "The Mapper Size plugin allows document to record their uncompressed size at index time."},
{"name": "U7321H6", "component": "store-smb", "verison": "8.17.0", "description": "The Store SMB plugin adds support for SMB stores."}
]Get information about ongoing and completed shard recoveries. Shard recovery is the process of initializing a shard copy, such as restoring a primary shard from a snapshot or syncing a replica shard from a primary shard. When a shard recovery completes, the recovered shard is available for search and indexing. For data streams, the API returns information about the stream’s 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. For application consumption, use the index recovery API.
If true, the response only includes ongoing shard recoveries.
The unit used to display byte values.
Values are b, kb, mb, gb, tb, or pb.
If true, the response includes detailed information about shard recoveries.
Comma-separated list or wildcard expression of index names to limit the returned information
List of columns to appear in the response. Supports simple wildcards.
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.
Unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
curl \
--request GET 'http://api.example.com/_cat/recovery' \
--header "Authorization: $API_KEY"[
{
"index": "my-index-000001 ",
"shard": "0",
"time": "13ms",
"type": "store",
"stage": "done",
"source_host": "n/a",
"source_node": "n/a",
"target_host": "127.0.0.1",
"target_node": "node-0",
"repository": "n/a",
"snapshot": "n/a",
"files": "0",
"files_recovered": "0",
"files_percent": "100.0%",
"files_total": "13",
"bytes": "0b",
"bytes_recovered": "0b",
"bytes_percent": "100.0%",
"bytes_total": "9928b",
"translog_ops": "0",
"translog_ops_recovered": "0",
"translog_ops_percent": "100.0%"
}
][
{
"i": "my-index-000001",
"s": "0",
"t": "1252ms",
"ty": "peer",
"st": "done",
"shost": "192.168.1.1",
"thost": "192.168.1.1",
"f": "0",
"fp": "100.0%",
"b": "0b",
"bp": "100.0%",
}
][
{
"i": "my-index-000001",
"s": "0",
"t": "1978ms",
"ty": "snapshot",
"st": "done",
"rep": "my-repo",
"snap": "snap-1",
"f": "79",
"fp": "8.0%",
"b": "12086",
"bp": "9.0%"
}
]Get information about ongoing and completed shard recoveries. Shard recovery is the process of initializing a shard copy, such as restoring a primary shard from a snapshot or syncing a replica shard from a primary shard. When a shard recovery completes, the recovered shard is available for search and indexing. For data streams, the API returns information about the stream’s 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. For application consumption, use the index recovery API.
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.
If true, the response only includes ongoing shard recoveries.
The unit used to display byte values.
Values are b, kb, mb, gb, tb, or pb.
If true, the response includes detailed information about shard recoveries.
Comma-separated list or wildcard expression of index names to limit the returned information
List of columns to appear in the response. Supports simple wildcards.
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.
Unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
curl \
--request GET 'http://api.example.com/_cat/recovery/{index}' \
--header "Authorization: $API_KEY"[
{
"index": "my-index-000001 ",
"shard": "0",
"time": "13ms",
"type": "store",
"stage": "done",
"source_host": "n/a",
"source_node": "n/a",
"target_host": "127.0.0.1",
"target_node": "node-0",
"repository": "n/a",
"snapshot": "n/a",
"files": "0",
"files_recovered": "0",
"files_percent": "100.0%",
"files_total": "13",
"bytes": "0b",
"bytes_recovered": "0b",
"bytes_percent": "100.0%",
"bytes_total": "9928b",
"translog_ops": "0",
"translog_ops_recovered": "0",
"translog_ops_percent": "100.0%"
}
][
{
"i": "my-index-000001",
"s": "0",
"t": "1252ms",
"ty": "peer",
"st": "done",
"shost": "192.168.1.1",
"thost": "192.168.1.1",
"f": "0",
"fp": "100.0%",
"b": "0b",
"bp": "100.0%",
}
][
{
"i": "my-index-000001",
"s": "0",
"t": "1978ms",
"ty": "snapshot",
"st": "done",
"rep": "my-repo",
"snap": "snap-1",
"f": "79",
"fp": "8.0%",
"b": "12086",
"bp": "9.0%"
}
]Get a list of snapshot repositories for a 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 repository API.
List of columns to appear in the response. Supports simple wildcards.
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.
If true, the request computes the list of selected nodes from the
local cluster state. If false 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.
Period to wait for a connection to the master node.
curl \
--request GET 'http://api.example.com/_cat/repositories' \
--header "Authorization: $API_KEY"[
{
"id": "repo1",
"type": "fs"
},
{
"id": "repo2",
"type": "s3"
}
]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.
The unit used to display byte values.
Values are b, kb, mb, gb, tb, or pb.
List of columns to appear in the response. Supports simple wildcards.
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.
Period to wait for a connection to the master node.
Unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
curl \
--request GET 'http://api.example.com/_cat/shards' \
--header "Authorization: $API_KEY"[
{
"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 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.
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.
The unit used to display byte values.
Values are b, kb, mb, gb, tb, or pb.
List of columns to appear in the response. Supports simple wildcards.
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.
Period to wait for a connection to the master node.
Unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
curl \
--request GET 'http://api.example.com/_cat/shards/{index}' \
--header "Authorization: $API_KEY"[
{
"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 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.
List of columns to appear in the response. Supports simple wildcards.
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.
Period to wait for a connection to the master node.
Unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
curl \
--request GET 'http://api.example.com/_cat/snapshots' \
--header "Authorization: $API_KEY"[
{
"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 thread pool statistics for each node in a cluster. Returned information includes all built-in thread pools and custom thread pools. 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 info API.
List of columns to appear in the response. Supports simple wildcards.
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.
The unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
If true, the request computes the list of selected nodes from the
local cluster state. If false 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.
Period to wait for a connection to the master node.
curl \
--request GET 'http://api.example.com/_cat/thread_pool' \
--header "Authorization: $API_KEY"[
{
"node_name": "node-0",
"name": "analyze",
"active": "0",
"queue": "0",
"rejected": "0"
},
{
"node_name": "node-0",
"name": "fetch_shard_started",
"active": "0",
"queue": "0",
"rejected": "0"
},
{
"node_name": "node-0",
"name": "fetch_shard_store",
"active": "0",
"queue": "0",
"rejected": "0"
},
{
"node_name": "node-0",
"name": "flush",
"active": "0",
"queue": "0",
"rejected": "0"
},
{
"node_name": "node-0",
"name": "write",
"active": "0",
"queue": "0",
"rejected": "0"
}
][
{
"id": "0EWUhXeBQtaVGlexUeVwMg",
"name": "generic",
"active": "0",
"rejected": "0",
"completed": "70"
}
]Get thread pool statistics for each node in a cluster. Returned information includes all built-in thread pools and custom thread pools. 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 info API.
A comma-separated list of thread pool names used to limit the request. Accepts wildcard expressions.
List of columns to appear in the response. Supports simple wildcards.
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.
The unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
If true, the request computes the list of selected nodes from the
local cluster state. If false 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.
Period to wait for a connection to the master node.
curl \
--request GET 'http://api.example.com/_cat/thread_pool/{thread_pool_patterns}' \
--header "Authorization: $API_KEY"[
{
"node_name": "node-0",
"name": "analyze",
"active": "0",
"queue": "0",
"rejected": "0"
},
{
"node_name": "node-0",
"name": "fetch_shard_started",
"active": "0",
"queue": "0",
"rejected": "0"
},
{
"node_name": "node-0",
"name": "fetch_shard_store",
"active": "0",
"queue": "0",
"rejected": "0"
},
{
"node_name": "node-0",
"name": "flush",
"active": "0",
"queue": "0",
"rejected": "0"
},
{
"node_name": "node-0",
"name": "write",
"active": "0",
"queue": "0",
"rejected": "0"
}
][
{
"id": "0EWUhXeBQtaVGlexUeVwMg",
"name": "generic",
"active": "0",
"rejected": "0",
"completed": "70"
}
]Get configuration and usage information about transforms.
CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get transform statistics API.
A transform identifier or a wildcard expression. If you do not specify one of these options, the API returns information for all transforms.
Specifies what to do when the request: contains wildcard expressions and there are no transforms that match; contains the _all string or no identifiers and there are no matches; contains wildcard expressions and there are only partial matches.
If true, it returns an empty transforms array when there are no matches and the subset of results when there are partial matches.
If false, the request returns a 404 status code when there are no matches or only partial matches.
Skips the specified number of transforms.
Comma-separated list of column names to display.
Supported values include:
changes_last_detection_time (or cldt): The timestamp when changes were last detected in the source indices.checkpoint (or cp): The sequence number for the checkpoint.checkpoint_duration_time_exp_avg (or cdtea, checkpointTimeExpAvg): Exponential moving average of the duration of the checkpoint, in
milliseconds.checkpoint_progress (or c, checkpointProgress): The progress of the next checkpoint that is currently in progress.create_time (or ct, createTime): The time the transform was created.delete_time (or dtime): The amount of time spent deleting, in milliseconds.description (or d): The description of the transform.dest_index (or di, destIndex): The destination index for the transform. The mappings of the destination
index are deduced based on the source fields when possible. If alternate
mappings are required, use the Create index API prior to starting the
transform.documents_deleted (or docd): The number of documents that have been deleted from the destination index
due to the retention policy for this transform.documents_indexed (or doci): The number of documents that have been indexed into the destination index
for the transform.docs_per_second (or dps): Specifies a limit on the number of input documents per second. This setting
throttles the transform by adding a wait time between search requests. The
default value is null, which disables throttling.documents_processed (or docp): The number of documents that have been processed from the source index of
the transform.frequency (or f): The interval between checks for changes in the source indices when the
transform is running continuously. Also determines the retry interval in
the event of transient failures while the transform is searching or
indexing. The minimum value is 1s and the maximum is 1h. The default
value is 1m.id: Identifier for the transform.index_failure (or if): The number of indexing failures.index_time (or itime): The amount of time spent indexing, in milliseconds.index_total (or it): The number of index operations.indexed_documents_exp_avg (or idea): Exponential moving average of the number of new documents that have been
indexed.last_search_time (or lst, lastSearchTime): The timestamp of the last search in the source indices. This field is only
shown if the transform is running.max_page_search_size (or mpsz): Defines the initial page size to use for the composite aggregation for each
checkpoint. If circuit breaker exceptions occur, the page size is
dynamically adjusted to a lower value. The minimum value is 10 and the
maximum is 65,536. The default value is 500.pages_processed (or pp): The number of search or bulk index operations processed. Documents are
processed in batches instead of individually.pipeline (or p): The unique identifier for an ingest pipeline.processed_documents_exp_avg (or pdea): Exponential moving average of the number of documents that have been
processed.processing_time (or pt): The amount of time spent processing results, in milliseconds.reason (or r): If a transform has a failed state, this property provides details about
the reason for the failure.search_failure (or sf): The number of search failures.search_time (or stime): The amount of time spent searching, in milliseconds.search_total (or st): The number of search operations on the source index for the transform.source_index (or si, sourceIndex): The source indices for the transform. It can be a single index, an index
pattern (for example, "my-index-*"), an array of indices (for example,
["my-index-000001", "my-index-000002"]), or an array of index patterns
(for example, ["my-index-*", "my-other-index-*"]. For remote indices use
the syntax "remote_name:index_name". If any indices are in remote
clusters then the master node and at least one transform node must have the
remote_cluster_client node role.state (or s): The status of the transform, which can be one of the following values:
aborting: The transform is aborting.failed: The transform failed. For more information about the failure,
check the reason field.indexing: The transform is actively processing data and creating new
documents.started: The transform is running but not actively indexing data.stopped: The transform is stopped.stopping: The transform is stopping.transform_type (or tt): Indicates the type of transform: batch or continuous.
trigger_count (or tc): The number of times the transform has been triggered by the scheduler. For
example, the scheduler triggers the transform indexer to check for updates
or ingest new data at an interval specified in the frequency property.
version (or v): The version of Elasticsearch that existed on the node when the transform
was created.
Comma-separated list of column names or column aliases used to sort the response.
Supported values include:
changes_last_detection_time (or cldt): The timestamp when changes were last detected in the source indices.checkpoint (or cp): The sequence number for the checkpoint.checkpoint_duration_time_exp_avg (or cdtea, checkpointTimeExpAvg): Exponential moving average of the duration of the checkpoint, in
milliseconds.checkpoint_progress (or c, checkpointProgress): The progress of the next checkpoint that is currently in progress.create_time (or ct, createTime): The time the transform was created.delete_time (or dtime): The amount of time spent deleting, in milliseconds.description (or d): The description of the transform.dest_index (or di, destIndex): The destination index for the transform. The mappings of the destination
index are deduced based on the source fields when possible. If alternate
mappings are required, use the Create index API prior to starting the
transform.documents_deleted (or docd): The number of documents that have been deleted from the destination index
due to the retention policy for this transform.documents_indexed (or doci): The number of documents that have been indexed into the destination index
for the transform.docs_per_second (or dps): Specifies a limit on the number of input documents per second. This setting
throttles the transform by adding a wait time between search requests. The
default value is null, which disables throttling.documents_processed (or docp): The number of documents that have been processed from the source index of
the transform.frequency (or f): The interval between checks for changes in the source indices when the
transform is running continuously. Also determines the retry interval in
the event of transient failures while the transform is searching or
indexing. The minimum value is 1s and the maximum is 1h. The default
value is 1m.id: Identifier for the transform.index_failure (or if): The number of indexing failures.index_time (or itime): The amount of time spent indexing, in milliseconds.index_total (or it): The number of index operations.indexed_documents_exp_avg (or idea): Exponential moving average of the number of new documents that have been
indexed.last_search_time (or lst, lastSearchTime): The timestamp of the last search in the source indices. This field is only
shown if the transform is running.max_page_search_size (or mpsz): Defines the initial page size to use for the composite aggregation for each
checkpoint. If circuit breaker exceptions occur, the page size is
dynamically adjusted to a lower value. The minimum value is 10 and the
maximum is 65,536. The default value is 500.pages_processed (or pp): The number of search or bulk index operations processed. Documents are
processed in batches instead of individually.pipeline (or p): The unique identifier for an ingest pipeline.processed_documents_exp_avg (or pdea): Exponential moving average of the number of documents that have been
processed.processing_time (or pt): The amount of time spent processing results, in milliseconds.reason (or r): If a transform has a failed state, this property provides details about
the reason for the failure.search_failure (or sf): The number of search failures.search_time (or stime): The amount of time spent searching, in milliseconds.search_total (or st): The number of search operations on the source index for the transform.source_index (or si, sourceIndex): The source indices for the transform. It can be a single index, an index
pattern (for example, "my-index-*"), an array of indices (for example,
["my-index-000001", "my-index-000002"]), or an array of index patterns
(for example, ["my-index-*", "my-other-index-*"]. For remote indices use
the syntax "remote_name:index_name". If any indices are in remote
clusters then the master node and at least one transform node must have the
remote_cluster_client node role.state (or s): The status of the transform, which can be one of the following values:
aborting: The transform is aborting.failed: The transform failed. For more information about the failure,
check the reason field.indexing: The transform is actively processing data and creating new
documents.started: The transform is running but not actively indexing data.stopped: The transform is stopped.stopping: The transform is stopping.transform_type (or tt): Indicates the type of transform: batch or continuous.
trigger_count (or tc): The number of times the transform has been triggered by the scheduler. For
example, the scheduler triggers the transform indexer to check for updates
or ingest new data at an interval specified in the frequency property.
version (or v): The version of Elasticsearch that existed on the node when the transform
was created.
The unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
The maximum number of transforms to obtain.
curl \
--request GET 'http://api.example.com/_cat/transforms/{transform_id}' \
--header "Authorization: $API_KEY"[
{
"id" : "ecommerce_transform",
"state" : "started",
"checkpoint" : "1",
"documents_processed" : "705",
"checkpoint_progress" : "100.00",
"changes_last_detection_time" : null
}
]Get information about configured remote clusters. The API returns connection and endpoint information keyed by the configured remote cluster alias.
This API returns information that reflects current state on the local cluster.
The connected field does not necessarily reflect whether a remote cluster is down or unavailable, only whether there is currently an open connection to it.
Elasticsearch does not spontaneously try to reconnect to a disconnected remote cluster.
To trigger a reconnection, attempt a cross-cluster search, ES|QL cross-cluster search, or try the resolve cluster endpoint.
curl \
--request GET 'http://api.example.com/_remote/info' \
--header "Authorization: $API_KEY"Get comprehensive information about the state of the cluster.
The cluster state is an internal data structure which keeps track of a variety of information needed by every node, including the identity and attributes of the other nodes in the cluster; cluster-wide settings; index metadata, including the mapping and settings for each index; the location and status of every shard copy in the cluster.
The elected master node ensures that every node in the cluster has a copy of the same cluster state. This API lets you retrieve a representation of this internal state for debugging or diagnostic purposes. You may need to consult the Elasticsearch source code to determine the precise meaning of the response.
By default the API will route requests to the elected master node since this node is the authoritative source of cluster states.
You can also retrieve the cluster state held on the node handling the API request by adding the ?local=true query parameter.
Elasticsearch may need to expend significant effort to compute a response to this API in larger clusters, and the response may comprise a very large quantity of data. If you use this API repeatedly, your cluster may become unstable.
WARNING: The response is a representation of an internal data structure. Its format is not subject to the same compatibility guarantees as other more stable APIs and may change from version to version. Do not query this API using external monitoring tools. Instead, obtain the information you require using other more stable cluster APIs.
Limit the information returned to the specified metrics
Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes _all string or when no indices have been specified)
Whether to expand wildcard expression to concrete indices that are open, closed or both.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.none: Wildcard expressions are not accepted.Return settings in flat format (default: false)
Return local information, do not retrieve the state from master node (default: false)
Specify timeout for connection to master
Wait for the metadata version to be equal or greater than the specified metadata version
The maximum time to wait for wait_for_metadata_version before timing out
curl \
--request GET 'http://api.example.com/_cluster/state/{metric}' \
--header "Authorization: $API_KEY"Get basic index metrics (shard numbers, store size, memory usage) and information about the current nodes that form the cluster (number, roles, os, jvm versions, memory usage, cpu and installed plugins).
Comma-separated list of node filters used to limit returned information. Defaults to all nodes in the cluster.
Include remote cluster data into the response
Period to wait for each node to respond.
If a node does not respond before its timeout expires, the response does not include its stats.
However, timed out nodes are included in the response’s _nodes.failed property. Defaults to no timeout.
curl \
--request GET 'http://api.example.com/_cluster/stats/nodes/{node_id}' \
--header "Authorization: $API_KEY"curl \
--request HEAD 'http://api.example.com/' \
--header "Authorization: $API_KEY"Clear the archived repositories metering information in the cluster.
Comma-separated list of node IDs or names used to limit returned information.
Specifies the maximum archive_version to be cleared from the archive.
curl \
--request DELETE 'http://api.example.com/_nodes/{node_id}/_repositories_metering/{max_archive_version}' \
--header "Authorization: $API_KEY"Get a report with the health status of an Elasticsearch cluster. The report contains a list of indicators that compose Elasticsearch functionality.
Each indicator has a health status of: green, unknown, yellow or red. The indicator will provide an explanation and metadata describing the reason for its current health status.
The cluster’s status is controlled by the worst indicator status.
In the event that an indicator’s status is non-green, a list of impacts may be present in the indicator result which detail the functionalities that are negatively affected by the health issue. Each impact carries with it a severity level, an area of the system that is affected, and a simple description of the impact on the system.
Some health indicators can determine the root cause of a health problem and prescribe a set of steps that can be performed in order to improve the health of the system. The root cause and remediation steps are encapsulated in a diagnosis. A diagnosis contains a cause detailing a root cause analysis, an action containing a brief description of the steps to take to fix the problem, the list of affected resources (if applicable), and a detailed step-by-step troubleshooting guide to fix the diagnosed problem.
NOTE: The health indicators perform root cause analysis of non-green health statuses. This can be computationally expensive when called frequently. When setting up automated polling of the API for health status, set verbose to false to disable the more expensive analysis logic.
curl \
--request GET 'http://api.example.com/_health_report' \
--header "Authorization: $API_KEY"Get a report with the health status of an Elasticsearch cluster. The report contains a list of indicators that compose Elasticsearch functionality.
Each indicator has a health status of: green, unknown, yellow or red. The indicator will provide an explanation and metadata describing the reason for its current health status.
The cluster’s status is controlled by the worst indicator status.
In the event that an indicator’s status is non-green, a list of impacts may be present in the indicator result which detail the functionalities that are negatively affected by the health issue. Each impact carries with it a severity level, an area of the system that is affected, and a simple description of the impact on the system.
Some health indicators can determine the root cause of a health problem and prescribe a set of steps that can be performed in order to improve the health of the system. The root cause and remediation steps are encapsulated in a diagnosis. A diagnosis contains a cause detailing a root cause analysis, an action containing a brief description of the steps to take to fix the problem, the list of affected resources (if applicable), and a detailed step-by-step troubleshooting guide to fix the diagnosed problem.
NOTE: The health indicators perform root cause analysis of non-green health statuses. This can be computationally expensive when called frequently. When setting up automated polling of the API for health status, set verbose to false to disable the more expensive analysis logic.
A feature of the cluster, as returned by the top-level health report API.
curl \
--request GET 'http://api.example.com/_health_report/{feature}' \
--header "Authorization: $API_KEY"The connector and sync jobs APIs provide a convenient way to create and manage Elastic connectors and sync jobs in an internal index.
Connectors are Elasticsearch integrations for syncing content from third-party data sources, which can be deployed on Elastic Cloud or hosted on your own infrastructure.
This API provides an alternative to relying solely on Kibana UI for connector and sync job management. The API comes with a set of validations and assertions to ensure that the state representation in the internal index remains valid.
This API requires the manage_connector privilege or, for read-only endpoints, the monitor_connector privilege.
Update the last_seen field in the connector and set it to the current timestamp.
The unique identifier of the connector to be checked in
curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_check_in' \
--header "Authorization: $API_KEY"{
"result": "updated"
}The unique identifier of the connector
A flag to indicate if the desired connector should be fetched, even if it was soft-deleted.
curl \
--request GET 'http://api.example.com/_connector/{connector_id}' \
--header "Authorization: $API_KEY"Starting offset (default: 0)
Specifies a max number of results to get
A comma-separated list of connector index names to fetch connector documents for
A comma-separated list of connector names to fetch connector documents for
A comma-separated list of connector service types to fetch connector documents for
A flag to indicate if the desired connector should be fetched, even if it was soft-deleted.
A wildcard query string that filters connectors with matching name, description or index name
curl \
--request GET 'http://api.example.com/_connector' \
--header "Authorization: $API_KEY"Connectors are Elasticsearch integrations that bring content from third-party data sources, which can be deployed on Elastic Cloud or hosted on your own infrastructure. Elastic managed connectors (Native connectors) are a managed service on Elastic Cloud. Self-managed connectors (Connector clients) are self-managed on your infrastructure.
curl \
--request POST 'http://api.example.com/_connector' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"description":"string","index_name":"string","is_native":true,"language":"string","name":"string","service_type":"string"}'Cancel a connector sync job, which sets the status to cancelling and updates cancellation_requested_at to the current time.
The connector service is then responsible for setting the status of connector sync jobs to cancelled.
The unique identifier of the connector sync job
curl \
--request PUT 'http://api.example.com/_connector/_sync_job/{connector_sync_job_id}/_cancel' \
--header "Authorization: $API_KEY"Update the connector features in the connector document. This API can be used to control the following aspects of a connector:
Normally, the running connector service automatically manages these features. However, you can use this API to override the default behavior.
To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure. This service runs automatically on Elastic Cloud for Elastic managed connectors.
The unique identifier of the connector to be updated.
curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_features' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"features\": {\n \"document_level_security\": {\n \"enabled\": true\n },\n \"incremental_sync\": {\n \"enabled\": true\n },\n \"sync_rules\": {\n \"advanced\": {\n \"enabled\": false\n },\n \"basic\": {\n \"enabled\": true\n }\n }\n }\n}"'{
"features": {
"document_level_security": {
"enabled": true
},
"incremental_sync": {
"enabled": true
},
"sync_rules": {
"advanced": {
"enabled": false
},
"basic": {
"enabled": true
}
}
}
}{
"features": {
"document_level_security": {
"enabled": true
}
}
}{
"result": "updated"
}Update the draft filtering validation info for a connector.
The unique identifier of the connector to be updated
curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_filtering/_validation' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"validation":{"errors":[{"ids":["string"],"messages":["string"]}],"state":"edited"}}'Update the index_name field of a connector, specifying the index where the data ingested by the connector is stored.
The unique identifier of the connector to be updated
curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_index_name' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"index_name\": \"data-from-my-google-drive\"\n}"'{
"index_name": "data-from-my-google-drive"
}{
"result": "updated"
}The unique identifier of the connector to be updated
curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_name' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"name\": \"Custom connector\",\n \"description\": \"This is my customized connector\"\n}"'{
"name": "Custom connector",
"description": "This is my customized connector"
}{
"result": "updated"
}The unique identifier of the connector to be updated
curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_native' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"is_native":true}'Create a cross-cluster replication follower index that follows a specific leader index. When the API returns, the follower index exists and cross-cluster replication starts replicating operations from the leader index to the follower index.
The name of the follower index.
Period to wait for a connection to the master node.
Specifies the number of shards to wait on being active before responding. This defaults to waiting on none of the shards to be active. A shard must be restored from the leader index before being active. Restoring a follower shard requires transferring all the remote Lucene segment files to the follower index.
If the leader index is part of a data stream, the name to which the local data stream for the followed index should be renamed.
The maximum number of outstanding reads requests from the remote cluster.
The maximum number of outstanding write requests on the follower.
The maximum number of operations to pull per read from the remote cluster.
A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and
d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
The maximum number of operations that can be queued for writing. When this limit is reached, reads from the remote cluster will be deferred until the number of queued operations goes below the limit.
The maximum number of operations per bulk write request executed on the follower.
A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and
d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
The remote cluster containing the leader index.
curl \
--request PUT 'http://api.example.com/{index}/_ccr/follow' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"remote_cluster\" : \"remote_cluster\",\n \"leader_index\" : \"leader_index\",\n \"settings\": {\n \"index.number_of_replicas\": 0\n },\n \"max_read_request_operation_count\" : 1024,\n \"max_outstanding_read_requests\" : 16,\n \"max_read_request_size\" : \"1024k\",\n \"max_write_request_operation_count\" : 32768,\n \"max_write_request_size\" : \"16k\",\n \"max_outstanding_write_requests\" : 8,\n \"max_write_buffer_count\" : 512,\n \"max_write_buffer_size\" : \"512k\",\n \"max_retry_delay\" : \"10s\",\n \"read_poll_timeout\" : \"30s\"\n}"'{
"remote_cluster" : "remote_cluster",
"leader_index" : "leader_index",
"settings": {
"index.number_of_replicas": 0
},
"max_read_request_operation_count" : 1024,
"max_outstanding_read_requests" : 16,
"max_read_request_size" : "1024k",
"max_write_request_operation_count" : 32768,
"max_write_request_size" : "16k",
"max_outstanding_write_requests" : 8,
"max_write_buffer_count" : 512,
"max_write_buffer_size" : "512k",
"max_retry_delay" : "10s",
"read_poll_timeout" : "30s"
}{
"follow_index_created" : true,
"follow_index_shards_acked" : true,
"index_following_started" : true
}Get cross-cluster replication auto-follow patterns.
The period to wait for a connection to the master node.
If the master node is not available before the timeout expires, the request fails and returns an error.
It can also be set to -1 to indicate that the request should never timeout.
curl \
--request GET 'http://api.example.com/_ccr/auto_follow' \
--header "Authorization: $API_KEY"{
"patterns": [
{
"name": "my_auto_follow_pattern",
"pattern": {
"active": true,
"remote_cluster" : "remote_cluster",
"leader_index_patterns" :
[
"leader_index*"
],
"leader_index_exclusion_patterns":
[
"leader_index_001"
],
"follow_index_pattern" : "{{leader_index}}-follower"
}
}
]
}Resume a cross-cluster replication auto-follow pattern that was paused. The auto-follow pattern will resume configuring following indices for newly created indices that match its patterns on the remote cluster. Remote indices created while the pattern was paused will also be followed unless they have been deleted or closed in the interim.
The name of the auto-follow pattern to resume.
The period to wait for a connection to the master node.
If the master node is not available before the timeout expires, the request fails and returns an error.
It can also be set to -1 to indicate that the request should never timeout.
curl \
--request POST 'http://api.example.com/_ccr/auto_follow/{name}/resume' \
--header "Authorization: $API_KEY"{
"acknowledged" : true
}Convert a cross-cluster replication follower index to a regular index. The API stops the following task associated with a follower index and removes index metadata and settings associated with cross-cluster replication. The follower index must be paused and closed before you call the unfollow API.
Currently cross-cluster replication does not support converting an existing regular index to a follower index. Converting a follower index to a regular index is an irreversible operation.
The name of the follower index.
The period to wait for a connection to the master node.
If the master node is not available before the timeout expires, the request fails and returns an error.
It can also be set to -1 to indicate that the request should never timeout.
curl \
--request POST 'http://api.example.com/{index}/_ccr/unfollow' \
--header "Authorization: $API_KEY"{
"acknowledged" : true
}Deletes one or more data streams and their backing indices.
Comma-separated list of data streams to delete. Wildcard (*) expressions are supported.
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.
Type of data stream that wildcard patterns can match. Supports comma-separated values,such as open,hidden.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.none: Wildcard expressions are not accepted.curl \
--request DELETE 'http://api.example.com/_data_stream/{name}' \
--header "Authorization: $API_KEY"Get statistics for one or more data streams.
Type of data stream that wildcard patterns can match.
Supports comma-separated values, such as open,hidden.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.none: Wildcard expressions are not accepted.curl \
--request GET 'http://api.example.com/_data_stream/_stats' \
--header "Authorization: $API_KEY"{
"_shards": {
"total": 10,
"successful": 5,
"failed": 0
},
"data_stream_count": 2,
"backing_indices": 5,
"total_store_size": "7kb",
"total_store_size_bytes": 7268,
"data_streams": [
{
"data_stream": "my-data-stream",
"backing_indices": 3,
"store_size": "3.7kb",
"store_size_bytes": 3772,
"maximum_timestamp": 1607512028000
},
{
"data_stream": "my-data-stream-two",
"backing_indices": 2,
"store_size": "3.4kb",
"store_size_bytes": 3496,
"maximum_timestamp": 1607425567000
}
]
}Update the data stream lifecycle of the specified data streams.
Comma-separated list of data streams used to limit the request.
Supports wildcards (*).
To target all data streams use * or _all.
Type of data stream that wildcard patterns can match.
Supports comma-separated values, such as open,hidden.
Valid values are: all, hidden, open, closed, none.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.none: Wildcard expressions are not accepted.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.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and
d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
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.
curl \
--request PUT 'http://api.example.com/_data_stream/{name}/_lifecycle' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"data_retention\": \"7d\"\n}"'{
"data_retention": "7d"
}{
"downsampling": [
{
"after": "1d",
"fixed_interval": "10m"
},
{
"after": "7d",
"fixed_interval": "1d"
}
]
}{
"acknowledged": true
}Aggregate a time series (TSDS) index and store pre-computed statistical summaries (min, max, sum, value_count and avg) for each metric field grouped by a configured time interval.
For example, a TSDS index that contains metrics sampled every 10 seconds can be downsampled to an hourly index.
All documents within an hour interval are summarized and stored as a single document in the downsample index.
NOTE: Only indices in a time series data stream are supported.
Neither field nor document level security can be defined on the source index.
The source index must be read only (index.blocks.write: true).
Name of the time series index to downsample.
Name of the index to create.
A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and
y (year)
curl \
--request POST 'http://api.example.com/{index}/_downsample/{target_index}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"fixed_interval\": \"1d\"\n}"'{
"fixed_interval": "1d"
}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.
The name of the index to explain
indicates if the API should return the default values the system uses for the index's lifecycle
Specify timeout for connection to master
curl \
--request GET 'http://api.example.com/{index}/_lifecycle/explain' \
--header "Authorization: $API_KEY"{
"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"
}
}{
"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;\"}"
}
}Get statistics about the data streams that are managed by a data stream lifecycle.
curl \
--request GET 'http://api.example.com/_lifecycle/stats' \
--header "Authorization: $API_KEY"{
"last_run_duration_in_millis": 2,
"last_run_duration": "2ms",
"time_between_starts_in_millis": 9998,
"time_between_starts": "9.99s",
"data_streams_count": 2,
"data_streams": [
{
"name": "my-data-stream",
"backing_indices_in_total": 2,
"backing_indices_in_error": 0
},
{
"name": "my-other-stream",
"backing_indices_in_total": 2,
"backing_indices_in_error": 1
}
]
}Type of data stream that wildcard patterns can match.
Supports comma-separated values, such as open,hidden.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.none: Wildcard expressions are not accepted.If true, returns all relevant default configurations for the index template.
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.
Whether the maximum timestamp for each data stream should be calculated and returned.
curl \
--request GET 'http://api.example.com/_data_stream' \
--header "Authorization: $API_KEY"{
"data_streams": [
{
"name": "my-data-stream",
"timestamp_field": {
"name": "@timestamp"
},
"indices": [
{
"index_name": ".ds-my-data-stream-2099.03.07-000001",
"index_uuid": "xCEhwsp8Tey0-FLNFYVwSg",
"prefer_ilm": true,
"ilm_policy": "my-lifecycle-policy",
"managed_by": "Index Lifecycle Management"
},
{
"index_name": ".ds-my-data-stream-2099.03.08-000002",
"index_uuid": "PA_JquKGSiKcAKBA8DJ5gw",
"prefer_ilm": true,
"ilm_policy": "my-lifecycle-policy",
"managed_by": "Index Lifecycle Management"
}
],
"generation": 2,
"_meta": {
"my-meta-field": "foo"
},
"status": "GREEN",
"next_generation_managed_by": "Index Lifecycle Management",
"prefer_ilm": true,
"template": "my-index-template",
"ilm_policy": "my-lifecycle-policy",
"hidden": false,
"system": false,
"allow_custom_routing": false,
"replicated": false,
"rollover_on_write": false
},
{
"name": "my-data-stream-two",
"timestamp_field": {
"name": "@timestamp"
},
"indices": [
{
"index_name": ".ds-my-data-stream-two-2099.03.08-000001",
"index_uuid": "3liBu2SYS5axasRt6fUIpA",
"prefer_ilm": true,
"ilm_policy": "my-lifecycle-policy",
"managed_by": "Index Lifecycle Management"
}
],
"generation": 1,
"_meta": {
"my-meta-field": "foo"
},
"status": "YELLOW",
"next_generation_managed_by": "Index Lifecycle Management",
"prefer_ilm": true,
"template": "my-index-template",
"ilm_policy": "my-lifecycle-policy",
"hidden": false,
"system": false,
"allow_custom_routing": false,
"replicated": false,
"rollover_on_write": false
}
]
}Get the source of a document. For example:
GET my-index-000001/_source/1
You can use the source filtering parameters to control which parts of the _source are returned:
GET my-index-000001/_source/1/?_source_includes=*.id&_source_excludes=entities
The node or shard the operation should be performed on. By default, the operation is randomized between the shard replicas.
If true, the request is real-time as opposed to near-real-time.
If true, the request refreshes the relevant shards before retrieving the document.
Setting it to true should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).
A custom value used to route operations to a specific shard.
Indicates whether to return the _source field (true or false) or lists the fields to return.
A comma-separated list of source fields to exclude in the response.
A comma-separated list of source fields to include in the response.
A comma-separated list of stored fields to return as part of a hit.
The version number for concurrency control. It must match the current version of the document for the request to succeed.
The version type.
Supported values include:
internal: Use internal versioning that starts at 1 and increments with each update or delete.external: Only index the document if the specified version is strictly higher than the version of the stored document or if there is no existing document.external_gte: Only index the document if the specified version is equal or higher than the version of the stored document or if there is no existing document.
NOTE: The external_gte version type is meant for special use cases and should be used with care.
If used incorrectly, it can result in loss of data.force: This option is deprecated because it can cause primary and replica shards to diverge.Values are internal, external, external_gte, or force.
curl \
--request GET 'http://api.example.com/{index}/_source/{id}' \
--header "Authorization: $API_KEY"Check whether a document source exists in an index. For example:
HEAD my-index-000001/_source/1
A document's source is not available if it is disabled in the mapping.
The node or shard the operation should be performed on. By default, the operation is randomized between the shard replicas.
If true, the request is real-time as opposed to near-real-time.
If true, the request refreshes the relevant shards before retrieving the document.
Setting it to true should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).
A custom value used to route operations to a specific shard.
Indicates whether to return the _source field (true or false) or lists the fields to return.
A comma-separated list of source fields to exclude in the response.
A comma-separated list of source fields to include in the response.
The version number for concurrency control. It must match the current version of the document for the request to succeed.
The version type.
Supported values include:
internal: Use internal versioning that starts at 1 and increments with each update or delete.external: Only index the document if the specified version is strictly higher than the version of the stored document or if there is no existing document.external_gte: Only index the document if the specified version is equal or higher than the version of the stored document or if there is no existing document.
NOTE: The external_gte version type is meant for special use cases and should be used with care.
If used incorrectly, it can result in loss of data.force: This option is deprecated because it can cause primary and replica shards to diverge.Values are internal, external, external_gte, or force.
curl \
--request HEAD 'http://api.example.com/{index}/_source/{id}' \
--header "Authorization: $API_KEY"Get multiple JSON documents by ID from one or more indices. If you specify an index in the request URI, you only need to specify the document IDs in the request body. To ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.
Filter source fields
By default, the _source field is returned for every document (if stored).
Use the _source and _source_include or source_exclude attributes to filter what fields are returned for a particular document.
You can include the _source, _source_includes, and _source_excludes query parameters in the request URI to specify the defaults to use when there are no per-document instructions.
Get stored fields
Use the stored_fields attribute to specify the set of stored fields you want to retrieve.
Any requested fields that are not stored are ignored.
You can include the stored_fields query parameter in the request URI to specify the defaults to use when there are no per-document instructions.
Specifies the node or shard the operation should be performed on. Random by default.
If true, the request is real-time as opposed to near-real-time.
If true, the request refreshes relevant shards before retrieving documents.
Custom value used to route operations to a specific shard.
True or false to return the _source field or not, or a list of fields to return.
A comma-separated list of source fields to exclude from the response.
You can also use this parameter to exclude fields from the subset specified in _source_includes query parameter.
A comma-separated list of source fields to include in the response.
If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the _source_excludes query parameter.
If the _source parameter is false, this parameter is ignored.
If true, retrieves the document fields stored in the index rather than the document _source.
curl \
--request POST 'http://api.example.com/_mget' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"docs\": [\n {\n \"_id\": \"1\"\n },\n {\n \"_id\": \"2\"\n }\n ]\n}"'{
"docs": [
{
"_id": "1"
},
{
"_id": "2"
}
]
}{
"docs": [
{
"_index": "test",
"_id": "1",
"_source": false
},
{
"_index": "test",
"_id": "2",
"_source": [ "field3", "field4" ]
},
{
"_index": "test",
"_id": "3",
"_source": {
"include": [ "user" ],
"exclude": [ "user.location" ]
}
}
]
}{
"docs": [
{
"_index": "test",
"_id": "1",
"stored_fields": [ "field1", "field2" ]
},
{
"_index": "test",
"_id": "2",
"stored_fields": [ "field3", "field4" ]
}
]
}{
"docs": [
{
"_index": "test",
"_id": "1",
"routing": "key2"
},
{
"_index": "test",
"_id": "2"
}
]
}Get multiple JSON documents by ID from one or more indices. If you specify an index in the request URI, you only need to specify the document IDs in the request body. To ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.
Filter source fields
By default, the _source field is returned for every document (if stored).
Use the _source and _source_include or source_exclude attributes to filter what fields are returned for a particular document.
You can include the _source, _source_includes, and _source_excludes query parameters in the request URI to specify the defaults to use when there are no per-document instructions.
Get stored fields
Use the stored_fields attribute to specify the set of stored fields you want to retrieve.
Any requested fields that are not stored are ignored.
You can include the stored_fields query parameter in the request URI to specify the defaults to use when there are no per-document instructions.
Name of the index to retrieve documents from when ids are specified, or when a document in the docs array does not specify an index.
Specifies the node or shard the operation should be performed on. Random by default.
If true, the request is real-time as opposed to near-real-time.
If true, the request refreshes relevant shards before retrieving documents.
Custom value used to route operations to a specific shard.
True or false to return the _source field or not, or a list of fields to return.
A comma-separated list of source fields to exclude from the response.
You can also use this parameter to exclude fields from the subset specified in _source_includes query parameter.
A comma-separated list of source fields to include in the response.
If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the _source_excludes query parameter.
If the _source parameter is false, this parameter is ignored.
If true, retrieves the document fields stored in the index rather than the document _source.
curl \
--request GET 'http://api.example.com/{index}/_mget' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"docs\": [\n {\n \"_id\": \"1\"\n },\n {\n \"_id\": \"2\"\n }\n ]\n}"'{
"docs": [
{
"_id": "1"
},
{
"_id": "2"
}
]
}{
"docs": [
{
"_index": "test",
"_id": "1",
"_source": false
},
{
"_index": "test",
"_id": "2",
"_source": [ "field3", "field4" ]
},
{
"_index": "test",
"_id": "3",
"_source": {
"include": [ "user" ],
"exclude": [ "user.location" ]
}
}
]
}{
"docs": [
{
"_index": "test",
"_id": "1",
"stored_fields": [ "field1", "field2" ]
},
{
"_index": "test",
"_id": "2",
"stored_fields": [ "field3", "field4" ]
}
]
}{
"docs": [
{
"_index": "test",
"_id": "1",
"routing": "key2"
},
{
"_index": "test",
"_id": "2"
}
]
}Update a document by running a script or passing a partial document.
If the Elasticsearch security features are enabled, you must have the index or write index privilege for the target index or index alias.
The script can update, delete, or skip modifying the document. The API also supports passing a partial document, which is merged into the existing document. To fully replace an existing document, use the index API. This operation:
The document must still be reindexed, but using this API removes some network roundtrips and reduces chances of version conflicts between the GET and the index operation.
The _source field must be enabled to use this API.
In addition to _source, you can access the following variables through the ctx map: _index, _type, _id, _version, _routing, and _now (the current timestamp).
Only perform the operation if the document has this primary term.
Only perform the operation if the document has this sequence number.
True or false if to include the document source in the error message in case of parsing errors.
The script language.
If 'true', Elasticsearch refreshes the affected shards to make this operation visible to search. If 'wait_for', it waits for a refresh to make this operation visible to search. If 'false', it does nothing with refreshes.
Values are true, false, or wait_for.
If true, the destination must be an index alias.
The number of times the operation should be retried when a conflict occurs.
A custom value used to route operations to a specific shard.
The period to wait for the following operations: dynamic mapping updates and waiting for active shards. Elasticsearch waits for at least the timeout period before failing. The actual wait time could be longer, particularly when multiple waits occur.
The number of copies of each shard that must be active before proceeding with the operation.
Set to 'all' or any positive integer up to the total number of shards in the index (number_of_replicas+1).
The default value of 1 means it waits for each primary shard to be active.
If false, source retrieval is turned off.
You can also specify a comma-separated list of the fields you want to retrieve.
The source fields you want to exclude.
The source fields you want to retrieve.
If true, the result in the response is set to noop (no operation) when there are no changes to the document.
A partial update to an existing document.
If both doc and script are specified, doc is ignored.
If true, use the contents of 'doc' as the value of 'upsert'.
NOTE: Using ingest pipelines with doc_as_upsert is not supported.
If true, run the script whether or not the document exists.
Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
If the document does not already exist, the contents of 'upsert' are inserted as a new document. If the document exists, the 'script' is run.
curl \
--request POST 'http://api.example.com/{index}/_update/{id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"script\" : {\n \"source\": \"ctx._source.counter += params.count\",\n \"lang\": \"painless\",\n \"params\" : {\n \"count\" : 4\n }\n }\n}"'{
"script" : {
"source": "ctx._source.counter += params.count",
"lang": "painless",
"params" : {
"count" : 4
}
}
}{
"scripted_upsert": true,
"script": {
"source": """
if ( ctx.op == 'create' ) {
ctx._source.counter = params.count
} else {
ctx._source.counter += params.count
}
""",
"params": {
"count": 4
}
},
"upsert": {}
}{
"doc": {
"name": "new_name"
},
"doc_as_upsert": true
}{
"script": {
"source": "ctx._source.tags.add(params.tag)",
"lang": "painless",
"params": {
"tag": "blue"
}
}
}{
"script": {
"source": "if (ctx._source.tags.contains(params.tag)) { ctx._source.tags.remove(ctx._source.tags.indexOf(params.tag)) }",
"lang": "painless",
"params": {
"tag": "blue"
}
}
}{
"script" : "ctx._source.new_field = 'value_of_new_field'"
}{
"script" : "ctx._source.remove('new_field')"
}{
"script": "ctx._source['my-object'].remove('my-subfield')"
}{
"script": {
"source": "if (ctx._source.tags.contains(params.tag)) { ctx.op = 'delete' } else { ctx.op = 'noop' }",
"lang": "painless",
"params": {
"tag": "green"
}
}
}{
"doc": {
"name": "new_name"
}
}{
"script": {
"source": "ctx._source.counter += params.count",
"lang": "painless",
"params": {
"count": 4
}
},
"upsert": {
"counter": 1
}
}{
"_shards": {
"total": 0,
"successful": 0,
"failed": 0
},
"_index": "test",
"_id": "1",
"_version": 2,
"_primary_term": 1,
"_seq_no": 1,
"result": "noop"
}Returns information about an enrich policy.
Comma-separated list of enrich policy names used to limit the request. To return information for all enrich policies, omit this parameter.
Period to wait for a connection to the master node.
curl \
--request GET 'http://api.example.com/_enrich/policy/{name}' \
--header "Authorization: $API_KEY"Period to wait for a connection to the master node.
curl \
--request GET 'http://api.example.com/_enrich/policy' \
--header "Authorization: $API_KEY"Event Query Language (EQL) is a query language for event-based time series data, such as logs, metrics, and traces.
The Elasticsearch Query Language (ES|QL) provides a powerful way to filter, transform, and analyze data stored in Elasticsearch, and in the future in other runtimes.
This API interrupts the query execution and returns the results so far. If the Elasticsearch security features are enabled, only the user who first submitted the ES|QL query can stop it.
The unique identifier of the query.
A query ID is provided in the ES|QL async query API response for a query that does not complete in the designated time.
A query ID is also provided when the request was submitted with the keep_on_completion parameter set to true.
Indicates whether columns that are entirely null will be removed from the columns and values portion of the results.
If true, the response will include an extra section under the name all_columns which has the name of all the columns.
curl \
--request POST 'http://api.example.com/_query/async/{id}/stop' \
--header "Authorization: $API_KEY"Get a list of features that can be included in snapshots using the feature_states field when creating a snapshot.
You can use this API to determine which feature states to include when taking a snapshot.
By default, all feature states are included in a snapshot if that snapshot includes the global state, or none if it does not.
A feature state includes one or more system indices necessary for a given feature to function. In order to ensure data integrity, all system indices that comprise a feature state are snapshotted and restored together.
The features listed by this API are a combination of built-in features and features defined by plugins. In order for a feature state to be listed in this API and recognized as a valid feature state by the create snapshot API, the plugin that defines that feature must be installed on the master node.
Period to wait for a connection to the master node.
curl \
--request GET 'http://api.example.com/_features' \
--header "Authorization: $API_KEY"{
"features": [
{
"name": "tasks",
"description": "Manages task results"
},
{
"name": "kibana",
"description": "Manages Kibana configuration and reports"
}
]
}Get the current global checkpoints for an index. This API is designed for internal use by the Fleet server project.
A single index or index alias that resolves to a single index.
A boolean value which controls whether to wait (until the timeout) for the global checkpoints
to advance past the provided checkpoints.
A boolean value which controls whether to wait (until the timeout) for the target index to exist
and all primary shards be active. Can only be true when wait_for_advance is true.
A comma separated list of previous global checkpoints. When used in combination with wait_for_advance,
the API will only return once the global checkpoints advances past the checkpoints. Providing an empty list
will cause Elasticsearch to immediately return the current global checkpoints.
Period to wait for a global checkpoints to advance past checkpoints.
curl \
--request GET 'http://api.example.com/{index}/_fleet/global_checkpoints' \
--header "Authorization: $API_KEY"