Delete an autoscaling policy Generally available; Added in 7.11.0

DELETE /_autoscaling/policy/{name}

NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.

External documentation

Path parameters

name string Required

the name of the autoscaling policy

Query parameters

master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
timeout string

Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

DELETE /_autoscaling/policy/{name}

DELETE /_autoscaling/policy/*

resp = client.autoscaling.delete_autoscaling_policy(
    name="*",
)

const response = await client.autoscaling.deleteAutoscalingPolicy({
  name: "*",
});

response = client.autoscaling.delete_autoscaling_policy(
  name: "*"
)

$resp = $client->autoscaling()->deleteAutoscalingPolicy([
    "name" => "*",
]);

curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_autoscaling/policy/*"

client.autoscaling().deleteAutoscalingPolicy(d -> d
    .name("*")
);

Response examples (200)

This may be a response to either `DELETE /_autoscaling/policy/my_autoscaling_policy` or `DELETE /_autoscaling/policy/*`.

{
  "acknowledged": true
}

Get a document count Generally available

GET /_cat/count/{index}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_cat/count

GET /_cat/count/{index}

Get quick access to a document count for a data stream, an index, or an entire cluster. The document count only includes live documents, not deleted documents which have not yet been removed by the merge process.

IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the count API.

Required authorization

Index privileges: read

Path parameters

index string | array[string] Required

A comma-separated list of data streams, indices, and aliases used to limit the request. It supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all.

Query parameters

h string | array[string]

List of columns to appear in the response. Supports simple wildcards.
s string | array[string]

List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.

Responses

200 application/json
Hide response attributes Show response attributes object
- epoch number | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  UnitSeconds number string-2 string
  
  Time unit for seconds
- timestamp string
  
  Time of day, expressed as HH:MM:SS
- count string
  
  the document count

GET /_cat/count/{index}

GET /_cat/count/my-index-000001?v=true&format=json

resp = client.cat.count(
    index="my-index-000001",
    v=True,
    format="json",
)

const response = await client.cat.count({
  index: "my-index-000001",
  v: "true",
  format: "json",
});

response = client.cat.count(
  index: "my-index-000001",
  v: "true",
  format: "json"
)

$resp = $client->cat()->count([
    "index" => "my-index-000001",
    "v" => "true",
    "format" => "json",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/count/my-index-000001?v=true&format=json"

client.cat().count();

Response examples (200)

A successful response from `GET /_cat/count/my-index-000001?v=true&format=json`. It retrieves the document count for the `my-index-000001` data stream or index.

[
  {
    "epoch": "1475868259",
    "timestamp": "15:24:20",
    "count": "120"
  }
]

A successful response from `GET /_cat/count?v=true&format=json`. It retrieves the document count for all data streams and indices in the cluster.

[
  {
    "epoch": "1475868259",
    "timestamp": "15:24:20",
    "count": "121"
  }
]

Get anomaly detection jobs Generally available; Added in 7.7.0

GET /_cat/ml/anomaly_detectors/{job_id}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_cat/ml/anomaly_detectors

GET /_cat/ml/anomaly_detectors/{job_id}

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.

Required authorization

Cluster privileges: monitor_ml

Path parameters

job_id string Required

Identifier for the anomaly detection job.

Query parameters

allow_no_match boolean
Specifies what to do when the request:
- Contains wildcard expressions and there are no jobs 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 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.
bytes string

The unit used to display byte values.

Values are b, kb, mb, gb, tb, or pb.
h string | array[string]
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.
s string | array[string]
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.
time string

The unit used to display time values.

Values are nanos, micros, ms, s, m, h, or d.

Responses

200 application/json
Hide response attributes Show response attributes object
- id string
- state string
  
  Values are closing, closed, opened, failed, or opening.
- opened_time string
  
  For open jobs only, the amount of time the job has been opened.
- assignment_explanation string
  
  For open anomaly detection jobs only, contains messages relating to the selection of a node to run the job.
- data.processed_records string
  
  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.processed_fields string
  
  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.input_bytes number | string
  
  One of:
  number-1 number string-2 string
- data.input_records string
  
  The number of input documents posted to the anomaly detection job.
- data.input_fields string
  
  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.invalid_dates string
  
  The number of input documents with either a missing date field or a date that could not be parsed.
- data.missing_fields string
  
  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. If you are using datafeeds or posting data to the job in JSON format, a high missing_field_count is often not an indication of data issues. It is not necessarily a cause for concern.
- data.out_of_order_timestamps string
  
  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.empty_buckets string
  
  The number of buckets which did not contain any data. If your data contains many empty buckets, consider increasing your bucket_span or using functions that are tolerant to gaps in data such as mean, non_null_sum or non_zero_count.
- data.sparse_buckets string
  
  The number of buckets that contained few data points compared to the expected number of data points. If your data contains many sparse buckets, consider using a longer bucket_span.
- data.buckets string
  
  The total number of buckets processed.
- data.earliest_record string
  
  The timestamp of the earliest chronologically input document.
- data.latest_record string
  
  The timestamp of the latest chronologically input document.
- data.last string
  
  The timestamp at which data was last analyzed, according to server time.
- data.last_empty_bucket string
  
  The timestamp of the last bucket that did not contain any data.
- data.last_sparse_bucket string
  
  The timestamp of the last bucket that was considered sparse.
- model.bytes number | string
  
  One of:
  number-1 number string-2 string
- model.memory_status string
  
  Values are ok, soft_limit, or hard_limit.
- model.bytes_exceeded number | string
  
  One of:
  number-1 number string-2 string
- model.memory_limit string
  
  The upper limit for model memory usage, checked on increasing values.
- model.by_fields string
  
  The number of by field values that were analyzed by the models. This value is cumulative for all detectors in the job.
- model.over_fields string
  
  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 string
  
  The number of partition field values that were analyzed by the models. This value is cumulative for all detectors in the job.
- model.bucket_allocation_failures string
  
  The number of buckets for which new entities in incoming data were not processed due to insufficient model memory. This situation is also signified by a hard_limit: memory_status property value.
- model.categorization_status string
  
  Values are ok or warn.
- model.categorized_doc_count string
  
  The number of documents that have had a field categorized.
- model.total_category_count string
  
  The number of categories created by categorization.
- model.frequent_category_count string
  
  The number of categories that match more than 1% of categorized documents.
- model.rare_category_count string
  
  The number of categories that match just one categorized document.
- model.dead_category_count string
  
  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 string
  
  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.log_time string
  
  The timestamp when the model stats were gathered, according to server time.
- model.timestamp string
  
  The timestamp of the last record when the model stats were gathered.
- forecasts.total string
  
  The number of individual forecasts currently available for the job. A value of one or more indicates that forecasts exist.
- forecasts.memory.min string
  
  The minimum memory usage in bytes for forecasts related to the anomaly detection job.
- forecasts.memory.max string
  
  The maximum memory usage in bytes for forecasts related to the anomaly detection job.
- forecasts.memory.avg string
  
  The average memory usage in bytes for forecasts related to the anomaly detection job.
- forecasts.memory.total string
  
  The total memory usage in bytes for forecasts related to the anomaly detection job.
- forecasts.records.min string
  
  The minimum number of model_forecast documents written for forecasts related to the anomaly detection job.
- forecasts.records.max string
  
  The maximum number of model_forecast documents written for forecasts related to the anomaly detection job.
- forecasts.records.avg string
  
  The average number of model_forecast documents written for forecasts related to the anomaly detection job.
- forecasts.records.total string
  
  The total number of model_forecast documents written for forecasts related to the anomaly detection job.
- forecasts.time.min string
  
  The minimum runtime in milliseconds for forecasts related to the anomaly detection job.
- forecasts.time.max string
  
  The maximum runtime in milliseconds for forecasts related to the anomaly detection job.
- forecasts.time.avg string
  
  The average runtime in milliseconds for forecasts related to the anomaly detection job.
- forecasts.time.total string
  
  The total runtime in milliseconds for forecasts related to the anomaly detection job.
- node.id string
- node.name string
  
  The name of the assigned node.
- node.ephemeral_id string
- node.address string
  
  The network address of the assigned node.
- buckets.count string
  
  The number of bucket results produced by the job.
- buckets.time.total string
  
  The sum of all bucket processing times, in milliseconds.
- buckets.time.min string
  
  The minimum of all bucket processing times, in milliseconds.
- buckets.time.max string
  
  The maximum of all bucket processing times, in milliseconds.
- buckets.time.exp_avg string
  
  The exponential moving average of all bucket processing times, in milliseconds.
- buckets.time.exp_avg_hour string
  
  The exponential moving average of bucket processing times calculated in a one hour time window, in milliseconds.

GET /_cat/ml/anomaly_detectors/{job_id}

GET _cat/ml/anomaly_detectors?h=id,s,dpr,mb&v=true&format=json

resp = client.cat.ml_jobs(
    h="id,s,dpr,mb",
    v=True,
    format="json",
)

const response = await client.cat.mlJobs({
  h: "id,s,dpr,mb",
  v: "true",
  format: "json",
});

response = client.cat.ml_jobs(
  h: "id,s,dpr,mb",
  v: "true",
  format: "json"
)

$resp = $client->cat()->mlJobs([
    "h" => "id,s,dpr,mb",
    "v" => "true",
    "format" => "json",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/ml/anomaly_detectors?h=id,s,dpr,mb&v=true&format=json"

client.cat().mlJobs();

Response examples (200)

A successful response from `GET _cat/ml/anomaly_detectors?h=id,s,dpr,mb&v=true&format=json`.

[
  {
    "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 plugin information Generally available

GET /_cat/plugins

Api key auth Basic auth Bearer auth

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.

Required authorization

Cluster privileges: monitor

Query parameters

h string | array[string]

List of columns to appear in the response. Supports simple wildcards.
s string | array[string]

List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.
include_bootstrap boolean

Include bootstrap plugins in the response
local boolean

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.
master_timeout string

Period to wait for a connection to the master node.

Values are -1 or 0.

Responses

200 application/json
Hide response attributes Show response attributes object
- id string
- name string
- component string
  
  The component name.
- version string
- description string
  
  The plugin details.
- type string
  
  The plugin type.

GET /_cat/plugins

GET /_cat/plugins?v=true&s=component&h=name,component,version,description&format=json

resp = client.cat.plugins(
    v=True,
    s="component",
    h="name,component,version,description",
    format="json",
)

const response = await client.cat.plugins({
  v: "true",
  s: "component",
  h: "name,component,version,description",
  format: "json",
});

response = client.cat.plugins(
  v: "true",
  s: "component",
  h: "name,component,version,description",
  format: "json"
)

$resp = $client->cat()->plugins([
    "v" => "true",
    "s" => "component",
    "h" => "name,component,version,description",
    "format" => "json",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/plugins?v=true&s=component&h=name,component,version,description&format=json"

client.cat().plugins();

Response examples (200)

A successful response from `GET /_cat/plugins?v=true&s=component&h=name,component,version,description&format=json`.

[
  { "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 snapshot repository information Generally available; Added in 2.1.0

GET /_cat/repositories

Api key auth Basic auth Bearer auth

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.

Required authorization

Cluster privileges: monitor_snapshot

Query parameters

h string | array[string]

List of columns to appear in the response. Supports simple wildcards.
s string | array[string]

List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.
local boolean

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.
master_timeout string

Period to wait for a connection to the master node.

Values are -1 or 0.

Responses

200 application/json
Hide response attributes Show response attributes object
- id string
  
  The unique repository identifier.
- type string
  
  The repository type.

GET /_cat/repositories

GET /_cat/repositories?v=true&format=json

resp = client.cat.repositories(
    v=True,
    format="json",
)

const response = await client.cat.repositories({
  v: "true",
  format: "json",
});

response = client.cat.repositories(
  v: "true",
  format: "json"
)

$resp = $client->cat()->repositories([
    "v" => "true",
    "format" => "json",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/repositories?v=true&format=json"

client.cat().repositories();

Response examples (200)

A successful response from `GET /_cat/repositories?v=true&format=json`.

[
  {
    "id": "repo1",
    "type": "fs"
  },
  {
    "id": "repo2",
    "type": "s3"
  }
]

Clear cluster voting config exclusions Generally available; Added in 7.0.0

DELETE /_cluster/voting_config_exclusions

Api key auth Basic auth Bearer auth

Remove master-eligible nodes from the voting configuration exclusion list.

External documentation

Query parameters

master_timeout string

Period to wait for a connection to the master node.

Values are -1 or 0.
wait_for_removal boolean

Specifies whether to wait for all excluded nodes to be removed from the cluster before clearing the voting configuration exclusions list. Defaults to true, meaning that all excluded nodes must be removed from the cluster before this API takes any action. If set to false then the voting configuration exclusions list is cleared even if some excluded nodes are still in the cluster.

Responses

200 application/json

DELETE /_cluster/voting_config_exclusions

curl \
 --request DELETE 'http://api.example.com/_cluster/voting_config_exclusions' \
 --header "Authorization: $API_KEY"

Get cluster-wide settings Generally available

GET /_cluster/settings

Api key auth Basic auth Bearer auth

By default, it returns only settings that have been explicitly defined.

Required authorization

Cluster privileges: monitor

External documentation

Query parameters

flat_settings boolean

If true, returns settings in flat format.
include_defaults boolean

If true, returns default cluster settings from the local node.
master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
timeout string

Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

Responses

200 application/json
Hide response attributes Show response attributes object
- persistent object Required
  
  The settings that persist after the cluster restarts.
  
  Hide persistent attribute Show persistent attribute object
  
  * object Additional properties
- transient object Required
  
  The settings that do not persist after the cluster restarts.
  
  Hide transient attribute Show transient attribute object
  
  * object Additional properties
- defaults object
  
  The default setting values.
  
  Hide defaults attribute Show defaults attribute object
  
  * object Additional properties

GET /_cluster/settings

GET /_cluster/settings?filter_path=persistent.cluster.remote

resp = client.cluster.get_settings(
    filter_path="persistent.cluster.remote",
)

const response = await client.cluster.getSettings({
  filter_path: "persistent.cluster.remote",
});

response = client.cluster.get_settings(
  filter_path: "persistent.cluster.remote"
)

$resp = $client->cluster()->getSettings([
    "filter_path" => "persistent.cluster.remote",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cluster/settings?filter_path=persistent.cluster.remote"

Get the cluster health status Generally available; Added in 1.3.0

GET /_cluster/health/{index}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_cluster/health

GET /_cluster/health/{index}

You can also use the API to get the health status of only specified data streams and indices. For data streams, the API retrieves the health status of the stream’s backing indices.

The cluster health status is: green, yellow or red. On the shard level, a red status indicates that the specific shard is not allocated in the cluster. Yellow means that the primary shard is allocated but replicas are not. Green means that all shards are allocated. The index level status is controlled by the worst shard status.

One of the main benefits of the API is the ability to wait until the cluster reaches a certain high watermark health level. The cluster status is controlled by the worst index status.

Required authorization

Cluster privileges: monitor,manage

Path parameters

index string | array[string] Required

Comma-separated list of data streams, indices, and index aliases used to limit the request. Wildcard expressions (*) are supported. To target all data streams and indices in a cluster, omit this parameter or use _all or *.

Query parameters

expand_wildcards string | array[string]
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.
Values are all, open, closed, hidden, or none.
level string

Can be one of cluster, indices or shards. Controls the details level of the health information returned.

Values are cluster, indices, or shards.
local boolean

If true, the request retrieves information from the local node only. Defaults to false, which means information is retrieved from the master node.
master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
timeout string

Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
wait_for_active_shards number | string

A number controlling to how many active shards to wait for, all to wait for all shards in the cluster to be active, or 0 to not wait.

Values are all or index-setting.
wait_for_events string

Can be one of immediate, urgent, high, normal, low, languid. Wait until all currently queued events with the given priority are processed.

Values are immediate, urgent, high, normal, low, or languid.
wait_for_nodes string | number

The request waits until the specified number N of nodes is available. It also accepts >=N, <=N, >N and <N. Alternatively, it is possible to use ge(N), le(N), gt(N) and lt(N) notation.
wait_for_no_initializing_shards boolean

A boolean value which controls whether to wait (until the timeout provided) for the cluster to have no shard initializations. Defaults to false, which means it will not wait for initializing shards.
wait_for_no_relocating_shards boolean

A boolean value which controls whether to wait (until the timeout provided) for the cluster to have no shard relocations. Defaults to false, which means it will not wait for relocating shards.
wait_for_status string
One of green, yellow or red. Will wait (until the timeout provided) until the status of the cluster changes to the one provided or better, i.e. green > yellow > red. By default, will not wait for any status.

Supported values include:
- green (or GREEN): All shards are assigned.
- yellow (or YELLOW): All primary shards are assigned, but one or more replica shards are unassigned. If a node in the cluster fails, some data could be unavailable until that node is repaired.
- red (or RED): One or more primary shards are unassigned, so some data is unavailable. This can occur briefly during cluster startup as primary shards are assigned.
- unknown
- unavailable
Values are green, GREEN, yellow, YELLOW, red, RED, unknown, or unavailable.

Responses

200 application/json
Hide response attributes Show response attributes object
- active_primary_shards number Required
  
  The number of active primary shards.
- active_shards number Required
  
  The total number of active primary and replica shards.
- active_shards_percent string
  
  The ratio of active shards in the cluster expressed as a string formatted percentage.
- active_shards_percent_as_number number Required
  
  The ratio of active shards in the cluster expressed as a percentage.
- cluster_name string Required
- delayed_unassigned_shards number Required
  
  The number of shards whose allocation has been delayed by the timeout settings.
- indices object
  
  Hide indices attribute Show indices attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  active_primary_shards number Required
  
  active_shards number Required
  
  initializing_shards number Required
  
  number_of_replicas number Required
  
  number_of_shards number Required
  
  relocating_shards number Required
  
  shards object
  
  Hide shards attribute Show shards attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  active_shards number Required
  
  initializing_shards number Required
  
  primary_active boolean Required
  
  relocating_shards number Required
  
  status string Required
  
  Values are green, GREEN, yellow, YELLOW, red, RED, unknown, or unavailable.
  
  unassigned_shards number Required
  
  unassigned_primary_shards number Required
  
  status string Required
  
  Values are green, GREEN, yellow, YELLOW, red, RED, unknown, or unavailable.
  
  unassigned_shards number Required
  
  unassigned_primary_shards number Required
- initializing_shards number Required
  
  The number of shards that are under initialization.
- number_of_data_nodes number Required
  
  The number of nodes that are dedicated data nodes.
- number_of_in_flight_fetch number Required
  
  The number of unfinished fetches.
- number_of_nodes number Required
  
  The number of nodes within the cluster.
- number_of_pending_tasks number Required
  
  The number of cluster-level changes that have not yet been executed.
- relocating_shards number Required
  
  The number of shards that are under relocation.
- status string Required
  
  Values are green, GREEN, yellow, YELLOW, red, RED, unknown, or unavailable.
- task_max_waiting_in_queue string
  
  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.
- task_max_waiting_in_queue_millis number
  
  Time unit for milliseconds
- timed_out boolean Required
  
  If false the response returned within the period of time that is specified by the timeout parameter (30s by default)
- unassigned_primary_shards number Required
  
  The number of primary shards that are not allocated.
- unassigned_shards number Required
  
  The number of shards that are not allocated.

GET /_cluster/health/{index}

GET _cluster/health

resp = client.cluster.health()

const response = await client.cluster.health();

response = client.cluster.health

$resp = $client->cluster()->health();

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cluster/health"

client.cluster().health(h -> h);

Response examples (200)

A successful response from `GET _cluster/health`. It is the health status of a quiet single node cluster with a single index with one shard and one replica.

{
  "cluster_name" : "testcluster",
  "status" : "yellow",
  "timed_out" : false,
  "number_of_nodes" : 1,
  "number_of_data_nodes" : 1,
  "active_primary_shards" : 1,
  "active_shards" : 1,
  "relocating_shards" : 0,
  "initializing_shards" : 0,
  "unassigned_shards" : 1,
  "delayed_unassigned_shards": 0,
  "number_of_pending_tasks" : 0,
  "number_of_in_flight_fetch": 0,
  "task_max_waiting_in_queue_millis": 0,
  "active_shards_percent_as_number": 50.0
}

Get the pending cluster tasks Generally available

GET /_cluster/pending_tasks

Api key auth Basic auth Bearer auth

Get information about cluster-level changes (such as create index, update mapping, allocate or fail shard) that have not yet taken effect.

NOTE: This API returns a list of any pending updates to the cluster state. These are distinct from the tasks reported by the task management API which include periodic tasks and tasks initiated by the user, such as node stats, search queries, or create index requests. However, if a user-initiated task such as a create index command causes a cluster state update, the activity of this task might be reported by both task api and pending cluster tasks API.

Required authorization

Cluster privileges: monitor

Query parameters

local boolean

If true, the request retrieves information from the local node only. If false, information is retrieved from the master node.
master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- tasks array[object] Required
  
  Hide tasks attributes Show tasks attributes object
  
  executing boolean Required
  
  Indicates whether the pending tasks are currently executing or not.
  
  insert_order number Required
  
  The number that represents when the task has been inserted into the task queue.
  
  priority string Required
  
  The priority of the pending task. The valid priorities in descending priority order are: IMMEDIATE > URGENT > HIGH > NORMAL > LOW > LANGUID.
  
  source string Required
  
  A general description of the cluster task that may include a reason and origin.
  
  time_in_queue string
  
  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.
  
  time_in_queue_millis number
  
  Time unit for milliseconds

GET /_cluster/pending_tasks

GET /_cluster/pending_tasks

resp = client.cluster.pending_tasks()

const response = await client.cluster.pendingTasks();

response = client.cluster.pending_tasks

$resp = $client->cluster()->pendingTasks();

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cluster/pending_tasks"

client.cluster().pendingTasks(p -> p);

Get the hot threads for nodes Generally available

GET /_nodes/{node_id}/hot_threads

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_nodes/hot_threads

GET /_nodes/{node_id}/hot_threads

Get a breakdown of the hot threads on each selected node in the cluster. The output is plain text with a breakdown of the top hot threads for each node.

Required authorization

Cluster privileges: monitor,manage

Path parameters

node_id string | array[string] Required

List of node IDs or names used to limit returned information.

Query parameters

ignore_idle_threads boolean

If true, known idle threads (e.g. waiting in a socket select, or to get a task from an empty queue) are filtered out.
interval string

The interval to do the second sampling of threads.

Values are -1 or 0.
snapshots number

Number of samples of thread stacktrace.
threads number

Specifies the number of hot threads to provide information for.
timeout string

Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
type string

The type to sample.

Values are cpu, wait, block, gpu, or mem.
sort string

The sort order for 'cpu' type (default: total)

Values are cpu, wait, block, gpu, or mem.

Responses

200 application/json

GET /_nodes/{node_id}/hot_threads

GET /_nodes/hot_threads

resp = client.nodes.hot_threads()

const response = await client.nodes.hotThreads();

response = client.nodes.hot_threads

$resp = $client->nodes()->hotThreads();

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_nodes/hot_threads"

client.nodes().hotThreads(h -> h);

Connector

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.

Check out the connector API tutorial

Delete a connector Beta; Added in 8.12.0

DELETE /_connector/{connector_id}

Api key auth Basic auth Bearer auth

Removes a connector and associated sync jobs. This is a destructive action that is not recoverable. NOTE: This action doesn’t delete any API keys, ingest pipelines, or data indices associated with the connector. These need to be removed manually.

Path parameters

connector_id string Required

The unique identifier of the connector to be deleted

Query parameters

delete_sync_jobs boolean

A flag indicating if associated sync jobs should be also removed. Defaults to false.
hard boolean

A flag indicating if the connector should be hard deleted.

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

DELETE /_connector/{connector_id}

DELETE _connector/my-connector-id&delete_sync_jobs=true

resp = client.connector.delete(
    connector_id="my-connector-id&delete_sync_jobs=true",
)

const response = await client.connector.delete({
  connector_id: "my-connector-id&delete_sync_jobs=true",
});

response = client.connector.delete(
  connector_id: "my-connector-id&delete_sync_jobs=true"
)

$resp = $client->connector()->delete([
    "connector_id" => "my-connector-id&delete_sync_jobs=true",
]);

curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/my-connector-id&delete_sync_jobs=true"

client.connector().delete(d -> d
    .connectorId("my-connector-id&delete_sync_jobs=true")
);

Response examples (200)

{
    "acknowledged": true
}

Create a connector Beta; Added in 8.12.0

POST /_connector

Api key auth Basic auth Bearer auth

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.

application/json

Body

description string
index_name string
is_native boolean
language string
name string
service_type string

Responses

200 application/json
Hide response attributes Show response attributes object
- result string Required
  
  Values are created, updated, deleted, not_found, or noop.
- id string Required

POST /_connector

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"}'

Set the connector sync job stats Technical preview

PUT /_connector/_sync_job/{connector_sync_job_id}/_stats

Api key auth Basic auth Bearer auth

Stats include: deleted_document_count, indexed_document_count, indexed_document_volume, and total_document_count. You can also update last_seen. This API is mainly used by the connector service for updating sync job information.

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.

Path parameters

connector_sync_job_id string Required

The unique identifier of the connector sync job.

application/json

Body Required

deleted_document_count number Required

The number of documents the sync job deleted.
indexed_document_count number Required

The number of documents the sync job indexed.
indexed_document_volume number Required

The total size of the data (in MiB) the sync job indexed.
last_seen string

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.
metadata object
Hide metadata attribute Show metadata attribute object
- * object Additional properties
total_document_count number

The total number of documents in the target index after the sync job finished.

Responses

200 application/json

PUT /_connector/_sync_job/{connector_sync_job_id}/_stats

PUT _connector/_sync_job/my-connector-sync-job/_stats
{
    "deleted_document_count": 10,
    "indexed_document_count": 20,
    "indexed_document_volume": 1000,
    "total_document_count": 2000,
    "last_seen": "2023-01-02T10:00:00Z"
}

resp = client.connector.sync_job_update_stats(
    connector_sync_job_id="my-connector-sync-job",
    deleted_document_count=10,
    indexed_document_count=20,
    indexed_document_volume=1000,
    total_document_count=2000,
    last_seen="2023-01-02T10:00:00Z",
)

const response = await client.connector.syncJobUpdateStats({
  connector_sync_job_id: "my-connector-sync-job",
  deleted_document_count: 10,
  indexed_document_count: 20,
  indexed_document_volume: 1000,
  total_document_count: 2000,
  last_seen: "2023-01-02T10:00:00Z",
});

response = client.connector.sync_job_update_stats(
  connector_sync_job_id: "my-connector-sync-job",
  body: {
    "deleted_document_count": 10,
    "indexed_document_count": 20,
    "indexed_document_volume": 1000,
    "total_document_count": 2000,
    "last_seen": "2023-01-02T10:00:00Z"
  }
)

$resp = $client->connector()->syncJobUpdateStats([
    "connector_sync_job_id" => "my-connector-sync-job",
    "body" => [
        "deleted_document_count" => 10,
        "indexed_document_count" => 20,
        "indexed_document_volume" => 1000,
        "total_document_count" => 2000,
        "last_seen" => "2023-01-02T10:00:00Z",
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"deleted_document_count":10,"indexed_document_count":20,"indexed_document_volume":1000,"total_document_count":2000,"last_seen":"2023-01-02T10:00:00Z"}' "$ELASTICSEARCH_URL/_connector/_sync_job/my-connector-sync-job/_stats"

client.connector().syncJobUpdateStats(s -> s
    .connectorSyncJobId("my-connector-sync-job")
    .deletedDocumentCount(10L)
    .indexedDocumentCount(20L)
    .indexedDocumentVolume(1000L)
    .lastSeen(l -> l
        .time("2023-01-02T10:00:00Z")
    )
    .totalDocumentCount(2000)
);

Request example

An example body for a `PUT _connector/_sync_job/my-connector-sync-job/_stats` request.

{
    "deleted_document_count": 10,
    "indexed_document_count": 20,
    "indexed_document_volume": 1000,
    "total_document_count": 2000,
    "last_seen": "2023-01-02T10:00:00Z"
}

Update the connector configuration Beta; Added in 8.12.0

PUT /_connector/{connector_id}/_configuration

Api key auth Basic auth Bearer auth

Update the configuration field in the connector document.

Path parameters

connector_id string Required

The unique identifier of the connector to be updated

application/json

Body Required

configuration object
Hide configuration attribute Show configuration attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  category string
  
  default_value number | string | boolean | null Required
  
  A scalar value.
  
  One of:
  number-1 number number-2 number string-3 string boolean-4 boolean string-5 string | null
  
  depends_on array[object] Required
  
  Hide depends_on attributes Show depends_on attributes object
  
  field string Required
  
  value number | string | boolean | null Required
  
  A scalar value.
  
  One of:
  number-1 number number-2 number string-3 string boolean-4 boolean string-5 string | null
  
  display string Required
  
  Values are textbox, textarea, numeric, toggle, or dropdown.
  
  label string Required
  
  options array[object] Required
  
  Hide options attributes Show options attributes object
  
  label string Required
  
  value number | string | boolean | null Required
  
  A scalar value.
  
  One of:
  number-1 number number-2 number string-3 string boolean-4 boolean string-5 string | null
  
  order number
  
  placeholder string
  
  required boolean Required
  
  sensitive boolean Required
  
  tooltip string | null
  
  One of:
  string-1 string string-2 string | null
  
  type string
  
  Values are str, int, list, or bool.
  
  ui_restrictions array[string]
  
  validations array[object]
  
  One of:
  LessThanValidation object GreaterThanValidation object ListTypeValidation object IncludedInValidation object RegexValidation object
  
  Hide attributes Show attributes
  
  type string Required Discriminator
  
  constraint number Required
  
  value object Required
values object
Hide values attribute Show values attribute object
- * object Additional properties

Responses

200 application/json
Hide response attribute Show response attribute object
- result string Required
  
  Values are created, updated, deleted, not_found, or noop.

PUT /_connector/{connector_id}/_configuration

PUT _connector/my-spo-connector/_configuration
{
    "values": {
        "tenant_id": "my-tenant-id",
        "tenant_name": "my-sharepoint-site",
        "client_id": "foo",
        "secret_value": "bar",
        "site_collections": "*"
    }
}

resp = client.connector.update_configuration(
    connector_id="my-spo-connector",
    values={
        "tenant_id": "my-tenant-id",
        "tenant_name": "my-sharepoint-site",
        "client_id": "foo",
        "secret_value": "bar",
        "site_collections": "*"
    },
)

const response = await client.connector.updateConfiguration({
  connector_id: "my-spo-connector",
  values: {
    tenant_id: "my-tenant-id",
    tenant_name: "my-sharepoint-site",
    client_id: "foo",
    secret_value: "bar",
    site_collections: "*",
  },
});

response = client.connector.update_configuration(
  connector_id: "my-spo-connector",
  body: {
    "values": {
      "tenant_id": "my-tenant-id",
      "tenant_name": "my-sharepoint-site",
      "client_id": "foo",
      "secret_value": "bar",
      "site_collections": "*"
    }
  }
)

$resp = $client->connector()->updateConfiguration([
    "connector_id" => "my-spo-connector",
    "body" => [
        "values" => [
            "tenant_id" => "my-tenant-id",
            "tenant_name" => "my-sharepoint-site",
            "client_id" => "foo",
            "secret_value" => "bar",
            "site_collections" => "*",
        ],
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"values":{"tenant_id":"my-tenant-id","tenant_name":"my-sharepoint-site","client_id":"foo","secret_value":"bar","site_collections":"*"}}' "$ELASTICSEARCH_URL/_connector/my-spo-connector/_configuration"

client.connector().updateConfiguration(u -> u
    .connectorId("my-spo-connector")
    .values(Map.of("tenant_id", JsonData.fromJson("\"my-tenant-id\""),"tenant_name", JsonData.fromJson("\"my-sharepoint-site\""),"secret_value", JsonData.fromJson("\"bar\""),"client_id", JsonData.fromJson("\"foo\""),"site_collections", JsonData.fromJson("\"*\"")))
);

Request examples

{
    "values": {
        "tenant_id": "my-tenant-id",
        "tenant_name": "my-sharepoint-site",
        "client_id": "foo",
        "secret_value": "bar",
        "site_collections": "*"
    }
}

{
    "values": {
        "secret_value": "foo-bar"
    }
}

Response examples (200)

{
  "result": "updated"
}

Update the connector error field Technical preview; Added in 8.12.0

PUT /_connector/{connector_id}/_error

Api key auth Basic auth Bearer auth

Set the error field for the connector. If the error provided in the request body is non-null, the connector’s status is updated to error. Otherwise, if the error is reset to null, the connector status is updated to connected.

Path parameters

connector_id string Required

The unique identifier of the connector to be updated

application/json

Body Required

error string | null Required

One of:
string-1 string NullValue string | null

Responses

200 application/json
Hide response attribute Show response attribute object
- result string Required
  
  Values are created, updated, deleted, not_found, or noop.

PUT /_connector/{connector_id}/_error

PUT _connector/my-connector/_error
{
    "error": "Houston, we have a problem!"
}

resp = client.connector.update_error(
    connector_id="my-connector",
    error="Houston, we have a problem!",
)

const response = await client.connector.updateError({
  connector_id: "my-connector",
  error: "Houston, we have a problem!",
});

response = client.connector.update_error(
  connector_id: "my-connector",
  body: {
    "error": "Houston, we have a problem!"
  }
)

$resp = $client->connector()->updateError([
    "connector_id" => "my-connector",
    "body" => [
        "error" => "Houston, we have a problem!",
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"error":"Houston, we have a problem!"}' "$ELASTICSEARCH_URL/_connector/my-connector/_error"

client.connector().updateError(u -> u
    .connectorId("my-connector")
    .error("Houston, we have a problem!")
);

Request example

{
    "error": "Houston, we have a problem!"
}

Response examples (200)

{
  "result": "updated"
}

Update the connector features Technical preview

PUT /_connector/{connector_id}/_features

Api key auth Basic auth Bearer auth

Update the connector features in the connector document. This API can be used to control the following aspects of a connector:

document-level security
incremental syncs
advanced sync rules
basic sync rules

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.

Path parameters

connector_id string Required

The unique identifier of the connector to be updated.

application/json

Body Required

features object Required
Hide features attributes Show features attributes object
- document_level_security object
  Hide document_level_security attribute Show document_level_security attribute object
  
  enabled boolean Required
- incremental_sync object
  Hide incremental_sync attribute Show incremental_sync attribute object
  
  enabled boolean Required
- native_connector_api_keys object
  Hide native_connector_api_keys attribute Show native_connector_api_keys attribute object
  
  enabled boolean Required
- sync_rules object
  Hide sync_rules attributes Show sync_rules attributes object
  
  advanced object
  
  Hide advanced attribute Show advanced attribute object
  
  enabled boolean Required
  
  basic object
  
  Hide basic attribute Show basic attribute object
  
  enabled boolean Required

Responses

200 application/json
Hide response attribute Show response attribute object
- result string Required
  
  Values are created, updated, deleted, not_found, or noop.

PUT /_connector/{connector_id}/_features

PUT _connector/my-connector/_features
{
  "features": {
    "document_level_security": {
      "enabled": true
    },
    "incremental_sync": {
      "enabled": true
    },
    "sync_rules": {
      "advanced": {
        "enabled": false
      },
      "basic": {
        "enabled": true
      }
    }
  }
}

resp = client.connector.update_features(
    connector_id="my-connector",
    features={
        "document_level_security": {
            "enabled": True
        },
        "incremental_sync": {
            "enabled": True
        },
        "sync_rules": {
            "advanced": {
                "enabled": False
            },
            "basic": {
                "enabled": True
            }
        }
    },
)

const response = await client.connector.updateFeatures({
  connector_id: "my-connector",
  features: {
    document_level_security: {
      enabled: true,
    },
    incremental_sync: {
      enabled: true,
    },
    sync_rules: {
      advanced: {
        enabled: false,
      },
      basic: {
        enabled: true,
      },
    },
  },
});

response = client.connector.update_features(
  connector_id: "my-connector",
  body: {
    "features": {
      "document_level_security": {
        "enabled": true
      },
      "incremental_sync": {
        "enabled": true
      },
      "sync_rules": {
        "advanced": {
          "enabled": false
        },
        "basic": {
          "enabled": true
        }
      }
    }
  }
)

$resp = $client->connector()->updateFeatures([
    "connector_id" => "my-connector",
    "body" => [
        "features" => [
            "document_level_security" => [
                "enabled" => true,
            ],
            "incremental_sync" => [
                "enabled" => true,
            ],
            "sync_rules" => [
                "advanced" => [
                    "enabled" => false,
                ],
                "basic" => [
                    "enabled" => true,
                ],
            ],
        ],
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"features":{"document_level_security":{"enabled":true},"incremental_sync":{"enabled":true},"sync_rules":{"advanced":{"enabled":false},"basic":{"enabled":true}}}}' "$ELASTICSEARCH_URL/_connector/my-connector/_features"

client.connector().updateFeatures(u -> u
    .connectorId("my-connector")
    .features(f -> f
        .documentLevelSecurity(d -> d
            .enabled(true)
        )
        .incrementalSync(i -> i
            .enabled(true)
        )
        .syncRules(s -> s
            .advanced(a -> a
                .enabled(false)
            )
            .basic(b -> b
                .enabled(true)
            )
        )
    )
);

Request examples

{
  "features": {
    "document_level_security": {
      "enabled": true
    },
    "incremental_sync": {
      "enabled": true
    },
    "sync_rules": {
      "advanced": {
        "enabled": false
      },
      "basic": {
        "enabled": true
      }
    }
  }
}

{
  "features": {
    "document_level_security": {
      "enabled": true
    }
  }
}

Response examples (200)

{
  "result": "updated"
}

Update the connector filtering Beta; Added in 8.12.0

PUT /_connector/{connector_id}/_filtering

Api key auth Basic auth Bearer auth

Update the draft filtering configuration of a connector and marks the draft validation state as edited. The filtering draft is activated once validated by the running Elastic connector service. The filtering property is used to configure sync rules (both basic and advanced) for a connector.

Path parameters

connector_id string Required

The unique identifier of the connector to be updated

application/json

Body Required

filtering array[object]
Hide filtering attributes Show filtering attributes object
- active object Required
  Hide active attributes Show active attributes object
  
  advanced_snippet object Required
  
  Hide advanced_snippet attributes Show advanced_snippet attributes object
  
  created_at string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  string-1 string UnitMillis number
  
  updated_at string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  string-1 string UnitMillis number
  
  value object Required
  
  rules array[object] Required
  
  Hide rules attributes Show rules attributes object
  
  created_at string
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  id string Required
  
  order number Required
  
  policy string Required
  
  Values are exclude or include.
  
  rule string Required
  
  Values are contains, ends_with, equals, regex, starts_with, >, or <.
  
  updated_at string
  
  value string Required
  
  validation object Required
  
  Hide validation attributes Show validation attributes object
  
  errors array[object] Required
  
  Hide errors attributes Show errors attributes object
  
  ids array[string] Required
  
  messages array[string] Required
  
  state string Required
  
  Values are edited, invalid, or valid.
- domain string
- draft object Required
  Hide draft attributes Show draft attributes object
  
  advanced_snippet object Required
  
  Hide advanced_snippet attributes Show advanced_snippet attributes object
  
  created_at string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  string-1 string UnitMillis number
  
  updated_at string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  string-1 string UnitMillis number
  
  value object Required
  
  rules array[object] Required
  
  Hide rules attributes Show rules attributes object
  
  created_at string
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  id string Required
  
  order number Required
  
  policy string Required
  
  Values are exclude or include.
  
  rule string Required
  
  Values are contains, ends_with, equals, regex, starts_with, >, or <.
  
  updated_at string
  
  value string Required
  
  validation object Required
  
  Hide validation attributes Show validation attributes object
  
  errors array[object] Required
  
  Hide errors attributes Show errors attributes object
  
  ids array[string] Required
  
  messages array[string] Required
  
  state string Required
  
  Values are edited, invalid, or valid.
rules array[object]
Hide rules attributes Show rules attributes object
- created_at string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  string-1 string UnitMillis number
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- id string Required
- order number Required
- policy string Required
  
  Values are exclude or include.
- rule string Required
  
  Values are contains, ends_with, equals, regex, starts_with, >, or <.
- updated_at string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  string-1 string UnitMillis number
- value string Required
advanced_snippet object
Hide advanced_snippet attributes Show advanced_snippet attributes object
- created_at string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  string-1 string UnitMillis number
- updated_at string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  string-1 string UnitMillis number
- value object Required

Responses

200 application/json
Hide response attribute Show response attribute object
- result string Required
  
  Values are created, updated, deleted, not_found, or noop.

PUT /_connector/{connector_id}/_filtering

PUT _connector/my-g-drive-connector/_filtering
{
    "rules": [
         {
            "field": "file_extension",
            "id": "exclude-txt-files",
            "order": 0,
            "policy": "exclude",
            "rule": "equals",
            "value": "txt"
        },
        {
            "field": "_",
            "id": "DEFAULT",
            "order": 1,
            "policy": "include",
            "rule": "regex",
            "value": ".*"
        }
    ]
}

resp = client.connector.update_filtering(
    connector_id="my-g-drive-connector",
    rules=[
        {
            "field": "file_extension",
            "id": "exclude-txt-files",
            "order": 0,
            "policy": "exclude",
            "rule": "equals",
            "value": "txt"
        },
        {
            "field": "_",
            "id": "DEFAULT",
            "order": 1,
            "policy": "include",
            "rule": "regex",
            "value": ".*"
        }
    ],
)

const response = await client.connector.updateFiltering({
  connector_id: "my-g-drive-connector",
  rules: [
    {
      field: "file_extension",
      id: "exclude-txt-files",
      order: 0,
      policy: "exclude",
      rule: "equals",
      value: "txt",
    },
    {
      field: "_",
      id: "DEFAULT",
      order: 1,
      policy: "include",
      rule: "regex",
      value: ".*",
    },
  ],
});

response = client.connector.update_filtering(
  connector_id: "my-g-drive-connector",
  body: {
    "rules": [
      {
        "field": "file_extension",
        "id": "exclude-txt-files",
        "order": 0,
        "policy": "exclude",
        "rule": "equals",
        "value": "txt"
      },
      {
        "field": "_",
        "id": "DEFAULT",
        "order": 1,
        "policy": "include",
        "rule": "regex",
        "value": ".*"
      }
    ]
  }
)

$resp = $client->connector()->updateFiltering([
    "connector_id" => "my-g-drive-connector",
    "body" => [
        "rules" => array(
            [
                "field" => "file_extension",
                "id" => "exclude-txt-files",
                "order" => 0,
                "policy" => "exclude",
                "rule" => "equals",
                "value" => "txt",
            ],
            [
                "field" => "_",
                "id" => "DEFAULT",
                "order" => 1,
                "policy" => "include",
                "rule" => "regex",
                "value" => ".*",
            ],
        ),
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"rules":[{"field":"file_extension","id":"exclude-txt-files","order":0,"policy":"exclude","rule":"equals","value":"txt"},{"field":"_","id":"DEFAULT","order":1,"policy":"include","rule":"regex","value":".*"}]}' "$ELASTICSEARCH_URL/_connector/my-g-drive-connector/_filtering"

client.connector().updateFiltering(u -> u
    .connectorId("my-g-drive-connector")
    .rules(List.of(FilteringRule.of(f -> f
            .field("file_extension")
            .id("exclude-txt-files")
            .order(0)
            .policy(FilteringPolicy.Exclude)
            .rule(FilteringRuleRule.Equals)
            .value("txt")),FilteringRule.of(f -> f
            .field("_")
            .id("DEFAULT")
            .order(1)
            .policy(FilteringPolicy.Include)
            .rule(FilteringRuleRule.Regex)
            .value(".*"))))
);

Request examples

{
    "rules": [
         {
            "field": "file_extension",
            "id": "exclude-txt-files",
            "order": 0,
            "policy": "exclude",
            "rule": "equals",
            "value": "txt"
        },
        {
            "field": "_",
            "id": "DEFAULT",
            "order": 1,
            "policy": "include",
            "rule": "regex",
            "value": ".*"
        }
    ]
}

{
    "advanced_snippet": {
        "value": [{
            "tables": [
                "users",
                "orders"
            ],
            "query": "SELECT users.id AS id, orders.order_id AS order_id FROM users JOIN orders ON users.id = orders.user_id"
        }]
    }
}

Response examples (200)

{
  "result": "updated"
}

Update the connector draft filtering validation Technical preview; Added in 8.12.0

PUT /_connector/{connector_id}/_filtering/_validation

Api key auth Basic auth Bearer auth

Update the draft filtering validation info for a connector.

Path parameters

connector_id string Required

The unique identifier of the connector to be updated

application/json

Body Required

validation object Required
Hide validation attributes Show validation attributes object
- errors array[object] Required
  Hide errors attributes Show errors attributes object
  
  ids array[string] Required
  
  messages array[string] Required
- state string Required
  
  Values are edited, invalid, or valid.

Responses

200 application/json
Hide response attribute Show response attribute object
- result string Required
  
  Values are created, updated, deleted, not_found, or noop.

PUT /_connector/{connector_id}/_filtering/_validation

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 connector index name Beta; Added in 8.12.0

PUT /_connector/{connector_id}/_index_name

Api key auth Basic auth Bearer auth

Update the index_name field of a connector, specifying the index where the data ingested by the connector is stored.

Path parameters

connector_id string Required

The unique identifier of the connector to be updated

application/json

Body Required

index_name string | null Required

One of:
IndexName string NullValue string | null

Responses

200 application/json
Hide response attribute Show response attribute object
- result string Required
  
  Values are created, updated, deleted, not_found, or noop.

PUT /_connector/{connector_id}/_index_name

PUT _connector/my-connector/_index_name
{
    "index_name": "data-from-my-google-drive"
}

resp = client.connector.update_index_name(
    connector_id="my-connector",
    index_name="data-from-my-google-drive",
)

const response = await client.connector.updateIndexName({
  connector_id: "my-connector",
  index_name: "data-from-my-google-drive",
});

response = client.connector.update_index_name(
  connector_id: "my-connector",
  body: {
    "index_name": "data-from-my-google-drive"
  }
)

$resp = $client->connector()->updateIndexName([
    "connector_id" => "my-connector",
    "body" => [
        "index_name" => "data-from-my-google-drive",
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"index_name":"data-from-my-google-drive"}' "$ELASTICSEARCH_URL/_connector/my-connector/_index_name"

client.connector().updateIndexName(u -> u
    .connectorId("my-connector")
    .indexName("data-from-my-google-drive")
);

Request example

{
    "index_name": "data-from-my-google-drive"
}

Response examples (200)

{
  "result": "updated"
}

Create a follower Generally available; Added in 6.5.0

PUT /{index}/_ccr/follow

Api key auth Basic auth Bearer auth

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.

Path parameters

index string Required

The name of the follower index.

Query parameters

master_timeout string

Period to wait for a connection to the master node.

Values are -1 or 0.
wait_for_active_shards number | string

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.

Values are all or index-setting.

application/json

Body Required

data_stream_name string

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.
leader_index string Required
max_outstanding_read_requests number

The maximum number of outstanding reads requests from the remote cluster.
max_outstanding_write_requests number

The maximum number of outstanding write requests on the follower.
max_read_request_operation_count number

The maximum number of operations to pull per read from the remote cluster.
max_read_request_size number | string

One of:
number-1 number string-2 string
max_retry_delay string

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.
max_write_buffer_count number

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.
max_write_buffer_size number | string

One of:
number-1 number string-2 string
max_write_request_operation_count number

The maximum number of operations per bulk write request executed on the follower.
max_write_request_size number | string

One of:
number-1 number string-2 string
read_poll_timeout string

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.
remote_cluster string Required

The remote cluster containing the leader index.
settings object
Index settings

Responses

200 application/json
Hide response attributes Show response attributes object
- follow_index_created boolean Required
- follow_index_shards_acked boolean Required
- index_following_started boolean Required

PUT /{index}/_ccr/follow

PUT /follower_index/_ccr/follow?wait_for_active_shards=1
{
  "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"
}

resp = client.ccr.follow(
    index="follower_index",
    wait_for_active_shards="1",
    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",
)

const response = await client.ccr.follow({
  index: "follower_index",
  wait_for_active_shards: 1,
  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",
});

response = client.ccr.follow(
  index: "follower_index",
  wait_for_active_shards: "1",
  body: {
    "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"
  }
)

$resp = $client->ccr()->follow([
    "index" => "follower_index",
    "wait_for_active_shards" => "1",
    "body" => [
        "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",
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"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"}' "$ELASTICSEARCH_URL/follower_index/_ccr/follow?wait_for_active_shards=1"

client.ccr().follow(f -> f
    .index("follower_index")
    .leaderIndex("leader_index")
    .maxOutstandingReadRequests(16L)
    .maxOutstandingWriteRequests(8)
    .maxReadRequestOperationCount(1024)
    .maxReadRequestSize("1024k")
    .maxRetryDelay(m -> m
        .time("10s")
    )
    .maxWriteBufferCount(512)
    .maxWriteBufferSize("512k")
    .maxWriteRequestOperationCount(32768)
    .maxWriteRequestSize("16k")
    .readPollTimeout(r -> r
        .time("30s")
    )
    .remoteCluster("remote_cluster")
    .settings(s -> s
        .otherSettings("index.number_of_replicas", JsonData.fromJson("0"))
    )
    .waitForActiveShards(w -> w
        .count(1)
    )
);

Request example

Run `PUT /follower_index/_ccr/follow?wait_for_active_shards=1` to create a follower index named `follower_index`.

{
  "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"
}

Response examples (200)

A successful response from `PUT /follower_index/_ccr/follow?wait_for_active_shards=1`.

{
  "follow_index_created" : true,
  "follow_index_shards_acked" : true,
  "index_following_started" : true
}

Get follower information Generally available; Added in 6.7.0

GET /{index}/_ccr/info

Api key auth Basic auth Bearer auth

Get information about all cross-cluster replication follower indices. For example, the results include follower index names, leader index names, replication options, and whether the follower indices are active or paused.

Required authorization

Cluster privileges: monitor

External documentation

Path parameters

index string | array[string] Required

A comma-delimited list of follower index patterns.

Query parameters

master_timeout string

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.

Values are -1 or 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- follower_indices array[object] Required
  
  Hide follower_indices attributes Show follower_indices attributes object
  
  follower_index string Required
  
  leader_index string Required
  
  parameters object
  
  Hide parameters attributes Show parameters attributes object
  
  max_outstanding_read_requests number
  
  The maximum number of outstanding reads requests from the remote cluster.
  
  max_outstanding_write_requests number
  
  The maximum number of outstanding write requests on the follower.
  
  max_read_request_operation_count number
  
  The maximum number of operations to pull per read from the remote cluster.
  
  max_read_request_size number | string
  
  One of:
  number-1 number string-2 string
  
  max_retry_delay string
  
  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.
  
  max_write_buffer_count number
  
  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.
  
  max_write_buffer_size number | string
  
  One of:
  number-1 number string-2 string
  
  max_write_request_operation_count number
  
  The maximum number of operations per bulk write request executed on the follower.
  
  max_write_request_size number | string
  
  One of:
  number-1 number string-2 string
  
  read_poll_timeout string
  
  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.
  
  remote_cluster string Required
  
  status string Required
  
  Values are active or paused.

GET /{index}/_ccr/info

GET /follower_index/_ccr/info

resp = client.ccr.follow_info(
    index="follower_index",
)

const response = await client.ccr.followInfo({
  index: "follower_index",
});

response = client.ccr.follow_info(
  index: "follower_index"
)

$resp = $client->ccr()->followInfo([
    "index" => "follower_index",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/follower_index/_ccr/info"

client.ccr().followInfo(f -> f
    .index("follower_index")
);

Response examples (200)

A successful response from `GET /follower_index/_ccr/info` when the follower index is active.

{
  "follower_indices": [
    {
      "follower_index": "follower_index",
      "remote_cluster": "remote_cluster",
      "leader_index": "leader_index",
      "status": "active",
      "parameters": {
        "max_read_request_operation_count": 5120,
        "max_read_request_size": "32mb",
        "max_outstanding_read_requests": 12,
        "max_write_request_operation_count": 5120,
        "max_write_request_size": "9223372036854775807b",
        "max_outstanding_write_requests": 9,
        "max_write_buffer_count": 2147483647,
        "max_write_buffer_size": "512mb",
        "max_retry_delay": "500ms",
        "read_poll_timeout": "1m"
      }
    }
  ]
}

A successful response from `GET /follower_index/_ccr/info` when the follower index is paused.

{
  "follower_indices": [
    {
      "follower_index": "follower_index",
      "remote_cluster": "remote_cluster",
      "leader_index": "leader_index",
      "status": "paused"
    }
  ]
}

Resume an auto-follow pattern Generally available; Added in 7.5.0

POST /_ccr/auto_follow/{name}/resume

Api key auth Basic auth Bearer auth

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.

Required authorization

Cluster privileges: manage_ccr

External documentation

Path parameters

name string Required

The name of the auto-follow pattern to resume.

Query parameters

master_timeout string

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.

Values are -1 or 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

POST /_ccr/auto_follow/{name}/resume

POST /_ccr/auto_follow/my_auto_follow_pattern/resume

resp = client.ccr.resume_auto_follow_pattern(
    name="my_auto_follow_pattern",
)

const response = await client.ccr.resumeAutoFollowPattern({
  name: "my_auto_follow_pattern",
});

response = client.ccr.resume_auto_follow_pattern(
  name: "my_auto_follow_pattern"
)

$resp = $client->ccr()->resumeAutoFollowPattern([
    "name" => "my_auto_follow_pattern",
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ccr/auto_follow/my_auto_follow_pattern/resume"

client.ccr().resumeAutoFollowPattern(r -> r
    .name("my_auto_follow_pattern")
);

Response examples (200)

A successful response `POST /_ccr/auto_follow/my_auto_follow_pattern/resume`, which resumes an auto-follow pattern.

{
  "acknowledged" : true
}

Create a data stream Generally available; Added in 7.9.0

PUT /_data_stream/{name}

Api key auth Basic auth Bearer auth

You must have a matching index template with data stream enabled.

Required authorization

Index privileges: create_index

Path parameters

name string Required

Name of the data stream, which must meet the following criteria: Lowercase only; Cannot include \, /, *, ?, ", <, >, |, ,, #, :, or a space character; Cannot start with -, _, +, or .ds-; Cannot be . or ..; Cannot be longer than 255 bytes. Multi-byte characters count towards this limit faster.

Query parameters

master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
timeout string

Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

PUT /_data_stream/{name}

PUT _data_stream/logs-foo-bar

resp = client.indices.create_data_stream(
    name="logs-foo-bar",
)

const response = await client.indices.createDataStream({
  name: "logs-foo-bar",
});

response = client.indices.create_data_stream(
  name: "logs-foo-bar"
)

$resp = $client->indices()->createDataStream([
    "name" => "logs-foo-bar",
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_data_stream/logs-foo-bar"

client.indices().createDataStream(c -> c
    .name("logs-foo-bar")
);

Get data stream stats Generally available; Added in 7.9.0

GET /_data_stream/{name}/_stats

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_data_stream/_stats

GET /_data_stream/{name}/_stats

Get statistics for one or more data streams.

Required authorization

Index privileges: monitor

Path parameters

name string Required

Comma-separated list of data streams used to limit the request. Wildcard expressions (*) are supported. To target all data streams in a cluster, omit this parameter or use *.

Query parameters

expand_wildcards string | array[string]
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.
Values are all, open, closed, hidden, or none.

Responses

200 application/json
Hide response attributes Show response attributes object
- _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  shard number Required
  
  status string
  
  skipped number
- backing_indices number Required
  
  Total number of backing indices for the selected data streams.
- data_stream_count number Required
  
  Total number of selected data streams.
- data_streams array[object] Required
  
  Contains statistics for the selected data streams.
  
  Hide data_streams attributes Show data_streams attributes object
  
  backing_indices number Required
  
  Current number of backing indices for the data stream.
  
  data_stream string Required
  
  maximum_timestamp number
  
  Time unit for milliseconds
  
  store_size number | string
  
  One of:
  number-1 number string-2 string
  
  store_size_bytes number Required
  
  Total size, in bytes, of all shards for the data stream’s backing indices.
- total_store_sizes number | string
  
  One of:
  number-1 number string-2 string
- total_store_size_bytes number Required
  
  Total size, in bytes, of all shards for the selected data streams.

GET /_data_stream/{name}/_stats

GET /_data_stream/my-index-000001/_stats

resp = client.indices.data_streams_stats(
    name="my-index-000001",
)

const response = await client.indices.dataStreamsStats({
  name: "my-index-000001",
});

response = client.indices.data_streams_stats(
  name: "my-index-000001"
)

$resp = $client->indices()->dataStreamsStats([
    "name" => "my-index-000001",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_data_stream/my-index-000001/_stats"

client.indices().dataStreamsStats(d -> d
    .name("my-index-000001")
);

Response examples (200)

A successful response for retrieving statistics for a data stream.

{
  "_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
    }
  ]
}

Get data stream lifecycles Generally available; Added in 8.11.0

GET /_data_stream/{name}/_lifecycle

Api key auth Basic auth Bearer auth

Get the data stream lifecycle configuration of one or more data streams.

External documentation

Path parameters

name string | array[string] Required

Comma-separated list of data streams to limit the request. Supports wildcards (*). To target all data streams, omit this parameter or use * or _all.

Query parameters

expand_wildcards string | array[string]
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.
Values are all, open, closed, hidden, or none.
include_defaults boolean

If true, return all default settings in the response.
master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- data_streams array[object] Required
  
  Hide data_streams attributes Show data_streams attributes object
  
  name string Required
  
  lifecycle object
  
  Data stream lifecycle with rollover can be used to display the configuration including the default rollover conditions, if asked.
  
  Hide lifecycle attributes Show lifecycle attributes object
  
  data_retention string
  
  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.
  
  downsampling object
  
  Hide downsampling attribute Show downsampling attribute object
  
  rounds array[object] Required
  
  The list of downsampling rounds to execute as part of this downsampling configuration
  
  enabled boolean
  
  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.
  
  Default value is true.
  
  rollover object
  
  Hide rollover attributes Show rollover attributes object
  
  min_age string
  
  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.
  
  max_age string
  
  min_docs number
  
  max_docs number
  
  min_size
  
  max_size
  
  min_primary_shard_size
  
  max_primary_shard_size
  
  min_primary_shard_docs number
  
  max_primary_shard_docs number

GET /_data_stream/{name}/_lifecycle

GET /_data_stream/{name}/_lifecycle?human&pretty

resp = client.indices.get_data_lifecycle(
    name="{name}",
    human=True,
    pretty=True,
)

const response = await client.indices.getDataLifecycle({
  name: "{name}",
  human: "true",
  pretty: "true",
});

response = client.indices.get_data_lifecycle(
  name: "{name}",
  human: "true",
  pretty: "true"
)

$resp = $client->indices()->getDataLifecycle([
    "name" => "{name}",
    "human" => "true",
    "pretty" => "true",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_data_stream/%7Bname%7D/_lifecycle?human&pretty"

Response examples (200)

A successful response from `GET /_data_stream/{name}/_lifecycle?human&pretty`.

{
  "data_streams": [
    {
      "name": "my-data-stream-1",
      "lifecycle": {
        "enabled": true,
        "data_retention": "7d"
      }
    },
    {
      "name": "my-data-stream-2",
      "lifecycle": {
        "enabled": true,
        "data_retention": "7d"
      }
    }
  ]
}

Update data stream lifecycles Generally available; Added in 8.11.0

PUT /_data_stream/{name}/_lifecycle

Api key auth Basic auth Bearer auth

Update the data stream lifecycle of the specified data streams.

External documentation

Path parameters

name string | array[string] Required

Comma-separated list of data streams used to limit the request. Supports wildcards (*). To target all data streams use * or _all.

Query parameters

expand_wildcards string | array[string]
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.
Values are all, open, closed, hidden, or none.
master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
timeout string

Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

application/json

Body

data_retention string

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.
downsampling object
Hide downsampling attribute Show downsampling attribute object
- rounds array[object] Required
  
  The list of downsampling rounds to execute as part of this downsampling configuration
  Hide rounds attributes Show rounds attributes object
  
  after string Required
  
  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.
  
  config object Required
  
  Hide config attribute Show config attribute object
  
  fixed_interval string Required
  
  A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)
enabled boolean

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.

Default value is true.

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

PUT /_data_stream/{name}/_lifecycle

PUT _data_stream/my-data-stream/_lifecycle
{
  "data_retention": "7d"
}

resp = client.indices.put_data_lifecycle(
    name="my-data-stream",
    data_retention="7d",
)

const response = await client.indices.putDataLifecycle({
  name: "my-data-stream",
  data_retention: "7d",
});

response = client.indices.put_data_lifecycle(
  name: "my-data-stream",
  body: {
    "data_retention": "7d"
  }
)

$resp = $client->indices()->putDataLifecycle([
    "name" => "my-data-stream",
    "body" => [
        "data_retention" => "7d",
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"data_retention":"7d"}' "$ELASTICSEARCH_URL/_data_stream/my-data-stream/_lifecycle"

client.indices().putDataLifecycle(p -> p
    .dataRetention(d -> d
        .time("7d")
    )
    .name("my-data-stream")
);

Request examples

{
  "data_retention": "7d"
}

This example configures two downsampling rounds.

{
    "downsampling": [
      {
        "after": "1d",
        "fixed_interval": "10m"
      },
      {
        "after": "7d",
        "fixed_interval": "1d"
      }
    ]
}

Response examples (200)

A successful response for configuring a data stream lifecycle.

{
  "acknowledged": true
}

Get data stream options Generally available; Added in 8.19.0

GET /_data_stream/{name}/_options

Api key auth Basic auth Bearer auth

Get the data stream options configuration of one or more data streams.

Path parameters

name string | array[string] Required

Comma-separated list of data streams to limit the request. Supports wildcards (*). To target all data streams, omit this parameter or use * or _all.

Query parameters

expand_wildcards string | array[string]
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.
Values are all, open, closed, hidden, or none.
master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- data_streams array[object] Required
  
  Hide data_streams attributes Show data_streams attributes object
  
  name string Required
  
  options object
  
  Data stream options contain the configuration of data stream level features for a given data stream, for example, the failure store configuration.
  
  Hide options attribute Show options attribute object
  
  failure_store object
  
  Data stream failure store contains the configuration of the failure store for a given data stream.
  
  Hide failure_store attributes Show failure_store attributes object
  
  enabled boolean
  
  If defined, it turns the failure store on/off (true/false) for this data stream. A data stream failure store that's disabled (enabled: false) will redirect no new failed indices to the failure store; however, it will not remove any existing data from the failure store.
  
  Default value is true.
  
  lifecycle object
  
  The failure store lifecycle configures the data stream lifecycle configuration for failure indices.
  
  Hide lifecycle attributes Show lifecycle attributes object
  
  data_retention string
  
  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.
  
  enabled boolean
  
  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.
  
  Default value is true.

GET /_data_stream/{name}/_options

curl \
 --request GET 'http://api.example.com/_data_stream/{name}/_options' \
 --header "Authorization: $API_KEY"

Downsample an index Technical preview; Added in 8.5.0

POST /{index}/_downsample/{target_index}

Api key auth Basic auth Bearer auth

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).

Path parameters

index string Required

Name of the time series index to downsample.
target_index string Required

Name of the index to create.

application/json

Body Required

fixed_interval string Required

A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)

Responses

200 application/json

POST /{index}/_downsample/{target_index}

POST /my-time-series-index/_downsample/my-downsampled-time-series-index
{
  "fixed_interval": "1d"
}

resp = client.indices.downsample(
    index="my-time-series-index",
    target_index="my-downsampled-time-series-index",
    config={
        "fixed_interval": "1d"
    },
)

const response = await client.indices.downsample({
  index: "my-time-series-index",
  target_index: "my-downsampled-time-series-index",
  config: {
    fixed_interval: "1d",
  },
});

response = client.indices.downsample(
  index: "my-time-series-index",
  target_index: "my-downsampled-time-series-index",
  body: {
    "fixed_interval": "1d"
  }
)

$resp = $client->indices()->downsample([
    "index" => "my-time-series-index",
    "target_index" => "my-downsampled-time-series-index",
    "body" => [
        "fixed_interval" => "1d",
    ],
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"fixed_interval":"1d"}' "$ELASTICSEARCH_URL/my-time-series-index/_downsample/my-downsampled-time-series-index"

client.indices().downsample(d -> d
    .index("my-time-series-index")
    .targetIndex("my-downsampled-time-series-index")
    .config(c -> c
        .fixedInterval(f -> f
            .time("1d")
        )
    )
);

Request example

{
  "fixed_interval": "1d"
}

Get the status for a data stream lifecycle Generally available; Added in 8.11.0

GET /{index}/_lifecycle/explain

Api key auth Basic auth Bearer auth

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.

External documentation

Path parameters

index string | array[string] Required

The name of the index to explain

Query parameters

include_defaults boolean

indicates if the API should return the default values the system uses for the index's lifecycle
master_timeout string

Specify timeout for connection to master

Values are -1 or 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- indices object Required
  
  Hide indices attribute Show indices attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  index string Required
  
  managed_by_lifecycle boolean Required
  
  index_creation_date_millis number
  
  Time unit for milliseconds
  
  time_since_index_creation string
  
  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.
  
  rollover_date_millis number
  
  Time unit for milliseconds
  
  time_since_rollover string
  
  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.
  
  lifecycle object
  
  Data stream lifecycle with rollover can be used to display the configuration including the default rollover conditions, if asked.
  
  Hide lifecycle attributes Show lifecycle attributes object
  
  data_retention string
  
  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.
  
  downsampling object
  
  Hide downsampling attribute Show downsampling attribute object
  
  rounds array[object] Required
  
  The list of downsampling rounds to execute as part of this downsampling configuration
  
  enabled boolean
  
  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.
  
  Default value is true.
  
  rollover object
  
  Hide rollover attributes Show rollover attributes object
  
  min_age string
  
  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.
  
  max_age string
  
  min_docs number
  
  max_docs number
  
  min_size
  
  max_size
  
  min_primary_shard_size
  
  max_primary_shard_size
  
  min_primary_shard_docs number
  
  max_primary_shard_docs number
  
  generation_time string
  
  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.
  
  error string

GET /{index}/_lifecycle/explain

GET .ds-metrics-2023.03.22-000001/_lifecycle/explain

resp = client.indices.explain_data_lifecycle(
    index=".ds-metrics-2023.03.22-000001",
)

const response = await client.indices.explainDataLifecycle({
  index: ".ds-metrics-2023.03.22-000001",
});

response = client.indices.explain_data_lifecycle(
  index: ".ds-metrics-2023.03.22-000001"
)

$resp = $client->indices()->explainDataLifecycle([
    "index" => ".ds-metrics-2023.03.22-000001",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/.ds-metrics-2023.03.22-000001/_lifecycle/explain"

client.indices().explainDataLifecycle(e -> e
    .index(".ds-metrics-2023.03.22-000001")
);

Response examples (200)

A successful response from `GET .ds-metrics-2023.03.22-000001/_lifecycle/explain`, which retrieves the lifecycle status for a data stream backing index. If the index is managed by a data stream lifecycle, the API will show the `managed_by_lifecycle` field set to `true` and the rest of the response will contain information about the lifecycle execution status for this index.

{
  "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"
  }
}

The API reports any errors related to the lifecycle execution for the target index.

{
  "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 data stream settings Generally available; Added in 9.1.0

GET /_data_stream/{name}/_settings

Api key auth Basic auth Bearer auth

Get setting information for one or more data streams.

Required authorization

Index privileges: view_index_metadata

Path parameters

name string | array[string] Required

A comma-separated list of data streams or data stream patterns. Supports wildcards (*).

Query parameters

master_timeout string

The period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- data_streams array[object] Required
  
  Hide data_streams attributes Show data_streams attributes object
  
  name string Required
  
  The name of the data stream.
  
  settings object Required
  Index settings
  
  effective_settings object Required
  Index settings

GET /_data_stream/{name}/_settings

GET /_data_stream/my-data-stream/_settings

resp = client.indices.get_data_stream_settings(
    name="my-data-stream",
)

const response = await client.indices.getDataStreamSettings({
  name: "my-data-stream",
});

response = client.indices.get_data_stream_settings(
  name: "my-data-stream"
)

$resp = $client->indices()->getDataStreamSettings([
    "name" => "my-data-stream",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_data_stream/my-data-stream/_settings"

Response examples (200)

This is a response to `GET /_data_stream/my-data-stream/_settings` where my-data-stream that has two settings set. The `effective_settings` field shows additional settings that are pulled from its template.

{
  "data_streams": [
    {
      "name": "my-data-stream",
      "settings": {
        "index": {
          "lifecycle": {
            "name": "new-test-policy"
          },
          "number_of_shards": "11"
        }
      },
      "effective_settings": {
        "index": {
          "lifecycle": {
            "name": "new-test-policy"
          },
          "mode": "standard",
          "number_of_shards": "11",
          "number_of_replicas": "0"
        }
      }
    }
  ]
}

Promote a data stream Generally available; Added in 7.9.0

POST /_data_stream/_promote/{name}

Api key auth Basic auth Bearer auth

Promote a data stream from a replicated data stream managed by cross-cluster replication (CCR) to a regular data stream.

With CCR auto following, a data stream from a remote cluster can be replicated to the local cluster. These data streams can't be rolled over in the local cluster. These replicated data streams roll over only if the upstream data stream rolls over. In the event that the remote cluster is no longer available, the data stream in the local cluster can be promoted to a regular data stream, which allows these data streams to be rolled over in the local cluster.

NOTE: When promoting a data stream, ensure the local cluster has a data stream enabled index template that matches the data stream. If this is missing, the data stream will not be able to roll over until a matching index template is created. This will affect the lifecycle management of the data stream and interfere with the data stream size and retention.

Path parameters

name string Required

The name of the data stream

Query parameters

master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

Responses

200 application/json

POST /_data_stream/_promote/{name}

POST /_data_stream/_promote/my-data-stream

resp = client.indices.promote_data_stream(
    name="my-data-stream",
)

const response = await client.indices.promoteDataStream({
  name: "my-data-stream",
});

response = client.indices.promote_data_stream(
  name: "my-data-stream"
)

$resp = $client->indices()->promoteDataStream([
    "name" => "my-data-stream",
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_data_stream/_promote/my-data-stream"

client.indices().promoteDataStream(p -> p
    .name("my-data-stream")
);

Bulk index or delete documents Generally available

PUT /{index}/_bulk

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

POST /_bulk

PUT /_bulk

POST /{index}/_bulk

PUT /{index}/_bulk

Perform multiple index, create, delete, and update actions in a single request. This reduces overhead and can greatly increase indexing speed.

If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:

To use the create action, you must have the create_doc, create, index, or write index privilege. Data streams support only the create action.
To use the index action, you must have the create, index, or write index privilege.
To use the delete action, you must have the delete or write index privilege.
To use the update action, you must have the index or write index privilege.
To automatically create a data stream or index with a bulk API request, you must have the auto_configure, create_index, or manage index privilege.
To make the result of a bulk operation visible to search using the refresh parameter, you must have the maintenance or manage index privilege.

Automatic data stream creation requires a matching index template with data stream enabled.

The actions are specified in the request body using a newline delimited JSON (NDJSON) structure:

action_and_meta_data\n
optional_source\n
action_and_meta_data\n
optional_source\n
....
action_and_meta_data\n
optional_source\n

The index and create actions expect a source on the next line and have the same semantics as the op_type parameter in the standard index API. A create action fails if a document with the same ID already exists in the target An index action adds or replaces a document as necessary.

NOTE: Data streams support only the create action. To update or delete a document in a data stream, you must target the backing index containing the document.

An update action expects that the partial doc, upsert, and script and its options are specified on the next line.

A delete action does not expect a source on the next line and has the same semantics as the standard delete API.

NOTE: The final line of data must end with a newline character (\n). Each newline character may be preceded by a carriage return (\r). When sending NDJSON data to the _bulk endpoint, use a Content-Type header of application/json or application/x-ndjson. Because this format uses literal newline characters (\n) as delimiters, make sure that the JSON actions and sources are not pretty printed.

If you provide a target in the request path, it is used for any actions that don't explicitly specify an _index argument.

A note on the format: the idea here is to make processing as fast as possible. As some of the actions are redirected to other shards on other nodes, only action_meta_data is parsed on the receiving node side.

Client libraries using this protocol should try and strive to do something similar on the client side, and reduce buffering as much as possible.

There is no "correct" number of actions to perform in a single bulk request. Experiment with different settings to find the optimal size for your particular workload. Note that Elasticsearch limits the maximum size of a HTTP request to 100mb by default so clients must ensure that no request exceeds this size. It is not possible to index a single document that exceeds the size limit, so you must pre-process any such documents into smaller pieces before sending them to Elasticsearch. For instance, split documents into pages or chapters before indexing them, or store raw binary data in a system outside Elasticsearch and replace the raw data with a link to the external system in the documents that you send to Elasticsearch.

Client suppport for bulk requests

Some of the officially supported clients provide helpers to assist with bulk requests and reindexing:

Go: Check out esutil.BulkIndexer
Perl: Check out Search::Elasticsearch::Client::5_0::Bulk and Search::Elasticsearch::Client::5_0::Scroll
Python: Check out elasticsearch.helpers.*
JavaScript: Check out client.helpers.*
.NET: Check out BulkAllObservable
PHP: Check out bulk indexing.

Submitting bulk requests with cURL

If you're providing text file input to curl, you must use the --data-binary flag instead of plain -d. The latter doesn't preserve newlines. For example:

$ cat requests
{ "index" : { "_index" : "test", "_id" : "1" } }
{ "field1" : "value1" }
$ curl -s -H "Content-Type: application/x-ndjson" -XPOST localhost:9200/_bulk --data-binary "@requests"; echo
{"took":7, "errors": false, "items":[{"index":{"_index":"test","_id":"1","_version":1,"result":"created","forced_refresh":false}}]}

Optimistic concurrency control

Each index and delete action within a bulk API call may include the if_seq_no and if_primary_term parameters in their respective action and meta data lines. The if_seq_no and if_primary_term parameters control how operations are run, based on the last modification to existing documents. See Optimistic concurrency control for more details.

Versioning

Each bulk item can include the version value using the version field. It automatically follows the behavior of the index or delete operation based on the _version mapping. It also support the version_type.

Routing

Each bulk item can include the routing value using the routing field. It automatically follows the behavior of the index or delete operation based on the _routing mapping.

NOTE: Data streams do not support custom routing unless they were created with the allow_custom_routing setting enabled in the template.

Wait for active shards

When making bulk calls, you can set the wait_for_active_shards parameter to require a minimum number of shard copies to be active before starting to process the bulk request.

Refresh

Control when the changes made by this request are visible to search.

NOTE: Only the shards that receive the bulk request will be affected by refresh. Imagine a _bulk?refresh=wait_for request with three documents in it that happen to be routed to different shards in an index with five shards. The request will only wait for those three shards to refresh. The other two shards that make up the index do not participate in the _bulk request at all.

You might want to disable the refresh interval temporarily to improve indexing throughput for large bulk requests. Refer to the linked documentation for step-by-step instructions using the index settings API.

External documentation

Path parameters

index string Required

The name of the data stream, index, or index alias to perform bulk actions on.

Query parameters

include_source_on_error boolean

True or false if to include the document source in the error message in case of parsing errors.
list_executed_pipelines boolean

If true, the response will include the ingest pipelines that were run for each index or create.
pipeline string

The pipeline identifier to use to preprocess incoming documents. If the index has a default ingest pipeline specified, setting the value to _none turns off the default ingest pipeline for this request. If a final pipeline is configured, it will always run regardless of the value of this parameter.
refresh string

If true, Elasticsearch refreshes the affected shards to make this operation visible to search. If wait_for, wait for a refresh to make this operation visible to search. If false, do nothing with refreshes. Valid values: true, false, wait_for.

Values are true, false, or wait_for.
routing string

A custom value that is used to route operations to a specific shard.
_source boolean | string | array[string]

Indicates whether to return the _source field (true or false) or contains a list of fields to return.
_source_excludes string | array[string]

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. If the _source parameter is false, this parameter is ignored.
_source_includes string | array[string]

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.
timeout string

The period each action waits for the following operations: automatic index creation, dynamic mapping updates, and waiting for active shards. The default is 1m (one minute), which guarantees Elasticsearch waits for at least the timeout before failing. The actual wait time could be longer, particularly when multiple waits occur.

Values are -1 or 0.
wait_for_active_shards number | string

The number of shard copies 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 is 1, which waits for each primary shard to be active.

Values are all or index-setting.
require_alias boolean

If true, the request's actions must target an index alias.
require_data_stream boolean

If true, the request's actions must target a data stream (existing or to be created).

application/json

Body object Required

index object
Hide index attributes Show index attributes object
- _id string
- _index string
- routing string
- if_primary_term number
- if_seq_no number
- version number
- version_type string
  
  Values are internal, external, external_gte, or force.
- dynamic_templates object
  
  A map from the full name of fields to the name of dynamic templates. It defaults to an empty map. If a name matches a dynamic template, that template will be applied regardless of other match predicates defined in the template. If a field is already defined in the mapping, then this parameter won't be used.
  Hide dynamic_templates attribute Show dynamic_templates attribute object
  
  * string Additional properties
- pipeline string
  
  The ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, setting the value to _none turns off the default ingest pipeline for this request. If a final pipeline is configured, it will always run regardless of the value of this parameter.
- require_alias boolean
  
  If true, the request's actions must target an index alias.
  
  Default value is false.
create object
Hide create attributes Show create attributes object
- _id string
- _index string
- routing string
- if_primary_term number
- if_seq_no number
- version number
- version_type string
  
  Values are internal, external, external_gte, or force.
- dynamic_templates object
  
  A map from the full name of fields to the name of dynamic templates. It defaults to an empty map. If a name matches a dynamic template, that template will be applied regardless of other match predicates defined in the template. If a field is already defined in the mapping, then this parameter won't be used.
  Hide dynamic_templates attribute Show dynamic_templates attribute object
  
  * string Additional properties
- pipeline string
  
  The ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, setting the value to _none turns off the default ingest pipeline for this request. If a final pipeline is configured, it will always run regardless of the value of this parameter.
- require_alias boolean
  
  If true, the request's actions must target an index alias.
  
  Default value is false.
update object
Hide update attributes Show update attributes object
- _id string
- _index string
- routing string
- if_primary_term number
- if_seq_no number
- version number
- version_type string
  
  Values are internal, external, external_gte, or force.
- require_alias boolean
  
  If true, the request's actions must target an index alias.
  
  Default value is false.
- retry_on_conflict number
  
  The number of times an update should be retried in the case of a version conflict.
delete object
Hide delete attributes Show delete attributes object
- _id string
- _index string
- routing string
- if_primary_term number
- if_seq_no number
- version number
- version_type string
  
  Values are internal, external, external_gte, or force.

detect_noop boolean

If true, the result in the response is set to 'noop' when no changes to the document occur.

Default value is true.
doc object

A partial update to an existing document.
doc_as_upsert boolean

Set to true to use the contents of doc as the value of upsert.

Default value is false.
script object
Hide script attributes Show script attributes object
- source string | object
  
  One of:
  string-1 string SearchRequestBody object
  
  Hide attributes Show attributes
  
  aggregations object
  
  Defines the aggregations that are run as part of the search request.
  
  External documentation
  
  collapse object
  External documentation
  
  explain boolean
  
  If true, the request returns detailed information about score computation as part of a hit.
  
  Default value is false.
  
  ext object
  
  Configuration of search extensions defined by Elasticsearch plugins.
  
  Hide ext attribute Show ext attribute object
  
  * object Additional properties
  
  from number
  
  The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
  
  Default value is 0.
  
  highlight object
  
  track_total_hits boolean | number
  
  Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
  
  indices_boost array[object]
  
  Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.
  
  External documentation
  
  docvalue_fields array[object]
  
  An array of wildcard (*) field patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.
  
  A reference to a field with formatting instructions on how to return the value
  
  External documentation
  
  A reference to a field with formatting instructions on how to return the value
  
  knn object | array[object]
  
  The approximate kNN search to run.
  
  One of:
  KnnSearch object array-2 array[object]
  
  rank object
  
  Hide rank attribute Show rank attribute object
  
  rrf
  
  min_score number
  
  The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
  
  post_filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  profile boolean
  
  Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.
  
  Default value is false.
  
  query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  rescore array[object]
  
  retriever object
  
  Hide retriever attributes Show retriever attributes object
  
  standard
  
  knn
  
  rrf
  
  text_similarity_reranker
  
  rule
  
  rescorer
  
  linear
  
  pinned
  
  script_fields object
  
  Retrieve a script evaluation (based on different fields) for each hit.
  
  Hide script_fields attribute Show script_fields attribute object
  
  * object Additional properties
  
  search_after array[number | string | boolean | null]
  
  A field value.
  
  size number
  
  The number of hits to return, which must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after property.
  
  Default value is 10.
  
  slice object
  
  Hide slice attributes Show slice attributes object
  
  field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  id string Required
  
  max number Required
  
  sort array[string | object]
  
  _source boolean | object
  
  Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
  
  One of:
  boolean-1 boolean SourceFilter object
  
  fields array[object]
  
  An array of wildcard (*) field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
  
  A reference to a field with formatting instructions on how to return the value
  
  A reference to a field with formatting instructions on how to return the value
  
  suggest object
  
  Hide suggest attribute Show suggest attribute object
  
  text string
  
  Global suggest text, to avoid repetition when the same text is used in several suggesters
  
  terminate_after number
  
  The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.
  
  IMPORTANT: Use with caution. Elasticsearch applies this property to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this property for requests that target data streams with backing indices across multiple data tiers.
  
  If set to 0 (default), the query does not terminate early.
  
  Default value is 0.
  
  timeout string
  
  The period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.
  
  track_scores boolean
  
  If true, calculate and return document scores, even if the scores are not used for sorting.
  
  Default value is false.
  
  version boolean
  
  If true, the request returns the document version as part of a hit.
  
  Default value is false.
  
  seq_no_primary_term boolean
  
  If true, the request returns sequence number and primary term of the last modification of each hit.
  
  External documentation
  
  stored_fields string | array[string]
  
  pit object
  
  Hide pit attributes Show pit attributes object
  
  id string Required
  
  keep_alive string
  
  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.
  
  runtime_mappings object
  
  Hide runtime_mappings attribute Show runtime_mappings attribute object
  
  * object Additional properties
  
  stats array[string]
  
  The stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.
- id string
- params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  Hide params attribute Show params attribute object
  
  * object Additional properties
- lang string
  
  Any of:
  string-1 string string-2 string
  
  Values are painless, expression, mustache, or java.
- options object
  Hide options attribute Show options attribute object
  
  * string Additional properties
scripted_upsert boolean

Set to true to run the script whether or not the document exists.

Default value is false.
_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
One of:
boolean-1 boolean SourceFilter object
Hide attributes Show attributes

exclude_vectors boolean

If true, vector fields are excluded from the returned source.

This option takes precedence over includes: any vector field will remain excluded even if it matches an includes rule.

excludes string | array[string]

includes string | array[string]
upsert object

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.

Responses

200 application/json
Hide response attributes Show response attributes object
- errors boolean Required
  
  If true, one or more of the operations in the bulk request did not complete successfully.
- items array[object] Required
  
  The result of each operation in the bulk request, in the order they were submitted.
  
  Hide items attribute Show items attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  _id string | null
  
  The document ID associated with the operation.
  
  One of:
  string-1 string string-2 string | null
  
  _index string Required
  
  The name of the index associated with the operation. If the operation targeted a data stream, this is the backing index into which the document was written.
  
  status number Required
  
  The HTTP status code returned for the operation.
  
  failure_store string
  
  Values are not_applicable_or_unknown, used, not_enabled, or failed.
  
  error object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide error attributes Show error attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  _primary_term number
  
  The primary term assigned to the document for the operation. This property is returned only for successful operations.
  
  result string
  
  The result of the operation. Successful values are created, deleted, and updated.
  
  _seq_no number
  
  _shards object
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  skipped number
  
  _version number
  
  forced_refresh boolean
  
  get object
  
  Hide get attributes Show get attributes object
  
  fields object
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  found boolean Required
  
  _seq_no number
  
  _primary_term number
  
  _routing string
  
  _source object
  
  Hide _source attribute Show _source attribute object
  
  * object Additional properties
- took number Required
  
  The length of time, in milliseconds, it took to process the bulk request.
- ingest_took number

PUT /{index}/_bulk

POST _bulk
{ "index" : { "_index" : "test", "_id" : "1" } }
{ "field1" : "value1" }
{ "delete" : { "_index" : "test", "_id" : "2" } }
{ "create" : { "_index" : "test", "_id" : "3" } }
{ "field1" : "value3" }
{ "update" : {"_id" : "1", "_index" : "test"} }
{ "doc" : {"field2" : "value2"} }

resp = client.bulk(
    operations=[
        {
            "index": {
                "_index": "test",
                "_id": "1"
            }
        },
        {
            "field1": "value1"
        },
        {
            "delete": {
                "_index": "test",
                "_id": "2"
            }
        },
        {
            "create": {
                "_index": "test",
                "_id": "3"
            }
        },
        {
            "field1": "value3"
        },
        {
            "update": {
                "_id": "1",
                "_index": "test"
            }
        },
        {
            "doc": {
                "field2": "value2"
            }
        }
    ],
)

const response = await client.bulk({
  operations: [
    {
      index: {
        _index: "test",
        _id: "1",
      },
    },
    {
      field1: "value1",
    },
    {
      delete: {
        _index: "test",
        _id: "2",
      },
    },
    {
      create: {
        _index: "test",
        _id: "3",
      },
    },
    {
      field1: "value3",
    },
    {
      update: {
        _id: "1",
        _index: "test",
      },
    },
    {
      doc: {
        field2: "value2",
      },
    },
  ],
});

response = client.bulk(
  body: [
    {
      "index": {
        "_index": "test",
        "_id": "1"
      }
    },
    {
      "field1": "value1"
    },
    {
      "delete": {
        "_index": "test",
        "_id": "2"
      }
    },
    {
      "create": {
        "_index": "test",
        "_id": "3"
      }
    },
    {
      "field1": "value3"
    },
    {
      "update": {
        "_id": "1",
        "_index": "test"
      }
    },
    {
      "doc": {
        "field2": "value2"
      }
    }
  ]
)

$resp = $client->bulk([
    "body" => array(
        [
            "index" => [
                "_index" => "test",
                "_id" => "1",
            ],
        ],
        [
            "field1" => "value1",
        ],
        [
            "delete" => [
                "_index" => "test",
                "_id" => "2",
            ],
        ],
        [
            "create" => [
                "_index" => "test",
                "_id" => "3",
            ],
        ],
        [
            "field1" => "value3",
        ],
        [
            "update" => [
                "_id" => "1",
                "_index" => "test",
            ],
        ],
        [
            "doc" => [
                "field2" => "value2",
            ],
        ],
    ),
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '[{"index":{"_index":"test","_id":"1"}},{"field1":"value1"},{"delete":{"_index":"test","_id":"2"}},{"create":{"_index":"test","_id":"3"}},{"field1":"value3"},{"update":{"_id":"1","_index":"test"}},{"doc":{"field2":"value2"}}]' "$ELASTICSEARCH_URL/_bulk"

Request examples

Run `POST _bulk` to perform multiple operations.

{ "index" : { "_index" : "test", "_id" : "1" } }
{ "field1" : "value1" }
{ "delete" : { "_index" : "test", "_id" : "2" } }
{ "create" : { "_index" : "test", "_id" : "3" } }
{ "field1" : "value3" }
{ "update" : {"_id" : "1", "_index" : "test"} }
{ "doc" : {"field2" : "value2"} }

When you run `POST _bulk` and use the `update` action, you can use `retry_on_conflict` as a field in the action itself (not in the extra payload line) to specify how many times an update should be retried in the case of a version conflict.

{ "update" : {"_id" : "1", "_index" : "index1", "retry_on_conflict" : 3} }
{ "doc" : {"field" : "value"} }
{ "update" : { "_id" : "0", "_index" : "index1", "retry_on_conflict" : 3} }
{ "script" : { "source": "ctx._source.counter += params.param1", "lang" : "painless", "params" : {"param1" : 1}}, "upsert" : {"counter" : 1}}
{ "update" : {"_id" : "2", "_index" : "index1", "retry_on_conflict" : 3} }
{ "doc" : {"field" : "value"}, "doc_as_upsert" : true }
{ "update" : {"_id" : "3", "_index" : "index1", "_source" : true} }
{ "doc" : {"field" : "value"} }
{ "update" : {"_id" : "4", "_index" : "index1"} }
{ "doc" : {"field" : "value"}, "_source": true}

To return only information about failed operations, run `POST /_bulk?filter_path=items.*.error`.

{ "update": {"_id": "5", "_index": "index1"} }
{ "doc": {"my_field": "foo"} }
{ "update": {"_id": "6", "_index": "index1"} }
{ "doc": {"my_field": "foo"} }
{ "create": {"_id": "7", "_index": "index1"} }
{ "my_field": "foo" }

Run `POST /_bulk` to perform a bulk request that consists of index and create actions with the `dynamic_templates` parameter. The bulk request creates two new fields `work_location` and `home_location` with type `geo_point` according to the `dynamic_templates` parameter. However, the `raw_location` field is created using default dynamic mapping rules, as a text field in that case since it is supplied as a string in the JSON document.

{ "index" : { "_index" : "my_index", "_id" : "1", "dynamic_templates": {"work_location": "geo_point"}} }
{ "field" : "value1", "work_location": "41.12,-71.34", "raw_location": "41.12,-71.34"}
{ "create" : { "_index" : "my_index", "_id" : "2", "dynamic_templates": {"home_location": "geo_point"}} }
{ "field" : "value2", "home_location": "41.12,-71.34"}

Response examples (200)

{
   "took": 30,
   "errors": false,
   "items": [
      {
         "index": {
            "_index": "test",
            "_id": "1",
            "_version": 1,
            "result": "created",
            "_shards": {
               "total": 2,
               "successful": 1,
               "failed": 0
            },
            "status": 201,
            "_seq_no" : 0,
            "_primary_term": 1
         }
      },
      {
         "delete": {
            "_index": "test",
            "_id": "2",
            "_version": 1,
            "result": "not_found",
            "_shards": {
               "total": 2,
               "successful": 1,
               "failed": 0
            },
            "status": 404,
            "_seq_no" : 1,
            "_primary_term" : 2
         }
      },
      {
         "create": {
            "_index": "test",
            "_id": "3",
            "_version": 1,
            "result": "created",
            "_shards": {
               "total": 2,
               "successful": 1,
               "failed": 0
            },
            "status": 201,
            "_seq_no" : 2,
            "_primary_term" : 3
         }
      },
      {
         "update": {
            "_index": "test",
            "_id": "1",
            "_version": 2,
            "result": "updated",
            "_shards": {
                "total": 2,
                "successful": 1,
                "failed": 0
            },
            "status": 200,
            "_seq_no" : 3,
            "_primary_term" : 4
         }
      }
   ]
}

If you run `POST /_bulk` with operations that update non-existent documents, the operations cannot complete successfully. The API returns a response with an `errors` property value `true`. The response also includes an error object for any failed operations. The error object contains additional information about the failure, such as the error type and reason.

{
  "took": 486,
  "errors": true,
  "items": [
    {
      "update": {
        "_index": "index1",
        "_id": "5",
        "status": 404,
        "error": {
          "type": "document_missing_exception",
          "reason": "[5]: document missing",
          "index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
          "shard": "0",
          "index": "index1"
        }
      }
    },
    {
      "update": {
        "_index": "index1",
        "_id": "6",
        "status": 404,
        "error": {
          "type": "document_missing_exception",
          "reason": "[6]: document missing",
          "index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
          "shard": "0",
          "index": "index1"
        }
      }
    },
    {
      "create": {
        "_index": "index1",
        "_id": "7",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 2,
          "successful": 1,
          "failed": 0
        },
        "_seq_no": 0,
        "_primary_term": 1,
        "status": 201
      }
    }
  ]
}

An example response from `POST /_bulk?filter_path=items.*.error`, which returns only information about failed operations.

{
  "items": [
    {
      "update": {
        "error": {
          "type": "document_missing_exception",
          "reason": "[5]: document missing",
          "index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
          "shard": "0",
          "index": "index1"
        }
      }
    },
    {
      "update": {
        "error": {
          "type": "document_missing_exception",
          "reason": "[6]: document missing",
          "index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
          "shard": "0",
          "index": "index1"
        }
      }
    }
  ]
}

Get multiple documents Generally available; Added in 1.3.0

POST /{index}/_mget

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_mget

POST /_mget

GET /{index}/_mget

POST /{index}/_mget

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.

Required authorization

Index privileges: read

Path parameters

index string Required

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.

Query parameters

preference string

Specifies the node or shard the operation should be performed on. Random by default.
realtime boolean

If true, the request is real-time as opposed to near-real-time.
refresh boolean

If true, the request refreshes relevant shards before retrieving documents.
routing string

Custom value used to route operations to a specific shard.
_source boolean | string | array[string]

True or false to return the _source field or not, or a list of fields to return.
_source_excludes string | array[string]

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.
_source_includes string | array[string]

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.
stored_fields string | array[string]

If true, retrieves the document fields stored in the index rather than the document _source.

application/json

Body Required

docs array[object]

The documents you want to retrieve. Required if no index is specified in the request URI.
Hide docs attributes Show docs attributes object
- _id string Required
- _index string
- routing string
- _source boolean | object
  
  Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
  
  One of:
  boolean-1 boolean SourceFilter object
  
  Hide attributes Show attributes
  
  exclude_vectors boolean
  
  If true, vector fields are excluded from the returned source.
  
  This option takes precedence over includes: any vector field will remain excluded even if it matches an includes rule.
  
  excludes string | array[string]
  
  includes string | array[string]
- stored_fields string | array[string]
- version number
- version_type string
  
  Values are internal, external, external_gte, or force.
ids string | array[string]

One of:
Id string array-2 array[string]

Responses

200 application/json
Hide response attribute Show response attribute object
- docs array[object] Required
  
  The response includes a docs array that contains the documents in the order specified in the request. The structure of the returned documents is similar to that returned by the get API. If there is a failure getting a particular document, the error is included in place of the document.
  
  One of:
  GetResult object MultiGetError object
  
  Hide attributes Show attributes
  
  _index string Required
  
  fields object
  
  If the stored_fields parameter is set to true and found is true, it contains the document fields stored in the index.
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  _ignored array[string]
  
  found boolean Required
  
  Indicates whether the document exists.
  
  _id string Required
  
  _primary_term number
  
  The primary term assigned to the document for the indexing operation.
  
  _routing string
  
  The explicit routing, if set.
  
  _seq_no number
  
  _source object
  
  If found is true, it contains the document data formatted in JSON. If the _source parameter is set to false or the stored_fields parameter is set to true, it is excluded.
  
  _version number
  
  Hide attributes Show attributes
  
  error object Required
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide error attributes Show error attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  _id string Required
  
  _index string Required

POST /{index}/_mget

GET /my-index-000001/_mget
{
  "docs": [
    {
      "_id": "1"
    },
    {
      "_id": "2"
    }
  ]
}

resp = client.mget(
    index="my-index-000001",
    docs=[
        {
            "_id": "1"
        },
        {
            "_id": "2"
        }
    ],
)

const response = await client.mget({
  index: "my-index-000001",
  docs: [
    {
      _id: "1",
    },
    {
      _id: "2",
    },
  ],
});

response = client.mget(
  index: "my-index-000001",
  body: {
    "docs": [
      {
        "_id": "1"
      },
      {
        "_id": "2"
      }
    ]
  }
)

$resp = $client->mget([
    "index" => "my-index-000001",
    "body" => [
        "docs" => array(
            [
                "_id" => "1",
            ],
            [
                "_id" => "2",
            ],
        ),
    ],
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"docs":[{"_id":"1"},{"_id":"2"}]}' "$ELASTICSEARCH_URL/my-index-000001/_mget"

client.mget(m -> m
    .docs(List.of(MultiGetOperation.of(mu -> mu
            .id("1")),MultiGetOperation.of(mu -> mu
            .id("2"))))
    .index("my-index-000001")
);

Request examples

Run `GET /my-index-000001/_mget`. When you specify an index in the request URI, only the document IDs are required in the request body.

{
  "docs": [
    {
      "_id": "1"
    },
    {
      "_id": "2"
    }
  ]
}

Run `GET /_mget`. This request sets `_source` to `false` for document 1 to exclude the source entirely. It retrieves `field3` and `field4` from document 2. It retrieves the `user` field from document 3 but filters out the `user.location` field.

{
  "docs": [
    {
      "_index": "test",
      "_id": "1",
      "_source": false
    },
    {
      "_index": "test",
      "_id": "2",
      "_source": [ "field3", "field4" ]
    },
    {
      "_index": "test",
      "_id": "3",
      "_source": {
        "include": [ "user" ],
        "exclude": [ "user.location" ]
      }
    }
  ]
}

Run `GET /_mget`. This request retrieves `field1` and `field2` from document 1 and `field3` and `field4` from document 2.

{
  "docs": [
    {
      "_index": "test",
      "_id": "1",
      "stored_fields": [ "field1", "field2" ]
    },
    {
      "_index": "test",
      "_id": "2",
      "stored_fields": [ "field3", "field4" ]
    }
  ]
}

Run `GET /_mget?routing=key1`. If routing is used during indexing, you need to specify the routing value to retrieve documents. This request fetches `test/_doc/2` from the shard corresponding to routing key `key1`. It fetches `test/_doc/1` from the shard corresponding to routing key `key2`.

{
  "docs": [
    {
      "_index": "test",
      "_id": "1",
      "routing": "key2"
    },
    {
      "_index": "test",
      "_id": "2"
    }
  ]
}

Get multiple term vectors Generally available

POST /{index}/_mtermvectors

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_mtermvectors

POST /_mtermvectors

GET /{index}/_mtermvectors

POST /{index}/_mtermvectors

Get multiple term vectors with a single request. You can specify existing documents by index and ID or provide artificial documents in the body of the request. You can specify the index in the request body or request URI. The response contains a docs array with all the fetched termvectors. Each element has the structure provided by the termvectors API.

Artificial documents

You can also use mtermvectors to generate term vectors for artificial documents provided in the body of the request. The mapping used is determined by the specified _index.

Required authorization

Index privileges: read

Path parameters

index string Required

The name of the index that contains the documents.

Query parameters

ids array[string]

A comma-separated list of documents ids. You must define ids as parameter or set "ids" or "docs" in the request body
fields string | array[string]

A comma-separated list or wildcard expressions of fields to include in the statistics. It is used as the default list unless a specific field list is provided in the completion_fields or fielddata_fields parameters.
field_statistics boolean

If true, the response includes the document count, sum of document frequencies, and sum of total term frequencies.
offsets boolean

If true, the response includes term offsets.
payloads boolean

If true, the response includes term payloads.
positions boolean

If true, the response includes term positions.
preference string

The node or shard the operation should be performed on. It is random by default.
realtime boolean

If true, the request is real-time as opposed to near-real-time.
routing string

A custom value used to route operations to a specific shard.
term_statistics boolean

If true, the response includes term frequency and document frequency.
version number

If true, returns the document version as part of a hit.
version_type string
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.

application/json

Body

docs array[object]

An array of existing or artificial documents.
Hide docs attributes Show docs attributes object
- _id string
- _index string
- doc object
  
  An artificial document (a document not present in the index) for which you want to retrieve term vectors.
- fields string | array[string]
- field_statistics boolean
  
  If true, the response includes the document count, sum of document frequencies, and sum of total term frequencies.
  
  Default value is true.
- filter object
  Hide filter attributes Show filter attributes object
  
  max_doc_freq number
  
  Ignore words which occur in more than this many docs. Defaults to unbounded.
  
  max_num_terms number
  
  The maximum number of terms that must be returned per field.
  
  Default value is 25.
  
  max_term_freq number
  
  Ignore words with more than this frequency in the source doc. It defaults to unbounded.
  
  max_word_length number
  
  The maximum word length above which words will be ignored. Defaults to unbounded.
  
  Default value is 0.
  
  min_doc_freq number
  
  Ignore terms which do not occur in at least this many docs.
  
  Default value is 1.
  
  min_term_freq number
  
  Ignore words with less than this frequency in the source doc.
  
  Default value is 1.
  
  min_word_length number
  
  The minimum word length below which words will be ignored.
  
  Default value is 0.
- offsets boolean
  
  If true, the response includes term offsets.
  
  Default value is true.
- payloads boolean
  
  If true, the response includes term payloads.
  
  Default value is true.
- positions boolean
  
  If true, the response includes term positions.
  
  Default value is true.
- routing string
- term_statistics boolean
  
  If true, the response includes term frequency and document frequency.
  
  Default value is false.
- version number
- version_type string
  
  Values are internal, external, external_gte, or force.
ids array[string]

A simplified syntax to specify documents by their ID if they're in the same index.

Responses

200 application/json
Hide response attribute Show response attribute object
- docs array[object] Required
  
  Hide docs attributes Show docs attributes object
  
  _id string
  
  _index string Required
  
  _version number
  
  took number
  
  found boolean
  
  term_vectors object
  
  Hide term_vectors attribute Show term_vectors attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  field_statistics object
  
  Hide field_statistics attributes Show field_statistics attributes object
  
  doc_count number Required
  
  sum_doc_freq number Required
  
  sum_ttf number Required
  
  terms object Required
  
  Hide terms attribute Show terms attribute object
  
  * object Additional properties
  
  error object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide error attributes Show error attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

POST /{index}/_mtermvectors

POST /my-index-000001/_mtermvectors
{
  "docs": [
      {
        "_id": "2",
        "fields": [
            "message"
        ],
        "term_statistics": true
      },
      {
        "_id": "1"
      }
  ]
}

resp = client.mtermvectors(
    index="my-index-000001",
    docs=[
        {
            "_id": "2",
            "fields": [
                "message"
            ],
            "term_statistics": True
        },
        {
            "_id": "1"
        }
    ],
)

const response = await client.mtermvectors({
  index: "my-index-000001",
  docs: [
    {
      _id: "2",
      fields: ["message"],
      term_statistics: true,
    },
    {
      _id: "1",
    },
  ],
});

response = client.mtermvectors(
  index: "my-index-000001",
  body: {
    "docs": [
      {
        "_id": "2",
        "fields": [
          "message"
        ],
        "term_statistics": true
      },
      {
        "_id": "1"
      }
    ]
  }
)

$resp = $client->mtermvectors([
    "index" => "my-index-000001",
    "body" => [
        "docs" => array(
            [
                "_id" => "2",
                "fields" => array(
                    "message",
                ),
                "term_statistics" => true,
            ],
            [
                "_id" => "1",
            ],
        ),
    ],
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"docs":[{"_id":"2","fields":["message"],"term_statistics":true},{"_id":"1"}]}' "$ELASTICSEARCH_URL/my-index-000001/_mtermvectors"

client.mtermvectors(m -> m
    .docs(List.of(MultiTermVectorsOperation.of(mu -> mu
            .id("2")
            .fields("message")
            .termStatistics(true)),MultiTermVectorsOperation.of(mu -> mu
            .id("1"))))
    .index("my-index-000001")
);

Request examples

Run `POST /my-index-000001/_mtermvectors`. When you specify an index in the request URI, the index does not need to be specified for each documents in the request body.

{
  "docs": [
      {
        "_id": "2",
        "fields": [
            "message"
        ],
        "term_statistics": true
      },
      {
        "_id": "1"
      }
  ]
}

Run `POST /my-index-000001/_mtermvectors`. If all requested documents are in same index and the parameters are the same, you can use a simplified syntax.

{
  "ids": [ "1", "2" ],
  "fields": [
    "message"
  ],
  "term_statistics": true
}

Run `POST /_mtermvectors` to generate term vectors for artificial documents provided in the body of the request. The mapping used is determined by the specified `_index`.

{
  "docs": [
      {
        "_index": "my-index-000001",
        "doc" : {
            "message" : "test test test"
        }
      },
      {
        "_index": "my-index-000001",
        "doc" : {
          "message" : "Another test ..."
        }
      }
  ]
}

Get an enrich policy Generally available; Added in 7.5.0

GET /_enrich/policy/{name}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_enrich/policy

GET /_enrich/policy/{name}

Returns information about an enrich policy.

Path parameters

name string | array[string] Required

Comma-separated list of enrich policy names used to limit the request. To return information for all enrich policies, omit this parameter.

Query parameters

master_timeout string

Period to wait for a connection to the master node.

Values are -1 or 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- policies array[object] Required
  
  Hide policies attribute Show policies attribute object
  
  config object Required
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  enrich_fields string | array[string] Required
  
  indices string | array[string] Required
  
  match_field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  name string
  
  elasticsearch_version string

GET /_enrich/policy/{name}

GET /_enrich/policy/my-policy

resp = client.enrich.get_policy(
    name="my-policy",
)

const response = await client.enrich.getPolicy({
  name: "my-policy",
});

response = client.enrich.get_policy(
  name: "my-policy"
)

$resp = $client->enrich()->getPolicy([
    "name" => "my-policy",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_enrich/policy/my-policy"

client.enrich().getPolicy(g -> g
    .name("my-policy")
);

Create an enrich policy Generally available; Added in 7.5.0

PUT /_enrich/policy/{name}

Api key auth Basic auth Bearer auth

Creates an enrich policy.

Path parameters

name string Required

Name of the enrich policy to create or update.

Query parameters

master_timeout string

Period to wait for a connection to the master node.

Values are -1 or 0.

application/json

Body Required

geo_match object Additional properties
Hide geo_match attributes Show geo_match attributes object
- enrich_fields string | array[string] Required
- indices string | array[string] Required
- match_field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
- name string
- elasticsearch_version string
match object Additional properties
Hide match attributes Show match attributes object
- enrich_fields string | array[string] Required
- indices string | array[string] Required
- match_field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
- name string
- elasticsearch_version string
range object Additional properties
Hide range attributes Show range attributes object
- enrich_fields string | array[string] Required
- indices string | array[string] Required
- match_field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
- name string
- elasticsearch_version string

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

PUT /_enrich/policy/{name}

PUT /_enrich/policy/postal_policy
{
  "geo_match": {
    "indices": "postal_codes",
    "match_field": "location",
    "enrich_fields": [ "location", "postal_code" ]
  }
}

resp = client.enrich.put_policy(
    name="postal_policy",
    geo_match={
        "indices": "postal_codes",
        "match_field": "location",
        "enrich_fields": [
            "location",
            "postal_code"
        ]
    },
)

const response = await client.enrich.putPolicy({
  name: "postal_policy",
  geo_match: {
    indices: "postal_codes",
    match_field: "location",
    enrich_fields: ["location", "postal_code"],
  },
});

response = client.enrich.put_policy(
  name: "postal_policy",
  body: {
    "geo_match": {
      "indices": "postal_codes",
      "match_field": "location",
      "enrich_fields": [
        "location",
        "postal_code"
      ]
    }
  }
)

$resp = $client->enrich()->putPolicy([
    "name" => "postal_policy",
    "body" => [
        "geo_match" => [
            "indices" => "postal_codes",
            "match_field" => "location",
            "enrich_fields" => array(
                "location",
                "postal_code",
            ),
        ],
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"geo_match":{"indices":"postal_codes","match_field":"location","enrich_fields":["location","postal_code"]}}' "$ELASTICSEARCH_URL/_enrich/policy/postal_policy"

client.enrich().putPolicy(p -> p
    .geoMatch(g -> g
        .enrichFields(List.of("location","postal_code"))
        .indices("postal_codes")
        .matchField("location")
    )
    .name("postal_policy")
);

Request example

An example body for a `PUT /_enrich/policy/postal_policy` request.

{
  "geo_match": {
    "indices": "postal_codes",
    "match_field": "location",
    "enrich_fields": [ "location", "postal_code" ]
  }
}

Run an enrich policy Generally available; Added in 7.5.0

PUT /_enrich/policy/{name}/_execute

Api key auth Basic auth Bearer auth

Create the enrich index for an existing enrich policy.

Path parameters

name string Required

Enrich policy to execute.

Query parameters

master_timeout string

Period to wait for a connection to the master node.

Values are -1 or 0.
wait_for_completion boolean

If true, the request blocks other enrich policy execution requests until complete.

Responses

200 application/json
Hide response attributes Show response attributes object
- status object
  
  Hide status attributes Show status attributes object
  
  phase string Required
  
  Values are SCHEDULED, RUNNING, COMPLETE, FAILED, or CANCELLED.
  
  step string
- task string

PUT /_enrich/policy/{name}/_execute

PUT /_enrich/policy/my-policy/_execute?wait_for_completion=false

resp = client.enrich.execute_policy(
    name="my-policy",
    wait_for_completion=False,
)

const response = await client.enrich.executePolicy({
  name: "my-policy",
  wait_for_completion: "false",
});

response = client.enrich.execute_policy(
  name: "my-policy",
  wait_for_completion: "false"
)

$resp = $client->enrich()->executePolicy([
    "name" => "my-policy",
    "wait_for_completion" => "false",
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_enrich/policy/my-policy/_execute?wait_for_completion=false"

client.enrich().executePolicy(e -> e
    .name("my-policy")
    .waitForCompletion(false)
);

Delete an async EQL search Generally available; Added in 7.9.0

DELETE /_eql/search/{id}

Api key auth Basic auth Bearer auth

Delete an async EQL search or a stored synchronous EQL search. The API also deletes results for the search.

Path parameters

id string Required

Identifier for the search to delete. A search ID is provided in the EQL search API's response for an async search. A search ID is also provided if the request’s keep_on_completion parameter is true.

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

DELETE /_eql/search/{id}

DELETE /_eql/search/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=

resp = client.eql.delete(
    id="FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
)

const response = await client.eql.delete({
  id: "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
});

response = client.eql.delete(
  id: "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE="
)

$resp = $client->eql()->delete([
    "id" => "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
]);

curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_eql/search/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE="

client.eql().delete(d -> d
    .id("FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=")
);

Get the async EQL status Generally available; Added in 7.9.0

GET /_eql/search/status/{id}

Api key auth Basic auth Bearer auth

Get the current status for an async EQL search or a stored synchronous EQL search without returning results.

Path parameters

id string Required

Identifier for the search.

Responses

200 application/json
Hide response attributes Show response attributes object
- id string Required
- is_partial boolean Required
  
  If true, the search request is still executing. If false, the search is completed.
- is_running boolean Required
  
  If true, the response does not contain complete search results. This could be because either the search is still running (is_running status is false), or because it is already completed (is_running status is true) and results are partial due to failures or timeouts.
- start_time_in_millis number
  
  Time unit for milliseconds
- expiration_time_in_millis number
  
  Time unit for milliseconds
- completion_status number
  
  For a completed search shows the http status code of the completed search.

GET /_eql/search/status/{id}

GET /_eql/search/status/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=

resp = client.eql.get_status(
    id="FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
)

const response = await client.eql.getStatus({
  id: "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
});

response = client.eql.get_status(
  id: "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE="
)

$resp = $client->eql()->getStatus([
    "id" => "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_eql/search/status/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE="

client.eql().getStatus(g -> g
    .id("FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=")
);

Response examples (200)

A successful response for getting status information for an async EQL search.

{
  "id": "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
  "is_running" : true,
  "is_partial" : true,
  "start_time_in_millis" : 1611690235000,
  "expiration_time_in_millis" : 1611690295000
}

Get async ES|QL query results Generally available; Added in 8.13.0

GET /_query/async/{id}

Api key auth Basic auth Bearer auth

Get the current status and available results or stored results for an ES|QL asynchronous query. If the Elasticsearch security features are enabled, only the user who first submitted the ES|QL query can retrieve the results using this API.

External documentation

Path parameters

id string Required

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.

Query parameters

drop_null_columns boolean

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.
format string

A short version of the Accept header, for example json or yaml.

Values are csv, json, tsv, txt, yaml, cbor, smile, or arrow.
keep_alive string

The period for which the query and its results are stored in the cluster. When this period expires, the query and its results are deleted, even if the query is still ongoing.

Values are -1 or 0.
wait_for_completion_timeout string

The period to wait for the request to finish. By default, the request waits for complete query results. If the request completes during the period specified in this parameter, complete query results are returned. Otherwise, the response returns an is_running value of true and no results.

Values are -1 or 0.

Responses

200 application/json
Hide response attributes Show response attributes object
- Time unit for milliseconds
- is_partial boolean
- all_columns array[object]
  
  Hide all_columns attributes Show all_columns attributes object
  
  name string Required
  
  type string Required
- columns array[object] Required
  
  Hide columns attributes Show columns attributes object
  
  name string Required
  
  type string Required
- values array[array] Required
  
  A field value.
  
  A field value.
- _clusters object
  
  Hide _clusters attributes Show _clusters attributes object
  
  total number Required
  
  successful number Required
  
  running number Required
  
  skipped number Required
  
  partial number Required
  
  failed number Required
  
  details object Required
  
  Hide details attribute Show details attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  status string Required
  
  Values are running, successful, partial, skipped, or failed.
  
  indices string Required
  
  Time unit for milliseconds
  
  _shards object
  
  Hide _shards attributes Show _shards attributes object
  
  total number Required
  
  successful number
  
  skipped number
  
  failed number
  
  failures array[object]
- profile object
  
  Profiling information. Present if profile was true in the request. The contents of this field are currently unstable.
- id string
- is_running boolean Required

GET /_query/async/{id}

GET /_query/async/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=?wait_for_completion_timeout=30s

resp = client.esql.async_query_get(
    id="FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
    wait_for_completion_timeout="30s",
)

const response = await client.esql.asyncQueryGet({
  id: "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
  wait_for_completion_timeout: "30s",
});

response = client.esql.async_query_get(
  id: "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
  wait_for_completion_timeout: "30s"
)

$resp = $client->esql()->asyncQueryGet([
    "id" => "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
    "wait_for_completion_timeout" => "30s",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_query/async/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=?wait_for_completion_timeout=30s"

Get the features Generally available; Added in 7.12.0

GET /_features

Api key auth Basic auth Bearer auth

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.

External documentation

Query parameters

master_timeout string

Period to wait for a connection to the master node.

Values are -1 or 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- features array[object] Required
  
  Hide features attributes Show features attributes object
  
  name string Required
  
  description string Required

GET /_features

GET _features

resp = client.features.get_features()

const response = await client.features.getFeatures();

response = client.features.get_features

$resp = $client->features()->getFeatures();

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_features"

client.features().getFeatures(g -> g);

Response examples (200)

A successful response for retrieving a list of feature states that can be included when taking a snapshot.

{
  "features": [
    {
      "name": "tasks",
      "description": "Manages task results"
    },
    {
      "name": "kibana",
      "description": "Manages Kibana configuration and reports"
    }
  ]
}

Get component templates Generally available; Added in 7.8.0

GET /_component_template/{name}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_component_template

GET /_component_template/{name}

Get information about component templates.

Required authorization

Cluster privileges: manage_index_templates

Path parameters

name string Required

Comma-separated list of component template names used to limit the request. Wildcard (*) expressions are supported.

Query parameters

flat_settings boolean

If true, returns settings in flat format.
settings_filter string | array[string]

Filter out results, for example to filter out sensitive information. Supports wildcards or full settings keys
include_defaults boolean Generally available; Added in 8.11.0

Return all default configurations for the component template (default: false)
local boolean

If true, the request retrieves information from the local node only. If false, information is retrieved from the master node.
master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- component_templates array[object] Required
  
  Hide component_templates attributes Show component_templates attributes object
  
  name string Required
  
  component_template object Required
  
  Hide component_template attributes Show component_template attributes object
  
  template object Required
  
  Hide template attributes Show template attributes object
  
  _meta object
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
  
  version number
  
  settings object
  
  Hide settings attribute Show settings attribute object
  
  * object
  
  mappings object
  
  Hide mappings attributes Show mappings attributes object
  
  all_field object
  
  date_detection boolean
  
  dynamic string
  
  Values are strict, runtime, true, or false.
  
  dynamic_date_formats array[string]
  
  dynamic_templates array[object]
  
  _field_names object
  
  index_field object
  
  _meta object
  
  numeric_detection boolean
  
  properties object
  
  _routing object
  
  _size object
  
  _source object
  
  runtime object
  
  enabled boolean
  
  subobjects string
  
  Values are true or false.
  
  _data_stream_timestamp object
  
  aliases object
  
  Hide aliases attribute Show aliases attribute object
  
  * object Additional properties
  
  lifecycle object
  
  data_stream_options object | string | null
  
  One of:
  DataStreamOptionsTemplate object string-2 string | null
  
  Data stream options template contains the same information as DataStreamOptions but allows them to be set explicitly to null.
  
  version number
  
  _meta object
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
  
  deprecated boolean

GET /_component_template/{name}

GET /_component_template/template_1

resp = client.cluster.get_component_template(
    name="template_1",
)

const response = await client.cluster.getComponentTemplate({
  name: "template_1",
});

response = client.cluster.get_component_template(
  name: "template_1"
)

$resp = $client->cluster()->getComponentTemplate([
    "name" => "template_1",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_component_template/template_1"

client.cluster().getComponentTemplate(g -> g
    .name("template_1")
);

Delete component templates Generally available; Added in 7.8.0

DELETE /_component_template/{name}

Api key auth Basic auth Bearer auth

Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

Required authorization

Cluster privileges: manage_index_templates

Path parameters

name string | array[string] Required

Comma-separated list or wildcard expression of component template names used to limit the request.

Query parameters

master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
timeout string

Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

DELETE /_component_template/{name}

DELETE _component_template/template_1

resp = client.cluster.delete_component_template(
    name="template_1",
)

const response = await client.cluster.deleteComponentTemplate({
  name: "template_1",
});

response = client.cluster.delete_component_template(
  name: "template_1"
)

$resp = $client->cluster()->deleteComponentTemplate([
    "name" => "template_1",
]);

curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_component_template/template_1"

client.cluster().deleteComponentTemplate(d -> d
    .name("template_1")
);

Close an index Generally available

POST /{index}/_close

Api key auth Basic auth Bearer auth

A closed index is blocked for read or write operations and does not allow all operations that opened indices allow. It is not possible to index documents or to search for documents in a closed index. Closed indices do not have to maintain internal data structures for indexing or searching documents, which results in a smaller overhead on the cluster.

When opening or closing an index, the master node is responsible for restarting the index shards to reflect the new state of the index. The shards will then go through the normal recovery process. The data of opened and closed indices is automatically replicated by the cluster to ensure that enough shard copies are safely kept around at all times.

You can open and close multiple indices. An error is thrown if the request explicitly refers to a missing index. This behaviour can be turned off using the ignore_unavailable=true parameter.

By default, you must explicitly name the indices you are opening or closing. To open or close indices with _all, *, or other wildcard expressions, change theaction.destructive_requires_name setting to false. This setting can also be changed with the cluster update settings API.

Closed indices consume a significant amount of disk-space which can cause problems in managed environments. Closing indices can be turned off with the cluster settings API by setting cluster.indices.close.enable to false.

Required authorization

Index privileges: manage

Path parameters

index string | array[string] Required

Comma-separated list or wildcard expression of index names used to limit the request.

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.
expand_wildcards string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. 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.
Values are all, open, closed, hidden, or none.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.
master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
timeout string

Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
wait_for_active_shards number | string

The number of shard copies 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).

Values are all or index-setting.

Responses

200 application/json
Hide response attributes Show response attributes object
- acknowledged boolean Required
- indices object Required
  
  Hide indices attribute Show indices attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  closed boolean Required
  
  shards object
  
  Hide shards attribute Show shards attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  failures array[object] Required
- shards_acknowledged boolean Required

POST /{index}/_close

POST /my-index-00001/_close

resp = client.indices.close(
    index="my-index-00001",
)

const response = await client.indices.close({
  index: "my-index-00001",
});

response = client.indices.close(
  index: "my-index-00001"
)

$resp = $client->indices()->close([
    "index" => "my-index-00001",
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/my-index-00001/_close"

client.indices().close(c -> c
    .index("my-index-00001")
);

Response examples (200)

A successful response for closing an index.

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "indices": {
    "my-index-000001": {
      "closed": true
    }
  }
}

Delete indices Generally available

DELETE /{index}

Api key auth Basic auth Bearer auth

Deleting an index deletes its documents, shards, and metadata. It does not delete related Kibana components, such as data views, visualizations, or dashboards.

You cannot delete the current write index of a data stream. To delete the index, you must roll over the data stream so a new write index is created. You can then use the delete index API to delete the previous write index.

Required authorization

Index privileges: delete_index

Path parameters

index string | array[string] Required

Comma-separated list of indices to delete. You cannot specify index aliases. By default, this parameter does not support wildcards (*) or _all. To use wildcards or _all, set the action.destructive_requires_name cluster setting to false.

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.
expand_wildcards string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. 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.
Values are all, open, closed, hidden, or none.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.
master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
timeout string

Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

Responses

200 application/json
Hide response attributes Show response attributes object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.
- _shards object
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  suppressed array[object]
  
  shard number Required
  
  status string
  
  skipped number

DELETE /{index}

DELETE /books

resp = client.indices.delete(
    index="books",
)

const response = await client.indices.delete({
  index: "books",
});

response = client.indices.delete(
  index: "books"
)

$resp = $client->indices()->delete([
    "index" => "books",
]);

curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/books"

client.indices().delete(d -> d
    .index("books")
);

Check index templates Generally available

HEAD /_index_template/{name}

Api key auth Basic auth Bearer auth

Check whether index templates exist.

Required authorization

Cluster privileges: manage_index_templates

Path parameters

name string Required

Comma-separated list of index template names used to limit the request. Wildcard (*) expressions are supported.

Query parameters

local boolean

If true, the request retrieves information from the local node only. Defaults to false, which means information is retrieved from the master node.
flat_settings boolean

If true, returns settings in flat format.
master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

Responses

200 application/json

HEAD /_index_template/{name}

curl \
 --request HEAD 'http://api.example.com/_index_template/{name}' \
 --header "Authorization: $API_KEY"

Open a closed index Generally available

POST /{index}/_open

Api key auth Basic auth Bearer auth

For data streams, the API opens any closed backing indices.

A closed index is blocked for read/write operations and does not allow all operations that opened indices allow. It is not possible to index documents or to search for documents in a closed index. This allows closed indices to not have to maintain internal data structures for indexing or searching documents, resulting in a smaller overhead on the cluster.

When opening or closing an index, the master is responsible for restarting the index shards to reflect the new state of the index. The shards will then go through the normal recovery process. The data of opened or closed indices is automatically replicated by the cluster to ensure that enough shard copies are safely kept around at all times.

You can open and close multiple indices. An error is thrown if the request explicitly refers to a missing index. This behavior can be turned off by using the ignore_unavailable=true parameter.

By default, you must explicitly name the indices you are opening or closing. To open or close indices with _all, *, or other wildcard expressions, change the action.destructive_requires_name setting to false. This setting can also be changed with the cluster update settings API.

Closed indices consume a significant amount of disk-space which can cause problems in managed environments. Closing indices can be turned off with the cluster settings API by setting cluster.indices.close.enable to false.

Because opening or closing an index allocates its shards, the wait_for_active_shards setting on index creation applies to the _open and _close index actions as well.

Required authorization

Index privileges: manage

Path parameters

index string | array[string] Required

Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (*). By default, you must explicitly name the indices you using to limit the request. To limit a request using _all, *, or other wildcard expressions, change the action.destructive_requires_name setting to false. You can update this setting in the elasticsearch.yml file or using the cluster update settings API.

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.
expand_wildcards string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. 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.
Values are all, open, closed, hidden, or none.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.
master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
timeout string

Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
wait_for_active_shards number | string

The number of shard copies 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).

Values are all or index-setting.

Responses

200 application/json
Hide response attributes Show response attributes object
- acknowledged boolean Required
- shards_acknowledged boolean Required

POST /{index}/_open

POST /.ds-my-data-stream-2099.03.07-000001/_open/

resp = client.indices.open(
    index=".ds-my-data-stream-2099.03.07-000001",
)

const response = await client.indices.open({
  index: ".ds-my-data-stream-2099.03.07-000001",
});

response = client.indices.open(
  index: ".ds-my-data-stream-2099.03.07-000001"
)

$resp = $client->indices()->open([
    "index" => ".ds-my-data-stream-2099.03.07-000001",
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/.ds-my-data-stream-2099.03.07-000001/_open/"

client.indices().open(o -> o
    .index(".ds-my-data-stream-2099.03.07-000001")
);

Response examples (200)

A successful response for opening an index.

{
  "acknowledged" : true,
  "shards_acknowledged" : true
}

Create or update a lifecycle policy Generally available; Added in 6.6.0

PUT /_ilm/policy/{policy}

Api key auth Basic auth Bearer auth

If the specified policy exists, it is replaced and the policy version is incremented.

NOTE: Only the latest version of the policy is stored, you cannot revert to previous versions.

Required authorization

Index privileges: manage
Cluster privileges: manage_ilm

External documentation

Path parameters

policy string Required

Identifier for the policy.

Query parameters

master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
timeout string

Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

application/json

Body

policy object
Hide policy attributes Show policy attributes object
- phases object Required
  Hide phases attributes Show phases attributes object
  
  cold object
  
  Hide cold attributes Show cold attributes object
  
  actions object
  
  Hide actions attributes Show actions attributes object
  
  allocate object
  
  Hide allocate attributes Show allocate attributes object
  
  number_of_replicas number
  
  total_shards_per_node number
  
  include object
  
  Hide include attribute Show include attribute object
  
  * string Additional properties
  
  exclude object
  
  Hide exclude attribute Show exclude attribute object
  
  * string Additional properties
  
  require object
  
  Hide require attribute Show require attribute object
  
  * string Additional properties
  
  delete object
  
  Hide delete attribute Show delete attribute object
  
  delete_searchable_snapshot boolean
  
  downsample object
  
  Hide downsample attributes Show downsample attributes object
  
  fixed_interval string Required
  
  A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)
  
  wait_timeout string
  
  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.
  
  freeze object
  
  For empty Class assignments
  
  forcemerge object
  
  Hide forcemerge attributes Show forcemerge attributes object
  
  max_num_segments number Required
  
  index_codec string
  
  migrate object
  
  Hide migrate attribute Show migrate attribute object
  
  enabled boolean
  
  readonly object
  
  For empty Class assignments
  
  rollover object
  
  Hide rollover attributes Show rollover attributes object
  
  max_size number | string
  
  One of:
  number-1 number string-2 string
  
  max_primary_shard_size number | string
  
  One of:
  number-1 number string-2 string
  
  max_age string
  
  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.
  
  max_docs number
  
  max_primary_shard_docs number
  
  min_size number | string
  
  One of:
  number-1 number string-2 string
  
  min_primary_shard_size number | string
  
  One of:
  number-1 number string-2 string
  
  min_age string
  
  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.
  
  min_docs number
  
  min_primary_shard_docs number
  
  set_priority object
  
  Hide set_priority attribute Show set_priority attribute object
  
  priority number
  
  searchable_snapshot object
  
  Hide searchable_snapshot attributes Show searchable_snapshot attributes object
  
  snapshot_repository string Required
  
  force_merge_index boolean
  
  shrink object
  
  Hide shrink attributes Show shrink attributes object
  
  number_of_shards number
  
  max_primary_shard_size number | string
  
  One of:
  number-1 number string-2 string
  
  allow_write_after_shrink boolean
  
  unfollow object
  
  For empty Class assignments
  
  wait_for_snapshot object
  
  Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
  
  policy string Required
  
  min_age string
  
  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.
  
  delete object
  
  Hide delete attributes Show delete attributes object
  
  actions object
  
  Hide actions attributes Show actions attributes object
  
  allocate object
  
  Hide allocate attributes Show allocate attributes object
  
  number_of_replicas number
  
  total_shards_per_node number
  
  include object
  
  Hide include attribute Show include attribute object
  
  * string Additional properties
  
  exclude object
  
  Hide exclude attribute Show exclude attribute object
  
  * string Additional properties
  
  require object
  
  Hide require attribute Show require attribute object
  
  * string Additional properties
  
  delete object
  
  Hide delete attribute Show delete attribute object
  
  delete_searchable_snapshot boolean
  
  downsample object
  
  Hide downsample attributes Show downsample attributes object
  
  fixed_interval string Required
  
  A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)
  
  wait_timeout string
  
  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.
  
  freeze object
  
  For empty Class assignments
  
  forcemerge object
  
  Hide forcemerge attributes Show forcemerge attributes object
  
  max_num_segments number Required
  
  index_codec string
  
  migrate object
  
  Hide migrate attribute Show migrate attribute object
  
  enabled boolean
  
  readonly object
  
  For empty Class assignments
  
  rollover object
  
  Hide rollover attributes Show rollover attributes object
  
  max_size number | string
  
  One of:
  number-1 number string-2 string
  
  max_primary_shard_size number | string
  
  One of:
  number-1 number string-2 string
  
  max_age string
  
  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.
  
  max_docs number
  
  max_primary_shard_docs number
  
  min_size number | string
  
  One of:
  number-1 number string-2 string
  
  min_primary_shard_size number | string
  
  One of:
  number-1 number string-2 string
  
  min_age string
  
  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.
  
  min_docs number
  
  min_primary_shard_docs number
  
  set_priority object
  
  Hide set_priority attribute Show set_priority attribute object
  
  priority number
  
  searchable_snapshot object
  
  Hide searchable_snapshot attributes Show searchable_snapshot attributes object
  
  snapshot_repository string Required
  
  force_merge_index boolean
  
  shrink object
  
  Hide shrink attributes Show shrink attributes object
  
  number_of_shards number
  
  max_primary_shard_size number | string
  
  One of:
  number-1 number string-2 string
  
  allow_write_after_shrink boolean
  
  unfollow object
  
  For empty Class assignments
  
  wait_for_snapshot object
  
  Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
  
  policy string Required
  
  min_age string
  
  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.
  
  frozen object
  
  Hide frozen attributes Show frozen attributes object
  
  actions object
  
  Hide actions attributes Show actions attributes object
  
  allocate object
  
  Hide allocate attributes Show allocate attributes object
  
  number_of_replicas number
  
  total_shards_per_node number
  
  include object
  
  Hide include attribute Show include attribute object
  
  * string Additional properties
  
  exclude object
  
  Hide exclude attribute Show exclude attribute object
  
  * string Additional properties
  
  require object
  
  Hide require attribute Show require attribute object
  
  * string Additional properties
  
  delete object
  
  Hide delete attribute Show delete attribute object
  
  delete_searchable_snapshot boolean
  
  downsample object
  
  Hide downsample attributes Show downsample attributes object
  
  fixed_interval string Required
  
  A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)
  
  wait_timeout string
  
  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.
  
  freeze object
  
  For empty Class assignments
  
  forcemerge object
  
  Hide forcemerge attributes Show forcemerge attributes object
  
  max_num_segments number Required
  
  index_codec string
  
  migrate object
  
  Hide migrate attribute Show migrate attribute object
  
  enabled boolean
  
  readonly object
  
  For empty Class assignments
  
  rollover object
  
  Hide rollover attributes Show rollover attributes object
  
  max_size number | string
  
  One of:
  number-1 number string-2 string
  
  max_primary_shard_size number | string
  
  One of:
  number-1 number string-2 string
  
  max_age string
  
  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.
  
  max_docs number
  
  max_primary_shard_docs number
  
  min_size number | string
  
  One of:
  number-1 number string-2 string
  
  min_primary_shard_size number | string
  
  One of:
  number-1 number string-2 string
  
  min_age string
  
  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.
  
  min_docs number
  
  min_primary_shard_docs number
  
  set_priority object
  
  Hide set_priority attribute Show set_priority attribute object
  
  priority number
  
  searchable_snapshot object
  
  Hide searchable_snapshot attributes Show searchable_snapshot attributes object
  
  snapshot_repository string Required
  
  force_merge_index boolean
  
  shrink object
  
  Hide shrink attributes Show shrink attributes object
  
  number_of_shards number
  
  max_primary_shard_size number | string
  
  One of:
  number-1 number string-2 string
  
  allow_write_after_shrink boolean
  
  unfollow object
  
  For empty Class assignments
  
  wait_for_snapshot object
  
  Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
  
  policy string Required
  
  min_age string
  
  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.
  
  hot object
  
  Hide hot attributes Show hot attributes object
  
  actions object
  
  Hide actions attributes Show actions attributes object
  
  allocate object
  
  Hide allocate attributes Show allocate attributes object
  
  number_of_replicas number
  
  total_shards_per_node number
  
  include object
  
  Hide include attribute Show include attribute object
  
  * string Additional properties
  
  exclude object
  
  Hide exclude attribute Show exclude attribute object
  
  * string Additional properties
  
  require object
  
  Hide require attribute Show require attribute object
  
  * string Additional properties
  
  delete object
  
  Hide delete attribute Show delete attribute object
  
  delete_searchable_snapshot boolean
  
  downsample object
  
  Hide downsample attributes Show downsample attributes object
  
  fixed_interval string Required
  
  A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)
  
  wait_timeout string
  
  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.
  
  freeze object
  
  For empty Class assignments
  
  forcemerge object
  
  Hide forcemerge attributes Show forcemerge attributes object
  
  max_num_segments number Required
  
  index_codec string
  
  migrate object
  
  Hide migrate attribute Show migrate attribute object
  
  enabled boolean
  
  readonly object
  
  For empty Class assignments
  
  rollover object
  
  Hide rollover attributes Show rollover attributes object
  
  max_size number | string
  
  One of:
  number-1 number string-2 string
  
  max_primary_shard_size number | string
  
  One of:
  number-1 number string-2 string
  
  max_age string
  
  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.
  
  max_docs number
  
  max_primary_shard_docs number
  
  min_size number | string
  
  One of:
  number-1 number string-2 string
  
  min_primary_shard_size number | string
  
  One of:
  number-1 number string-2 string
  
  min_age string
  
  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.
  
  min_docs number
  
  min_primary_shard_docs number
  
  set_priority object
  
  Hide set_priority attribute Show set_priority attribute object
  
  priority number
  
  searchable_snapshot object
  
  Hide searchable_snapshot attributes Show searchable_snapshot attributes object
  
  snapshot_repository string Required
  
  force_merge_index boolean
  
  shrink object
  
  Hide shrink attributes Show shrink attributes object
  
  number_of_shards number
  
  max_primary_shard_size number | string
  
  One of:
  number-1 number string-2 string
  
  allow_write_after_shrink boolean
  
  unfollow object
  
  For empty Class assignments
  
  wait_for_snapshot object
  
  Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
  
  policy string Required
  
  min_age string
  
  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.
  
  warm object
  
  Hide warm attributes Show warm attributes object
  
  actions object
  
  Hide actions attributes Show actions attributes object
  
  allocate object
  
  Hide allocate attributes Show allocate attributes object
  
  number_of_replicas number
  
  total_shards_per_node number
  
  include object
  
  Hide include attribute Show include attribute object
  
  * string Additional properties
  
  exclude object
  
  Hide exclude attribute Show exclude attribute object
  
  * string Additional properties
  
  require object
  
  Hide require attribute Show require attribute object
  
  * string Additional properties
  
  delete object
  
  Hide delete attribute Show delete attribute object
  
  delete_searchable_snapshot boolean
  
  downsample object
  
  Hide downsample attributes Show downsample attributes object
  
  fixed_interval string Required
  
  A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)
  
  wait_timeout string
  
  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.
  
  freeze object
  
  For empty Class assignments
  
  forcemerge object
  
  Hide forcemerge attributes Show forcemerge attributes object
  
  max_num_segments number Required
  
  index_codec string
  
  migrate object
  
  Hide migrate attribute Show migrate attribute object
  
  enabled boolean
  
  readonly object
  
  For empty Class assignments
  
  rollover object
  
  Hide rollover attributes Show rollover attributes object
  
  max_size number | string
  
  One of:
  number-1 number string-2 string
  
  max_primary_shard_size number | string
  
  One of:
  number-1 number string-2 string
  
  max_age string
  
  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.
  
  max_docs number
  
  max_primary_shard_docs number
  
  min_size number | string
  
  One of:
  number-1 number string-2 string
  
  min_primary_shard_size number | string
  
  One of:
  number-1 number string-2 string
  
  min_age string
  
  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.
  
  min_docs number
  
  min_primary_shard_docs number
  
  set_priority object
  
  Hide set_priority attribute Show set_priority attribute object
  
  priority number
  
  searchable_snapshot object
  
  Hide searchable_snapshot attributes Show searchable_snapshot attributes object
  
  snapshot_repository string Required
  
  force_merge_index boolean
  
  shrink object
  
  Hide shrink attributes Show shrink attributes object
  
  number_of_shards number
  
  max_primary_shard_size number | string
  
  One of:
  number-1 number string-2 string
  
  allow_write_after_shrink boolean
  
  unfollow object
  
  For empty Class assignments
  
  wait_for_snapshot object
  
  Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
  
  policy string Required
  
  min_age string
  
  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.
- _meta object
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

PUT /_ilm/policy/{policy}

PUT _ilm/policy/my_policy
{
  "policy": {
    "_meta": {
      "description": "used for nginx log",
      "project": {
        "name": "myProject",
        "department": "myDepartment"
      }
    },
    "phases": {
      "warm": {
        "min_age": "10d",
        "actions": {
          "forcemerge": {
            "max_num_segments": 1
          }
        }
      },
      "delete": {
        "min_age": "30d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}

resp = client.ilm.put_lifecycle(
    name="my_policy",
    policy={
        "_meta": {
            "description": "used for nginx log",
            "project": {
                "name": "myProject",
                "department": "myDepartment"
            }
        },
        "phases": {
            "warm": {
                "min_age": "10d",
                "actions": {
                    "forcemerge": {
                        "max_num_segments": 1
                    }
                }
            },
            "delete": {
                "min_age": "30d",
                "actions": {
                    "delete": {}
                }
            }
        }
    },
)

const response = await client.ilm.putLifecycle({
  name: "my_policy",
  policy: {
    _meta: {
      description: "used for nginx log",
      project: {
        name: "myProject",
        department: "myDepartment",
      },
    },
    phases: {
      warm: {
        min_age: "10d",
        actions: {
          forcemerge: {
            max_num_segments: 1,
          },
        },
      },
      delete: {
        min_age: "30d",
        actions: {
          delete: {},
        },
      },
    },
  },
});

response = client.ilm.put_lifecycle(
  policy: "my_policy",
  body: {
    "policy": {
      "_meta": {
        "description": "used for nginx log",
        "project": {
          "name": "myProject",
          "department": "myDepartment"
        }
      },
      "phases": {
        "warm": {
          "min_age": "10d",
          "actions": {
            "forcemerge": {
              "max_num_segments": 1
            }
          }
        },
        "delete": {
          "min_age": "30d",
          "actions": {
            "delete": {}
          }
        }
      }
    }
  }
)

$resp = $client->ilm()->putLifecycle([
    "policy" => "my_policy",
    "body" => [
        "policy" => [
            "_meta" => [
                "description" => "used for nginx log",
                "project" => [
                    "name" => "myProject",
                    "department" => "myDepartment",
                ],
            ],
            "phases" => [
                "warm" => [
                    "min_age" => "10d",
                    "actions" => [
                        "forcemerge" => [
                            "max_num_segments" => 1,
                        ],
                    ],
                ],
                "delete" => [
                    "min_age" => "30d",
                    "actions" => [
                        "delete" => new ArrayObject([]),
                    ],
                ],
            ],
        ],
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"policy":{"_meta":{"description":"used for nginx log","project":{"name":"myProject","department":"myDepartment"}},"phases":{"warm":{"min_age":"10d","actions":{"forcemerge":{"max_num_segments":1}}},"delete":{"min_age":"30d","actions":{"delete":{}}}}}}' "$ELASTICSEARCH_URL/_ilm/policy/my_policy"

client.ilm().putLifecycle(p -> p
    .name("my_policy")
    .policy(po -> po
        .phases(ph -> ph
            .delete(d -> d
                .actions(a -> a
                    .delete(de -> de)
                )
                .minAge(m -> m
                    .time("30d")
                )
            )
            .warm(w -> w
                .actions(a -> a
                    .forcemerge(f -> f
                        .maxNumSegments(1)
                    )
                )
                .minAge(m -> m
                    .time("10d")
                )
            )
        )
        .meta(Map.of("description", JsonData.fromJson("\"used for nginx log\""),"project", JsonData.fromJson("{\"name\":\"myProject\",\"department\":\"myDepartment\"}")))
    )
);

Request example

Run `PUT _ilm/policy/my_policy` to create a new policy with arbitrary metadata.

{
  "policy": {
    "_meta": {
      "description": "used for nginx log",
      "project": {
        "name": "myProject",
        "department": "myDepartment"
      }
    },
    "phases": {
      "warm": {
        "min_age": "10d",
        "actions": {
          "forcemerge": {
            "max_num_segments": 1
          }
        }
      },
      "delete": {
        "min_age": "30d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}

Response examples (200)

A successful response when creating a new lifecycle policy.

{
  "acknowledged": true
}

Delete a lifecycle policy Generally available; Added in 6.6.0

DELETE /_ilm/policy/{policy}

Api key auth Basic auth Bearer auth

You cannot delete policies that are currently in use. If the policy is being used to manage any indices, the request fails and returns an error.

Required authorization

Cluster privileges: manage_ilm

Path parameters

policy string Required

Identifier for the policy.

Query parameters

master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
timeout string

Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

DELETE /_ilm/policy/{policy}

DELETE _ilm/policy/my_policy

resp = client.ilm.delete_lifecycle(
    name="my_policy",
)

const response = await client.ilm.deleteLifecycle({
  name: "my_policy",
});

response = client.ilm.delete_lifecycle(
  policy: "my_policy"
)

$resp = $client->ilm()->deleteLifecycle([
    "policy" => "my_policy",
]);

curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ilm/policy/my_policy"

client.ilm().deleteLifecycle(d -> d
    .name("my_policy")
);

Response examples (200)

A successful response when deleting a lifecycle policy.

{
  "acknowledged": true
}

Get the ILM status Generally available; Added in 6.6.0

GET /_ilm/status

Api key auth Basic auth Bearer auth

Get the current index lifecycle management status.

Required authorization

Cluster privileges: read_ilm

Responses

200 application/json
Hide response attribute Show response attribute object
- operation_mode string Required
  
  Values are RUNNING, STOPPING, or STOPPED.

GET /_ilm/status

GET _ilm/status

resp = client.ilm.get_status()

const response = await client.ilm.getStatus();

response = client.ilm.get_status

$resp = $client->ilm()->getStatus();

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ilm/status"

client.ilm().getStatus();

Response examples (200)

A successful response when retrieving the current ILM status.

{
  "operation_mode": "RUNNING"
}

Get cluster info Generally available

GET /

Api key auth Basic auth Bearer auth

Get basic build, version, and cluster information.

Required authorization

Cluster privileges: monitor

Responses

200 application/json
Hide response attributes Show response attributes object
- cluster_name string Required
- cluster_uuid string Required
- name string Required
- tagline string Required
- version object Required
  
  Hide version attributes Show version attributes object
  
  build_date string | number Required
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  string-1 string UnitMillis number
  
  build_flavor string Required
  
  The build flavor. For example, default.
  
  build_hash string Required
  
  The Elasticsearch Git commit's SHA hash.
  
  build_snapshot boolean Required
  
  Indicates whether the Elasticsearch build was a snapshot.
  
  build_type string Required
  
  The build type that corresponds to how Elasticsearch was installed. For example, docker, rpm, or tar.
  
  lucene_version string Required
  
  minimum_index_compatibility_version string Required
  
  minimum_wire_compatibility_version string Required
  
  number string Required
  
  The Elasticsearch version number.

GET /

GET /

resp = client.info()

const response = await client.info();

response = client.info

$resp = $client->info();

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/"

client.info();

Response examples (200)

A successful response from `GET /`s.

{
  "name": "instance-0000000000",
  "cluster_name": "my_test_cluster",
  "cluster_uuid": "5QaxoN0pRZuOmWSxstBBwQ",
  "version": {
    "build_date": "2024-02-01T13:07:13.727175297Z",
    "minimum_wire_compatibility_version": "7.17.0",
    "build_hash": "6185ba65d27469afabc9bc951cded6c17c21e3f3",
    "number": "8.12.1",
    "lucene_version": "9.9.2",
    "minimum_index_compatibility_version": "7.0.0",
    "build_flavor": "default",
    "build_snapshot": false,
    "build_type": "docker"
  },
  "tagline": "You Know, for Search"
}

Get GeoIP database configurations Generally available; Added in 8.15.0

GET /_ingest/geoip/database/{id}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_ingest/geoip/database

GET /_ingest/geoip/database/{id}

Get information about one or more IP geolocation database configurations.

Path parameters

id string | array[string] Required

A comma-separated list of database configuration IDs to retrieve. Wildcard (*) expressions are supported. To get all database configurations, omit this parameter or use *.

Responses

200 application/json
Hide response attribute Show response attribute object
- databases array[object] Required
  
  Hide databases attributes Show databases attributes object
  
  id string Required
  
  version number Required
  
  modified_date_millis number
  
  Time unit for milliseconds
  
  database object
  
  The configuration necessary to identify which IP geolocation provider to use to download a database, as well as any provider-specific configuration necessary for such downloading. At present, the only supported providers are maxmind and ipinfo, and the maxmind provider requires that an account_id (string) is configured. A provider (either maxmind or ipinfo) must be specified. The web and local providers can be returned as read only configurations.
  
  Hide database attributes Show database attributes object
  
  name string Required
  
  maxmind object
  
  Hide maxmind attribute Show maxmind attribute object
  
  account_id string Required
  
  ipinfo object

GET /_ingest/geoip/database/{id}

curl \
 --request GET 'http://api.example.com/_ingest/geoip/database/{id}' \
 --header "Authorization: $API_KEY"

Get GeoIP statistics Generally available; Added in 7.13.0

GET /_ingest/geoip/stats

Api key auth Basic auth Bearer auth

Get download statistics for GeoIP2 databases that are used with the GeoIP processor.

External documentation

Responses

200 application/json
Hide response attributes Show response attributes object
- stats object Required
  
  Hide stats attributes Show stats attributes object
  
  successful_downloads number Required
  
  Total number of successful database downloads.
  
  failed_downloads number Required
  
  Total number of failed database downloads.
  
  total_download_time number
  
  Time unit for milliseconds
  
  databases_count number Required
  
  Current number of databases available for use.
  
  skipped_updates number Required
  
  Total number of database updates skipped.
  
  expired_databases number Required
  
  Total number of databases not updated after 30 days
- nodes object Required
  
  Downloaded GeoIP2 databases for each node.
  
  Hide nodes attribute Show nodes attribute object
  
  * object Additional properties
  
  Downloaded databases for the node. The field key is the node ID.
  
  Hide * attributes Show * attributes object
  
  databases array[object] Required
  
  Downloaded databases for the node.
  
  Hide databases attribute Show databases attribute object
  
  name string Required
  
  files_in_temp array[string] Required
  
  Downloaded database files, including related license files. Elasticsearch stores these files in the node’s temporary directory: $ES_TMPDIR/geoip-databases/.

GET /_ingest/geoip/stats

GET _ingest/geoip/stats

resp = client.ingest.geo_ip_stats()

const response = await client.ingest.geoIpStats();

response = client.ingest.geo_ip_stats

$resp = $client->ingest()->geoIpStats();

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ingest/geoip/stats"

client.ingest().geoIpStats();

Delete an anomaly detection job Generally available; Added in 5.4.0

DELETE /_ml/anomaly_detectors/{job_id}

Api key auth Basic auth Bearer auth

All job configuration, model state and results are deleted. It is not currently possible to delete multiple jobs using wildcards or a comma separated list. If you delete a job that has a datafeed, the request first tries to delete the datafeed. This behavior is equivalent to calling the delete datafeed API with the same timeout and force parameters as the delete job request.

Required authorization

Cluster privileges: manage_ml

Path parameters

job_id string Required

Identifier for the anomaly detection job.

Query parameters

force boolean

Use to forcefully delete an opened job; this method is quicker than closing and deleting the job.
delete_user_annotations boolean

Specifies whether annotations that have been added by the user should be deleted along with any auto-generated annotations when the job is reset.
wait_for_completion boolean

Specifies whether the request should return immediately or wait until the job deletion completes.

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

DELETE /_ml/anomaly_detectors/{job_id}

DELETE _ml/anomaly_detectors/total-requests

resp = client.ml.delete_job(
    job_id="total-requests",
)

const response = await client.ml.deleteJob({
  job_id: "total-requests",
});

response = client.ml.delete_job(
  job_id: "total-requests"
)

$resp = $client->ml()->deleteJob([
    "job_id" => "total-requests",
]);

curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ml/anomaly_detectors/total-requests"

client.ml().deleteJob(d -> d
    .jobId("total-requests")
);

Response examples (200)

A successful response when deleting an anomaly detection job.

{
  "acknowledged": true
}

A successful response when deleting an anomaly detection job asynchronously. When the `wait_for_completion` query parameter is set to `false`, the response contains an identifier for the job deletion task.

{
  "task": "oTUltX4IQMOUUVeiohTt8A:39"
}

Elasticsearch API

Documentation source and versions

Autoscaling

Delete an autoscaling policy Generally available; Added in 7.11.0

Path parameters

Query parameters

Responses

Get a document count Generally available

Required authorization

Path parameters

Query parameters

Responses

epoch number | string

Get anomaly detection jobs Generally available; Added in 7.7.0

Required authorization

Path parameters

Query parameters

Responses

data.input_bytes number | string

model.bytes number | string

model.bytes_exceeded number | string

Get plugin information Generally available

Required authorization

Query parameters

Responses

Get snapshot repository information Generally available; Added in 2.1.0

Required authorization

Query parameters

Responses

Clear cluster voting config exclusions Generally available; Added in 7.0.0

Query parameters

Responses

Get cluster-wide settings Generally available

Required authorization

Query parameters

Responses

Get the cluster health status Generally available; Added in 1.3.0

Required authorization

Path parameters

Query parameters

Responses

Get the pending cluster tasks Generally available

Required authorization

Query parameters

Responses

Get the hot threads for nodes Generally available

Required authorization

Path parameters

Query parameters

Responses

Cluster - Health

Connector

Delete a connector Beta; Added in 8.12.0

Path parameters

Query parameters

Responses

Create a connector Beta; Added in 8.12.0

Body

Responses

Set the connector sync job stats Technical preview

Path parameters

Body Required

Responses

Update the connector configuration Beta; Added in 8.12.0

Path parameters

Body Required

default_value number | string | boolean | null Required

value number | string | boolean | null Required

value number | string | boolean | null Required

tooltip string | null

Responses

Update the connector error field Technical preview; Added in 8.12.0

Path parameters

Body Required

error string | null Required

Responses

Update the connector features Technical preview

Path parameters

Body Required

Responses