Get anomaly detection jobs
Added in 7.7.0
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.
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. Iffalse
, 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
, orpb
. -
h
string | array[string] Comma-separated list of column names to display.
Supported values include:
assignment_explanation
(orae
): For open anomaly detection jobs only, contains messages relating to the selection of a node to run the job.buckets.count
(orbc
,bucketsCount
): The number of bucket results produced by the job.buckets.time.exp_avg
(orbtea
,bucketsTimeExpAvg
): Exponential moving average of all bucket processing times, in milliseconds.buckets.time.exp_avg_hour
(orbteah
,bucketsTimeExpAvgHour
): Exponentially-weighted moving average of bucket processing times calculated in a 1 hour time window, in milliseconds.buckets.time.max
(orbtmax
,bucketsTimeMax
): Maximum among all bucket processing times, in milliseconds.buckets.time.min
(orbtmin
,bucketsTimeMin
): Minimum among all bucket processing times, in milliseconds.buckets.time.total
(orbtt
,bucketsTimeTotal
): Sum of all bucket processing times, in milliseconds.data.buckets
(ordb
,dataBuckets
): The number of buckets processed.data.earliest_record
(order
,dataEarliestRecord
): The timestamp of the earliest chronologically input document.data.empty_buckets
(ordeb
,dataEmptyBuckets
): The number of buckets which did not contain any data.data.input_bytes
(ordib
,dataInputBytes
): The number of bytes of input data posted to the anomaly detection job.data.input_fields
(ordif
,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
(ordir
,dataInputRecords
): The number of input documents posted to the anomaly detection job.data.invalid_dates
(ordid
,dataInvalidDates
): The number of input documents with either a missing date field or a date that could not be parsed.data.last
(ordl
,dataLast
): The timestamp at which data was last analyzed, according to server time.data.last_empty_bucket
(ordleb
,dataLastEmptyBucket
): The timestamp of the last bucket that did not contain any data.data.last_sparse_bucket
(ordlsb
,dataLastSparseBucket
): The timestamp of the last bucket that was considered sparse.data.latest_record
(ordlr
,dataLatestRecord
): The timestamp of the latest chronologically input document.data.missing_fields
(ordmf
,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
(ordoot
,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
(ordpf
,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
(ordpr
,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
(ordsb
,dataSparseBuckets
): The number of buckets that contained few data points compared to the expected number of data points.forecasts.memory.avg
(orfmavg
,forecastsMemoryAvg
): The average memory usage in bytes for forecasts related to the anomaly detection job.forecasts.memory.max
(orfmmax
,forecastsMemoryMax
): The maximum memory usage in bytes for forecasts related to the anomaly detection job.forecasts.memory.min
(orfmmin
,forecastsMemoryMin
): The minimum memory usage in bytes for forecasts related to the anomaly detection job.forecasts.memory.total
(orfmt
,forecastsMemoryTotal
): The total memory usage in bytes for forecasts related to the anomaly detection job.forecasts.records.avg
(orfravg
,forecastsRecordsAvg
): The average number ofm
odel_forecast` documents written for forecasts related to the anomaly detection job.forecasts.records.max
(orfrmax
,forecastsRecordsMax
): The maximum number ofmodel_forecast
documents written for forecasts related to the anomaly detection job.forecasts.records.min
(orfrmin
,forecastsRecordsMin
): The minimum number ofmodel_forecast
documents written for forecasts related to the anomaly detection job.forecasts.records.total
(orfrt
,forecastsRecordsTotal
): The total number ofmodel_forecast
documents written for forecasts related to the anomaly detection job.forecasts.time.avg
(orftavg
,forecastsTimeAvg
): The average runtime in milliseconds for forecasts related to the anomaly detection job.forecasts.time.max
(orftmax
,forecastsTimeMax
): The maximum runtime in milliseconds for forecasts related to the anomaly detection job.forecasts.time.min
(orftmin
,forecastsTimeMin
): The minimum runtime in milliseconds for forecasts related to the anomaly detection job.forecasts.time.total
(orftt
,forecastsTimeTotal
): The total runtime in milliseconds for forecasts related to the anomaly detection job.forecasts.total
(orft
,forecastsTotal
): The number of individual forecasts currently available for the job.id
: Identifier for the anomaly detection job.model.bucket_allocation_failures
(ormbaf
,modelBucketAllocationFailures
): The number of buckets for which new entities in incoming data were not processed due to insufficient model memory.model.by_fields
(ormbf
,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
(ormb
,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
(ormbe
,modelBytesExceeded
): The number of bytes over the high limit for memory usage at the last allocation failure.model.categorization_status
(ormcs
,modelCategorizationStatus
): The status of categorization for the job:ok
orwarn
. Ifok
, categorization is performing acceptably well (or not being used at all). Ifwarn
, 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
(ormcdc
,modelCategorizedDocCount
): The number of documents that have had a field categorized.model.dead_category_count
(ormdcc
,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
(ormdcc
,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
(ormfcc
,modelFrequentCategoryCount
): The number of categories that match more than 1% of categorized documents.model.log_time
(ormlt
,modelLogTime
): The timestamp when the model stats were gathered, according to server time.model.memory_limit
(ormml
,modelMemoryLimit
): The timestamp when the model stats were gathered, according to server time.model.memory_status
(ormms
,modelMemoryStatus
): The status of the mathematical models:ok
,soft_limit
, orhard_limit
. Ifok
, the models stayed below the configured value. Ifsoft_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. Ifhard_limit
, the models used more space than the configured memory limit. As a result, not all incoming data was processed.model.over_fields
(ormof
,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
(ormpf
,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
(ormrcc
,modelRareCategoryCount
): The number of categories that match just one categorized document.model.timestamp
(ormt
,modelTimestamp
): The timestamp of the last record when the model stats were gathered.model.total_category_count
(ormtcc
,modelTotalCategoryCount
): The number of categories created by categorization.node.address
(orna
,nodeAddress
): The network address of the node that runs the job. This information is available only for open jobs.node.ephemeral_id
(orne
,nodeEphemeralId
): The ephemeral ID of the node that runs the job. This information is available only for open jobs.node.id
(orni
,nodeId
): The unique identifier of the node that runs the job. This information is available only for open jobs.node.name
(ornn
,nodeName
): The name of the node that runs the job. This information is available only for open jobs.opened_time
(orot
): For open jobs only, the elapsed time for which the job has been open.state
(ors
): The status of the anomaly detection job:closed
,closing
,failed
,opened
, oropening
. Ifclosed
, the job finished successfully with its model state persisted. The job must be opened before it can accept further data. Ifclosing
, the job close action is in progress and has not yet completed. A closing job cannot accept further data. Iffailed
, 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. Ifopened
, the job is available to receive and process data. Ifopening
, 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
(orae
): For open anomaly detection jobs only, contains messages relating to the selection of a node to run the job.buckets.count
(orbc
,bucketsCount
): The number of bucket results produced by the job.buckets.time.exp_avg
(orbtea
,bucketsTimeExpAvg
): Exponential moving average of all bucket processing times, in milliseconds.buckets.time.exp_avg_hour
(orbteah
,bucketsTimeExpAvgHour
): Exponentially-weighted moving average of bucket processing times calculated in a 1 hour time window, in milliseconds.buckets.time.max
(orbtmax
,bucketsTimeMax
): Maximum among all bucket processing times, in milliseconds.buckets.time.min
(orbtmin
,bucketsTimeMin
): Minimum among all bucket processing times, in milliseconds.buckets.time.total
(orbtt
,bucketsTimeTotal
): Sum of all bucket processing times, in milliseconds.data.buckets
(ordb
,dataBuckets
): The number of buckets processed.data.earliest_record
(order
,dataEarliestRecord
): The timestamp of the earliest chronologically input document.data.empty_buckets
(ordeb
,dataEmptyBuckets
): The number of buckets which did not contain any data.data.input_bytes
(ordib
,dataInputBytes
): The number of bytes of input data posted to the anomaly detection job.data.input_fields
(ordif
,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
(ordir
,dataInputRecords
): The number of input documents posted to the anomaly detection job.data.invalid_dates
(ordid
,dataInvalidDates
): The number of input documents with either a missing date field or a date that could not be parsed.data.last
(ordl
,dataLast
): The timestamp at which data was last analyzed, according to server time.data.last_empty_bucket
(ordleb
,dataLastEmptyBucket
): The timestamp of the last bucket that did not contain any data.data.last_sparse_bucket
(ordlsb
,dataLastSparseBucket
): The timestamp of the last bucket that was considered sparse.data.latest_record
(ordlr
,dataLatestRecord
): The timestamp of the latest chronologically input document.data.missing_fields
(ordmf
,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
(ordoot
,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
(ordpf
,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
(ordpr
,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
(ordsb
,dataSparseBuckets
): The number of buckets that contained few data points compared to the expected number of data points.forecasts.memory.avg
(orfmavg
,forecastsMemoryAvg
): The average memory usage in bytes for forecasts related to the anomaly detection job.forecasts.memory.max
(orfmmax
,forecastsMemoryMax
): The maximum memory usage in bytes for forecasts related to the anomaly detection job.forecasts.memory.min
(orfmmin
,forecastsMemoryMin
): The minimum memory usage in bytes for forecasts related to the anomaly detection job.forecasts.memory.total
(orfmt
,forecastsMemoryTotal
): The total memory usage in bytes for forecasts related to the anomaly detection job.forecasts.records.avg
(orfravg
,forecastsRecordsAvg
): The average number ofm
odel_forecast` documents written for forecasts related to the anomaly detection job.forecasts.records.max
(orfrmax
,forecastsRecordsMax
): The maximum number ofmodel_forecast
documents written for forecasts related to the anomaly detection job.forecasts.records.min
(orfrmin
,forecastsRecordsMin
): The minimum number ofmodel_forecast
documents written for forecasts related to the anomaly detection job.forecasts.records.total
(orfrt
,forecastsRecordsTotal
): The total number ofmodel_forecast
documents written for forecasts related to the anomaly detection job.forecasts.time.avg
(orftavg
,forecastsTimeAvg
): The average runtime in milliseconds for forecasts related to the anomaly detection job.forecasts.time.max
(orftmax
,forecastsTimeMax
): The maximum runtime in milliseconds for forecasts related to the anomaly detection job.forecasts.time.min
(orftmin
,forecastsTimeMin
): The minimum runtime in milliseconds for forecasts related to the anomaly detection job.forecasts.time.total
(orftt
,forecastsTimeTotal
): The total runtime in milliseconds for forecasts related to the anomaly detection job.forecasts.total
(orft
,forecastsTotal
): The number of individual forecasts currently available for the job.id
: Identifier for the anomaly detection job.model.bucket_allocation_failures
(ormbaf
,modelBucketAllocationFailures
): The number of buckets for which new entities in incoming data were not processed due to insufficient model memory.model.by_fields
(ormbf
,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
(ormb
,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
(ormbe
,modelBytesExceeded
): The number of bytes over the high limit for memory usage at the last allocation failure.model.categorization_status
(ormcs
,modelCategorizationStatus
): The status of categorization for the job:ok
orwarn
. Ifok
, categorization is performing acceptably well (or not being used at all). Ifwarn
, 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
(ormcdc
,modelCategorizedDocCount
): The number of documents that have had a field categorized.model.dead_category_count
(ormdcc
,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
(ormdcc
,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
(ormfcc
,modelFrequentCategoryCount
): The number of categories that match more than 1% of categorized documents.model.log_time
(ormlt
,modelLogTime
): The timestamp when the model stats were gathered, according to server time.model.memory_limit
(ormml
,modelMemoryLimit
): The timestamp when the model stats were gathered, according to server time.model.memory_status
(ormms
,modelMemoryStatus
): The status of the mathematical models:ok
,soft_limit
, orhard_limit
. Ifok
, the models stayed below the configured value. Ifsoft_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. Ifhard_limit
, the models used more space than the configured memory limit. As a result, not all incoming data was processed.model.over_fields
(ormof
,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
(ormpf
,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
(ormrcc
,modelRareCategoryCount
): The number of categories that match just one categorized document.model.timestamp
(ormt
,modelTimestamp
): The timestamp of the last record when the model stats were gathered.model.total_category_count
(ormtcc
,modelTotalCategoryCount
): The number of categories created by categorization.node.address
(orna
,nodeAddress
): The network address of the node that runs the job. This information is available only for open jobs.node.ephemeral_id
(orne
,nodeEphemeralId
): The ephemeral ID of the node that runs the job. This information is available only for open jobs.node.id
(orni
,nodeId
): The unique identifier of the node that runs the job. This information is available only for open jobs.node.name
(ornn
,nodeName
): The name of the node that runs the job. This information is available only for open jobs.opened_time
(orot
): For open jobs only, the elapsed time for which the job has been open.state
(ors
): The status of the anomaly detection job:closed
,closing
,failed
,opened
, oropening
. Ifclosed
, the job finished successfully with its model state persisted. The job must be opened before it can accept further data. Ifclosing
, the job close action is in progress and has not yet completed. A closing job cannot accept further data. Iffailed
, 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. Ifopened
, the job is available to receive and process data. Ifopening
, 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
, ord
.
curl \
--request GET 'http://api.example.com/_cat/ml/anomaly_detectors' \
--header "Authorization: $API_KEY"
[
{
"id": "high_sum_total_sales",
"s": "closed",
"dpr": "14022",
"mb": "1.5mb"
},
{
"id": "low_request_rate",
"s": "closed",
"dpr": "1216",
"mb": "40.5kb"
},
{
"id": "response_code_rates",
"s": "closed",
"dpr": "28146",
"mb": "132.7kb"
},
{
"id": "url_scanning",
"s": "closed",
"dpr": "28146",
"mb": "501.6kb"
}
]
Get snapshot information
Added in 2.1.0
Get information about the snapshots stored in one or more repositories. A snapshot is a backup of an index or running Elasticsearch cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get snapshot API.
Query parameters
-
h
string | array[string] List of columns to appear in the response. Supports simple wildcards.
-
s
string | array[string] List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting
:asc
or:desc
as a suffix to the column name. -
master_timeout
string Period to wait for a connection to the master node.
-
time
string Unit used to display time values.
Values are
nanos
,micros
,ms
,s
,m
,h
, ord
.
curl \
--request GET 'http://api.example.com/_cat/snapshots' \
--header "Authorization: $API_KEY"
[
{
"id": "snap1",
"repository": "repo1",
"status": "FAILED",
"start_epoch": "1445616705",
"start_time": "18:11:45",
"end_epoch": "1445616978",
"end_time": "18:16:18",
"duration": "4.6m",
"indices": "1",
"successful_shards": "4",
"failed_shards": "1",
"total_shards": "5"
},
{
"id": "snap2",
"repository": "repo1",
"status": "SUCCESS",
"start_epoch": "1445634298",
"start_time": "23:04:58",
"end_epoch": "1445634672",
"end_time": "23:11:12",
"duration": "6.2m",
"indices": "2",
"successful_shards": "10",
"failed_shards": "0",
"total_shards": "10"
}
]
Get the cluster health
Added in 8.7.0
Get a report with the health status of an Elasticsearch cluster. The report contains a list of indicators that compose Elasticsearch functionality.
Each indicator has a health status of: green, unknown, yellow or red. The indicator will provide an explanation and metadata describing the reason for its current health status.
The cluster’s status is controlled by the worst indicator status.
In the event that an indicator’s status is non-green, a list of impacts may be present in the indicator result which detail the functionalities that are negatively affected by the health issue. Each impact carries with it a severity level, an area of the system that is affected, and a simple description of the impact on the system.
Some health indicators can determine the root cause of a health problem and prescribe a set of steps that can be performed in order to improve the health of the system. The root cause and remediation steps are encapsulated in a diagnosis. A diagnosis contains a cause detailing a root cause analysis, an action containing a brief description of the steps to take to fix the problem, the list of affected resources (if applicable), and a detailed step-by-step troubleshooting guide to fix the diagnosed problem.
NOTE: The health indicators perform root cause analysis of non-green health statuses. This can be computationally expensive when called frequently. When setting up automated polling of the API for health status, set verbose to false to disable the more expensive analysis logic.
Path parameters
-
feature
string | array[string] Required A feature of the cluster, as returned by the top-level health report API.
curl \
--request GET 'http://api.example.com/_health_report/{feature}' \
--header "Authorization: $API_KEY"
Claim a connector sync job
Technical preview
This action updates the job status to in_progress
and sets the last_seen
and started_at
timestamps to the current time.
Additionally, it can set the sync_cursor
property for the sync job.
This API is not intended for direct connector management by users. It supports the implementation of services that utilize the connector protocol to communicate with Elasticsearch.
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.
Body
Required
-
sync_cursor
object The cursor object from the last incremental sync job. This should reference the
sync_cursor
field in the connector state for which the job runs. -
worker_hostname
string Required The host name of the current system that will run the job.
curl \
--request PUT 'http://api.example.com/_connector/_sync_job/{connector_sync_job_id}/_claim' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"sync_cursor":{},"worker_hostname":"string"}'
Update the connector name and description
Beta
Path parameters
-
connector_id
string Required The unique identifier of the connector to be updated
Body
Required
-
name
string -
description
string
curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_name' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"name\": \"Custom connector\",\n \"description\": \"This is my customized connector\"\n}"'
{
"name": "Custom connector",
"description": "This is my customized connector"
}
{
"result": "updated"
}
Pause a follower
Added in 6.5.0
Pause a cross-cluster replication follower index. The follower index will not fetch any additional operations from the leader index. You can resume following with the resume follower API. You can pause and resume a follower index to change the configuration of the following task.
Path parameters
-
index
string Required The name of the follower index.
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.
curl \
--request POST 'http://api.example.com/{index}/_ccr/pause_follow' \
--header "Authorization: $API_KEY"
{
"acknowledged" : true
}
Create a new document in the index
Added in 5.0.0
You can index a new JSON document with the /<target>/_doc/
or /<target>/_create/<_id>
APIs
Using _create
guarantees that the document is indexed only if it does not already exist.
It returns a 409 response when a document with a same ID already exists in the index.
To update an existing document, you must use the /<target>/_doc/
API.
If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:
- To add a document using the
PUT /<target>/_create/<_id>
orPOST /<target>/_create/<_id>
request formats, you must have thecreate_doc
,create
,index
, orwrite
index privilege. - To automatically create a data stream or index with this API request, you must have the
auto_configure
,create_index
, ormanage
index privilege.
Automatic data stream creation requires a matching index template with data stream enabled.
Automatically create data streams and indices
If the request's target doesn't exist and matches an index template with a data_stream
definition, the index operation automatically creates the data stream.
If the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.
NOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.
If no mapping exists, the index operation creates a dynamic mapping. By default, new fields and objects are automatically added to the mapping if needed.
Automatic index creation is controlled by the action.auto_create_index
setting.
If it is true
, any index can be created automatically.
You can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to false
to turn off automatic index creation entirely.
Specify a comma-separated list of patterns you want to allow or prefix each pattern with +
or -
to indicate whether it should be allowed or blocked.
When a list is specified, the default behaviour is to disallow.
NOTE: The action.auto_create_index
setting affects the automatic creation of indices only.
It does not affect the creation of data streams.
Routing
By default, shard placement — or routing — is controlled by using a hash of the document's ID value.
For more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the routing
parameter.
When setting up explicit mapping, you can also use the _routing
field to direct the index operation to extract the routing value from the document itself.
This does come at the (very minimal) cost of an additional document parsing pass.
If the _routing
mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.
NOTE: Data streams do not support custom routing unless they were created with the allow_custom_routing
setting enabled in the template.
Distributed
The index operation is directed to the primary shard based on its route and performed on the actual node containing this shard. After the primary shard completes the operation, if needed, the update is distributed to applicable replicas.
Active shards
To improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation.
If the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs.
By default, write operations only wait for the primary shards to be active before proceeding (that is to say wait_for_active_shards
is 1
).
This default can be overridden in the index settings dynamically by setting index.write.wait_for_active_shards
.
To alter this behavior per operation, use the wait_for_active_shards request
parameter.
Valid values are all or any positive integer up to the total number of configured copies per shard in the index (which is number_of_replicas
+1).
Specifying a negative value or a number greater than the number of shard copies will throw an error.
For example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes).
If you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding.
This means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data.
If wait_for_active_shards
is set on the request to 3
(and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding.
This requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard.
However, if you set wait_for_active_shards
to all
(or to 4
, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index.
The operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.
It is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts.
After the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary.
The _shards
section of the API response reveals the number of shard copies on which replication succeeded and failed.
Path parameters
-
index
string Required The name of the data stream or index to target. If the target doesn't exist and matches the name or wildcard (
*
) pattern of an index template with adata_stream
definition, this request creates the data stream. If the target doesn't exist and doesn’t match a data stream template, this request creates the index. -
id
string Required A unique identifier for the document. To automatically generate a document ID, use the
POST /<target>/_doc/
request format.
Query parameters
-
if_primary_term
number Only perform the operation if the document has this primary term.
-
if_seq_no
number Only perform the operation if the document has this sequence number.
-
include_source_on_error
boolean True or false if to include the document source in the error message in case of parsing errors.
-
op_type
string Set to
create
to only index the document if it does not already exist (put if absent). If a document with the specified_id
already exists, the indexing operation will fail. The behavior is the same as using the<index>/_create
endpoint. If a document ID is specified, this paramater defaults toindex
. Otherwise, it defaults tocreate
. If the request targets a data stream, anop_type
ofcreate
is required.Supported values include:
index
: Overwrite any documents that already exist.create
: Only index documents that do not already exist.
Values are
index
orcreate
. -
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. -
refresh
string If
true
, Elasticsearch refreshes the affected shards to make this operation visible to search. Ifwait_for
, it waits for a refresh to make this operation visible to search. Iffalse
, it does nothing with refreshes.Values are
true
,false
, orwait_for
. -
require_alias
boolean If
true
, the destination must be an index alias. -
require_data_stream
boolean If
true
, the request's actions must target a data stream (existing or to be created). -
routing
string A custom value that is used to route operations to a specific shard.
-
timeout
string The period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards. Elasticsearch waits for at least the specified timeout period before failing. The actual wait time could be longer, particularly when multiple waits occur.
This parameter is useful for situations where the primary shard assigned to perform the operation might not be available when the operation runs. Some reasons for this might be that the primary shard is currently recovering from a gateway or undergoing relocation. By default, the operation will wait on the primary shard to become available for at least 1 minute before failing and responding with an error. The actual wait time could be longer, particularly when multiple waits occur.
-
version
number The explicit version number for concurrency control. It must be a non-negative long number.
-
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: Theexternal_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
, orforce
. -
wait_for_active_shards
number | string The number of shard copies that must be active before proceeding with the operation. You can set it to
all
or any positive integer up to the total number of shards in the index (number_of_replicas+1
). The default value of1
means it waits for each primary shard to be active.
curl \
--request PUT 'http://api.example.com/{index}/_create/{id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"@timestamp\": \"2099-11-15T13:12:00\",\n \"message\": \"GET /search HTTP/1.1 200 1070000\",\n \"user\": {\n \"id\": \"kimchy\"\n }\n}"'
{
"@timestamp": "2099-11-15T13:12:00",
"message": "GET /search HTTP/1.1 200 1070000",
"user": {
"id": "kimchy"
}
}
Run an async ES|QL query
Added in 8.13.0
Asynchronously run an ES|QL (Elasticsearch query language) query, monitor its progress, and retrieve results when they become available.
The API accepts the same parameters and request body as the synchronous query API, along with additional async related properties.
Query parameters
-
allow_partial_results
boolean If
true
, partial results will be returned if there are shard failures, but the query can continue to execute on other clusters and shards. Iffalse
, the query will fail if there are any failures.To override the default behavior, you can set the
esql.query.allow_partial_results
cluster setting tofalse
. -
delimiter
string The character to use between values within a CSV row. It is valid only for the CSV format.
-
drop_null_columns
boolean Indicates whether columns that are entirely
null
will be removed from thecolumns
andvalues
portion of the results. Iftrue
, the response will include an extra section under the nameall_columns
which has the name of all the columns. -
format
string A short version of the Accept header, for example
json
oryaml
.Values are
csv
,json
,tsv
,txt
,yaml
,cbor
,smile
, orarrow
. -
keep_alive
string The period for which the query and its results are stored in the cluster. The default period is five days. When this period expires, the query and its results are deleted, even if the query is still ongoing. If the
keep_on_completion
parameter is false, Elasticsearch only stores async queries that do not complete within the period set by thewait_for_completion_timeout
parameter, regardless of this value. -
keep_on_completion
boolean Indicates whether the query and its results are stored in the cluster. If false, the query and its results are stored in the cluster only if the request does not complete during the period set by the
wait_for_completion_timeout
parameter. -
wait_for_completion_timeout
string The period to wait for the request to finish. By default, the request waits for 1 second for the query results. If the query completes during this period, results are returned Otherwise, a query ID is returned that can later be used to retrieve the results.
Body
Required
-
columnar
boolean By default, ES|QL returns results as rows. For example, FROM returns each individual document as one row. For the JSON, YAML, CBOR and smile formats, ES|QL can return the results in a columnar fashion where one row represents all the values of a certain column in the results.
-
filter
object An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation -
locale
string -
params
array[number | string | boolean | null] To avoid any attempts of hacking or code injection, extract the values in a separate list of parameters. Use question mark placeholders (?) in the query string for each of the parameters.
-
profile
boolean If provided and
true
the response will include an extraprofile
object with information on how the query was executed. This information is for human debugging and its format can change at any time but it can give some insight into the performance of each part of the query. -
query
string Required The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results.
-
tables
object Tables to use with the LOOKUP operation. The top level key is the table name and the next level key is the column name.
-
include_ccs_metadata
boolean When set to
true
and performing a cross-cluster query, the response will include an extra_clusters
object with information about the clusters that participated in the search along with info such as shards count. -
wait_for_completion_timeout
string A duration. Units can be
nanos
,micros
,ms
(milliseconds),s
(seconds),m
(minutes),h
(hours) andd
(days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
curl \
--request POST 'http://api.example.com/_query/async' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"query\": \"\"\"\n FROM library,remote-*:library\n | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n | STATS MAX(page_count) BY year\n | SORT year\n | LIMIT 5\n \"\"\",\n \"wait_for_completion_timeout\": \"2s\",\n \"include_ccs_metadata\": true\n}"'
{
"query": """
FROM library,remote-*:library
| EVAL year = DATE_TRUNC(1 YEARS, release_date)
| STATS MAX(page_count) BY year
| SORT year
| LIMIT 5
""",
"wait_for_completion_timeout": "2s",
"include_ccs_metadata": true
}
Get tokens from text analysis
The analyze API performs analysis on a text string and returns the resulting tokens.
Generating excessive amount of tokens may cause a node to run out of memory.
The index.analyze.max_token_count
setting enables you to limit the number of tokens that can be produced.
If more than this limit of tokens gets generated, an error occurs.
The _analyze
endpoint without a specified index will always use 10000
as its limit.
Query parameters
-
index
string Index used to derive the analyzer. If specified, the
analyzer
or field parameter overrides this value. If no index is specified or the index does not have a default analyzer, the analyze API uses the standard analyzer.
Body
-
analyzer
string The name of the analyzer that should be applied to the provided
text
. This could be a built-in analyzer, or an analyzer that’s been configured in the index. -
attributes
array[string] Array of token attributes used to filter the output of the
explain
parameter. -
char_filter
array Array of character filters used to preprocess characters before the tokenizer.
External documentation -
explain
boolean If
true
, the response includes token attributes and additional details. -
field
string Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
-
filter
array Array of token filters used to apply after the tokenizer.
External documentation -
normalizer
string Normalizer to use to convert text into a single token.
text
string | array[string]
curl \
--request GET 'http://api.example.com/_analyze' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"analyzer\": \"standard\",\n \"text\": \"this is a test\"\n}"'
{
"analyzer": "standard",
"text": "this is a test"
}
{
"analyzer": "standard",
"text": [
"this is a test",
"the second text"
]
}
{
"tokenizer": "keyword",
"filter": [
"lowercase"
],
"char_filter": [
"html_strip"
],
"text": "this is a <b>test</b>"
}
{
"tokenizer": "whitespace",
"filter": [
"lowercase",
{
"type": "stop",
"stopwords": [
"a",
"is",
"this"
]
}
],
"text": "this is a test"
}
{
"field": "obj1.field1",
"text": "this is a test"
}
{
"normalizer": "my_normalizer",
"text": "BaR"
}
{
"tokenizer": "standard",
"filter": [
"snowball"
],
"text": "detailed output",
"explain": true,
"attributes": [
"keyword"
]
}
{
"detail": {
"custom_analyzer": true,
"charfilters": [],
"tokenizer": {
"name": "standard",
"tokens": [
{
"token": "detailed",
"start_offset": 0,
"end_offset": 8,
"type": "<ALPHANUM>",
"position": 0
},
{
"token": "output",
"start_offset": 9,
"end_offset": 15,
"type": "<ALPHANUM>",
"position": 1
}
]
},
"tokenfilters": [
{
"name": "snowball",
"tokens": [
{
"token": "detail",
"start_offset": 0,
"end_offset": 8,
"type": "<ALPHANUM>",
"position": 0,
"keyword": false
},
{
"token": "output",
"start_offset": 9,
"end_offset": 15,
"type": "<ALPHANUM>",
"position": 1,
"keyword": false
}
]
}
]
}
}
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.
-
timeout
string Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request DELETE 'http://api.example.com/{index}/_aliases/{name}' \
--header "Authorization: $API_KEY"
Force a merge
Added in 2.1.0
Perform the force merge operation on the shards of one or more indices. For data streams, the API forces a merge on the shards of the stream's backing indices.
Merging reduces the number of segments in each shard by merging some of them together and also frees up the space used by deleted documents. Merging normally happens automatically, but sometimes it is useful to trigger a merge manually.
WARNING: We recommend force merging only a read-only index (meaning the index is no longer receiving writes). When documents are updated or deleted, the old version is not immediately removed but instead soft-deleted and marked with a "tombstone". These soft-deleted documents are automatically cleaned up during regular segment merges. But force merge can cause very large (greater than 5 GB) segments to be produced, which are not eligible for regular merges. So the number of soft-deleted documents can then grow rapidly, resulting in higher disk usage and worse search performance. If you regularly force merge an index receiving writes, this can also make snapshots more expensive, since the new documents can't be backed up incrementally.
Blocks during a force merge
Calls to this API block until the merge is complete (unless request contains wait_for_completion=false
).
If the client connection is lost before completion then the force merge process will continue in the background.
Any new requests to force merge the same indices will also block until the ongoing force merge is complete.
Running force merge asynchronously
If the request contains wait_for_completion=false
, Elasticsearch performs some preflight checks, launches the request, and returns a task you can use to get the status of the task.
However, you can not cancel this task as the force merge task is not cancelable.
Elasticsearch creates a record of this task as a document at _tasks/<task_id>
.
When you are done with a task, you should delete the task document so Elasticsearch can reclaim the space.
Force merging multiple indices
You can force merge multiple indices with a single request by targeting:
- One or more data streams that contain multiple backing indices
- Multiple indices
- One or more aliases
- All data streams and indices in a cluster
Each targeted shard is force-merged separately using the force_merge threadpool.
By default each node only has a single force_merge
thread which means that the shards on that node are force-merged one at a time.
If you expand the force_merge
threadpool on a node then it will force merge its shards in parallel
Force merge makes the storage for the shard being merged temporarily increase, as it may require free space up to triple its size in case max_num_segments parameter
is set to 1
, to rewrite all segments into a new one.
Data streams and time-based indices
Force-merging is useful for managing a data stream's older backing indices and other time-based indices, particularly after a rollover. In these cases, each index only receives indexing traffic for a certain period of time. Once an index receive no more writes, its shards can be force-merged to a single segment. This can be a good idea because single-segment shards can sometimes use simpler and more efficient data structures to perform searches. For example:
POST /.ds-my-data-stream-2099.03.07-000001/_forcemerge?max_num_segments=1
Query parameters
-
allow_no_indices
boolean Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes
_all
string or when no indices have been specified) -
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 withopen
,closed
, orboth
.none
: Wildcard expressions are not accepted.
-
flush
boolean Specify whether the index should be flushed after performing the operation (default: true)
-
max_num_segments
number The number of segments the index should be merged into (default: dynamic)
-
only_expunge_deletes
boolean Specify whether the operation should only expunge deleted documents
-
wait_for_completion
boolean Should the request wait until the force merge is completed.
curl \
--request POST 'http://api.example.com/_forcemerge' \
--header "Authorization: $API_KEY"
Get index templates
Get information about one or more index templates.
IMPORTANT: This documentation is about legacy index templates, which are deprecated and will be replaced by the composable templates introduced in Elasticsearch 7.8.
Query parameters
-
flat_settings
boolean If
true
, returns settings in flat format. -
local
boolean If
true
, the request retrieves information from the local node only. -
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.
curl \
--request GET 'http://api.example.com/_template' \
--header "Authorization: $API_KEY"
Reload search analyzers
Added in 7.3.0
Reload an index's search analyzers and their resources. For data streams, the API reloads search analyzers and resources for the stream's backing indices.
IMPORTANT: After reloading the search analyzers you should clear the request cache to make sure it doesn't contain responses derived from the previous versions of the analyzer.
You can use the reload search analyzers API to pick up changes to synonym files used in the synonym_graph
or synonym
token filter of a search analyzer.
To be eligible, the token filter must have an updateable
flag of true
and only be used in search analyzers.
NOTE: This API does not perform a reload for each shard of an index. Instead, it performs a reload for each node containing index shards. As a result, the total shard count returned by the API can differ from the number of index shards. Because reloading affects every node with an index shard, it is important to update the synonym file on every data node in the cluster--including nodes that don't contain a shard replica--before using this API. This ensures the synonym file is updated everywhere in the cluster in case shards are relocated in the future.
Path parameters
-
index
string | array[string] Required A comma-separated list of index names to reload analyzers for
Query parameters
-
allow_no_indices
boolean Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes
_all
string or when no indices have been specified) -
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 withopen
,closed
, orboth
.none
: Wildcard expressions are not accepted.
-
resource
string Changed resource to reload analyzers from if applicable
curl \
--request POST 'http://api.example.com/{index}/_reload_search_analyzers' \
--header "Authorization: $API_KEY"
Resolve the cluster
Added in 8.13.0
Resolve the specified index expressions to return information about each cluster, including the local "querying" cluster, if included. If no index expression is provided, the API will return information about all the remote clusters that are configured on the querying cluster.
This endpoint is useful before doing a cross-cluster search in order to determine which remote clusters should be included in a search.
You use the same index expression with this endpoint as you would for cross-cluster search. Index and cluster exclusions are also supported with this endpoint.
For each cluster in the index expression, information is returned about:
- Whether the querying ("local") cluster is currently connected to each remote cluster specified in the index expression. Note that this endpoint actively attempts to contact the remote clusters, unlike the
remote/info
endpoint. - Whether each remote cluster is configured with
skip_unavailable
astrue
orfalse
. - Whether there are any indices, aliases, or data streams on that cluster that match the index expression.
- Whether the search is likely to have errors returned when you do the cross-cluster search (including any authorization errors if you do not have permission to query the index).
- Cluster version information, including the Elasticsearch server version.
For example, GET /_resolve/cluster/my-index-*,cluster*:my-index-*
returns information about the local cluster and all remotely configured clusters that start with the alias cluster*
.
Each cluster returns information about whether it has any indices, aliases or data streams that match my-index-*
.
Note on backwards compatibility
The ability to query without an index expression was added in version 8.18, so when
querying remote clusters older than that, the local cluster will send the index
expression dummy*
to those remote clusters. Thus, if an errors occur, you may see a reference
to that index expression even though you didn't request it. If it causes a problem, you can
instead include an index expression like *:*
to bypass the issue.
Advantages of using this endpoint before a cross-cluster search
You may want to exclude a cluster or index from a search when:
- A remote cluster is not currently connected and is configured with
skip_unavailable=false
. Running a cross-cluster search under those conditions will cause the entire search to fail. - A cluster has no matching indices, aliases or data streams for the index expression (or your user does not have permissions to search them). For example, suppose your index expression is
logs*,remote1:logs*
and the remote1 cluster has no indices, aliases or data streams that matchlogs*
. In that case, that cluster will return no results from that cluster if you include it in a cross-cluster search. - The index expression (combined with any query parameters you specify) will likely cause an exception to be thrown when you do the search. In these cases, the "error" field in the
_resolve/cluster
response will be present. (This is also where security/permission errors will be shown.) - A remote cluster is an older version that does not support the feature you want to use in your search.
Test availability of remote clusters
The remote/info
endpoint is commonly used to test whether the "local" cluster (the cluster being queried) is connected to its remote clusters, but it does not necessarily reflect whether the remote cluster is available or not.
The remote cluster may be available, while the local cluster is not currently connected to it.
You can use the _resolve/cluster
API to attempt to reconnect to remote clusters.
For example with GET _resolve/cluster
or GET _resolve/cluster/*:*
.
The connected
field in the response will indicate whether it was successful.
If a connection was (re-)established, this will also cause the remote/info
endpoint to now indicate a connected status.
Path parameters
-
name
string | array[string] Required A comma-separated list of names or index patterns for the indices, aliases, and data streams to resolve. Resources on remote clusters can be specified using the
<cluster>
:<name>
syntax. Index and cluster exclusions (e.g.,-cluster1:*
) are also supported. If no index expression is specified, information about all remote clusters configured on the local cluster is returned without doing any index matching
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. For example, a request targetingfoo*,bar*
returns an error if an index starts withfoo
but no index starts withbar
. NOTE: This option is only supported when specifying an index expression. You will get an error if you specify index options to the_resolve/cluster
API endpoint that takes no index expression. -
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
. Valid values are:all
,open
,closed
,hidden
,none
. NOTE: This option is only supported when specifying an index expression. You will get an error if you specify index options to the_resolve/cluster
API endpoint that takes no index expression.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 withopen
,closed
, orboth
.none
: Wildcard expressions are not accepted.
-
ignore_throttled
boolean Deprecated If true, concrete, expanded, or aliased indices are ignored when frozen. NOTE: This option is only supported when specifying an index expression. You will get an error if you specify index options to the
_resolve/cluster
API endpoint that takes no index expression. -
timeout
string The maximum time to wait for remote clusters to respond. If a remote cluster does not respond within this timeout period, the API response will show the cluster as not connected and include an error message that the request timed out.
The default timeout is unset and the query can take as long as the networking layer is configured to wait for remote clusters that are not responding (typically 30 seconds).
curl \
--request GET 'http://api.example.com/_resolve/cluster/{name}' \
--header "Authorization: $API_KEY"
{
"(local)": {
"connected": true,
"skip_unavailable": false,
"matching_indices": true,
"version": {
"number": "8.13.0",
"build_flavor": "default",
"minimum_wire_compatibility_version": "7.17.0",
"minimum_index_compatibility_version": "7.0.0"
}
},
"cluster_one": {
"connected": true,
"skip_unavailable": true,
"matching_indices": true,
"version": {
"number": "8.13.0",
"build_flavor": "default",
"minimum_wire_compatibility_version": "7.17.0",
"minimum_index_compatibility_version": "7.0.0"
}
},
"cluster_two": {
"connected": true,
"skip_unavailable": false,
"matching_indices": true,
"version": {
"number": "8.13.0",
"build_flavor": "default",
"minimum_wire_compatibility_version": "7.17.0",
"minimum_index_compatibility_version": "7.0.0"
}
}
}
{
"(local)": {
"connected": true,
"skip_unavailable": false,
"error": "no such index [not_present]"
},
"cluster_one": {
"connected": true,
"skip_unavailable": true,
"matching_indices": false,
"version": {
"number": "8.13.0",
"build_flavor": "default",
"minimum_wire_compatibility_version": "7.17.0",
"minimum_index_compatibility_version": "7.0.0"
}
},
"cluster_two": {
"connected": false,
"skip_unavailable": false
},
"cluster_three": {
"connected": false,
"skip_unavailable": false,
"error": "Request timed out before receiving a response from the remote cluster"
},
"oldcluster": {
"connected": true,
"skip_unavailable": false,
"matching_indices": true
}
}
Delete an inference endpoint
Added in 8.11.0
Path parameters
-
task_type
string Required The task type
Values are
sparse_embedding
,text_embedding
,rerank
,completion
, orchat_completion
. -
inference_id
string Required The inference identifier.
curl \
--request DELETE 'http://api.example.com/_inference/{task_type}/{inference_id}' \
--header "Authorization: $API_KEY"
Get calendar configuration info
Added in 6.2.0
Path parameters
-
calendar_id
string Required A string that uniquely identifies a calendar. You can get information for multiple calendars by using a comma-separated list of ids or a wildcard expression. You can get information for all calendars by using
_all
or*
or by omitting the calendar identifier.
curl \
--request POST 'http://api.example.com/_ml/calendars/{calendar_id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"page":{"from":42.0,"size":42.0}}'
Delete events from a calendar
Added in 6.2.0
Path parameters
-
calendar_id
string Required A string that uniquely identifies a calendar.
-
event_id
string Required Identifier for the scheduled event. You can obtain this identifier by using the get calendar events API.
curl \
--request DELETE 'http://api.example.com/_ml/calendars/{calendar_id}/events/{event_id}' \
--header "Authorization: $API_KEY"
{
"acknowledged": true
}
Delete an anomaly detection job
Added in 5.4.0
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.
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.
curl \
--request DELETE 'http://api.example.com/_ml/anomaly_detectors/{job_id}' \
--header "Authorization: $API_KEY"
{
"acknowledged": true
}
{
"task": "oTUltX4IQMOUUVeiohTt8A:39"
}
Get anomaly detection job results for categories
Added in 5.4.0
Path parameters
-
job_id
string Required Identifier for the anomaly detection job.
Query parameters
-
from
number Skips the specified number of categories.
-
partition_field_value
string Only return categories for the specified partition.
-
size
number Specifies the maximum number of categories to obtain.
curl \
--request POST 'http://api.example.com/_ml/anomaly_detectors/{job_id}/results/categories' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"page":{"from":42.0,"size":42.0}}'
Stop datafeeds
Added in 5.4.0
A datafeed that is stopped ceases to retrieve data from Elasticsearch. A datafeed can be started and stopped multiple times throughout its lifecycle.
Path parameters
-
datafeed_id
string Required Identifier for the datafeed. You can stop multiple datafeeds in a single API request by using a comma-separated list of datafeeds or a wildcard expression. You can close all datafeeds by using
_all
or by specifying*
as the identifier.
Query parameters
-
allow_no_match
boolean Specifies what to do when the request:
- Contains wildcard expressions and there are no datafeeds 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 datafeeds array when there are no matches and the subset of results when there are partial matches. Iffalse
, the API returns a 404 status code when there are no matches or only partial matches. -
force
boolean If
true
, the datafeed is stopped forcefully. -
timeout
string Specifies the amount of time to wait until a datafeed stops.
Body
-
allow_no_match
boolean Refer to the description for the
allow_no_match
query parameter. -
force
boolean Refer to the description for the
force
query parameter. -
timeout
string A duration. Units can be
nanos
,micros
,ms
(milliseconds),s
(seconds),m
(minutes),h
(hours) andd
(days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
curl \
--request POST 'http://api.example.com/_ml/datafeeds/{datafeed_id}/_stop' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"allow_no_match":true,"force":true,"timeout":"string"}'
Get data frame analytics job configuration info
Added in 7.3.0
You can get information for multiple data frame analytics jobs in a single API request by using a comma-separated list of data frame analytics jobs or a wildcard expression.
Path parameters
-
id
string Required Identifier for the data frame analytics job. If you do not specify this option, the API returns information for the first hundred data frame analytics jobs.
Query parameters
-
allow_no_match
boolean Specifies what to do when the request:
- Contains wildcard expressions and there are no data frame analytics jobs that match.
- Contains the
_all
string or no identifiers and there are no matches. - Contains wildcard expressions and there are only partial matches.
The default value returns an empty data_frame_analytics array when there are no matches and the subset of results when there are partial matches. If this parameter is
false
, the request returns a 404 status code when there are no matches or only partial matches. -
from
number Skips the specified number of data frame analytics jobs.
-
size
number Specifies the maximum number of data frame analytics jobs to obtain.
-
exclude_generated
boolean Indicates if certain fields should be removed from the configuration on retrieval. This allows the configuration to be in an acceptable format to be retrieved and then added to another cluster.
curl \
--request GET 'http://api.example.com/_ml/data_frame/analytics/{id}' \
--header "Authorization: $API_KEY"
Clear trained model deployment cache
Added in 8.5.0
Cache will be cleared on all nodes where the trained model is assigned. A trained model deployment may have an inference cache enabled. As requests are handled by each allocated node, their responses may be cached on that individual node. Calling this API clears the caches without restarting the deployment.
Path parameters
-
model_id
string Required The unique identifier of the trained model.
curl \
--request POST 'http://api.example.com/_ml/trained_models/{model_id}/deployment/cache/_clear' \
--header "Authorization: $API_KEY"
{
"cleared": true
}
Evaluate a trained model
Added in 8.3.0
Path parameters
-
model_id
string Required The unique identifier of the trained model.
Query parameters
-
timeout
string Controls the amount of time to wait for inference results.
Body
Required
-
docs
array[object] Required An array of objects to pass to the model for inference. The objects should contain a fields matching your configured trained model input. Typically, for NLP models, the field name is
text_field
. Currently, for NLP models, only a single value is allowed. -
inference_config
object
curl \
--request POST 'http://api.example.com/_ml/trained_models/{model_id}/_infer' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"docs":[{"additionalProperty1":{},"additionalProperty2":{}}],"inference_config":{"regression":{"results_field":"string","num_top_feature_importance_values":42.0},"classification":{"num_top_classes":42.0,"num_top_feature_importance_values":42.0,"prediction_field_type":"string","results_field":"string","top_classes_results_field":"string"},"text_classification":{"num_top_classes":42.0,"tokenization":{"truncate":"first","span":42.0},"results_field":"string","classification_labels":["string"]},"zero_shot_classification":{"tokenization":{"truncate":"first","span":42.0},"results_field":"string","multi_label":true,"labels":["string"]},"fill_mask":{"num_top_classes":42.0,"tokenization":{"truncate":"first","span":42.0},"results_field":"string"},"ner":{"tokenization":{"truncate":"first","span":42.0},"results_field":"string"},"pass_through":{"tokenization":{"truncate":"first","span":42.0},"results_field":"string"},"text_embedding":{"tokenization":{"truncate":"first","span":42.0},"results_field":"string"},"text_expansion":{"tokenization":{"truncate":"first","span":42.0},"results_field":"string"},"question_answering":{"question":"string","num_top_classes":42.0,"tokenization":{"truncate":"first","span":42.0},"results_field":"string","max_answer_length":42.0}}}'
Get the shutdown status
Added in 7.13.0
Get information about nodes that are ready to be shut down, have shut down preparations still in progress, or have stalled. The API returns status information for each part of the shut down process.
NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
If the operator privileges feature is enabled, you must be an operator to use this API.
Path parameters
-
node_id
string | array[string] Required Which node for which to retrieve the shutdown status
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
nanos
,micros
,ms
,s
,m
,h
, ord
.
curl \
--request GET 'http://api.example.com/_nodes/{node_id}/shutdown' \
--header "Authorization: $API_KEY"
{
"nodes": [
{
"node_id": "USpTGYaBSIKbgSUJR2Z9lg",
"type": "RESTART",
"reason": "Demonstrating how the node shutdown API works",
"shutdown_startedmillis": 1624406108685,
"allocation_delay": "10m",
"status": "COMPLETE",
"shard_migration": {
"status": "COMPLETE",
"shard_migrations_remaining": 0,
"explanation": "no shard relocation is necessary for a node restart"
},
"persistent_tasks": {
"status": "COMPLETE"
},
"plugins": {
"status": "COMPLETE"
}
}
]
}
Cancel node shutdown preparations
Added in 7.13.0
Remove a node from the shutdown list so it can resume normal operations. You must explicitly clear the shutdown request when a node rejoins the cluster or when a node has permanently left the cluster. Shutdown requests are never removed automatically by Elasticsearch.
NOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
If the operator privileges feature is enabled, you must be an operator to use this API.
Path parameters
-
node_id
string Required The node id of node to be removed from the shutdown state
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
nanos
,micros
,ms
,s
,m
,h
, ord
. -
timeout
string Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are
nanos
,micros
,ms
,s
,m
,h
, ord
.
curl \
--request DELETE 'http://api.example.com/_nodes/{node_id}/shutdown' \
--header "Authorization: $API_KEY"
{
"acknowledged": true
}
Get a query ruleset
Added in 8.10.0
Get details about a query ruleset.
Path parameters
-
ruleset_id
string Required The unique identifier of the query ruleset
curl \
--request GET 'http://api.example.com/_query_rules/{ruleset_id}' \
--header "Authorization: $API_KEY"
{
"ruleset_id": "my-ruleset",
"rules": [
{
"rule_id": "my-rule1",
"type": "pinned",
"criteria": [
{
"type": "contains",
"metadata": "query_string",
"values": [ "pugs", "puggles" ]
}
],
"actions": {
"ids": [
"id1",
"id2"
]
}
},
{
"rule_id": "my-rule2",
"type": "pinned",
"criteria": [
{
"type": "fuzzy",
"metadata": "query_string",
"values": [ "rescue dogs" ]
}
],
"actions": {
"docs": [
{
"_index": "index1",
"_id": "id3"
},
{
"_index": "index2",
"_id": "id4"
}
]
}
}
]
}
Create or update a script or search template
Creates or updates a stored script or search template.
Query parameters
-
context
string The context in which the script or search template should run. To prevent errors, the API immediately compiles the script or template in this context. If you specify both this and the
<context>
path parameter, the API uses the request path parameter. -
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. It can also be set to
-1
to indicate that the request should never timeout. -
timeout
string The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. It can also be set to
-1
to indicate that the request should never timeout.
curl \
--request PUT 'http://api.example.com/_scripts/{id}/{context}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"script\": {\n \"lang\": \"mustache\",\n \"source\": {\n \"query\": {\n \"match\": {\n \"message\": \"{{query_string}}\"\n }\n },\n \"from\": \"{{from}}\",\n \"size\": \"{{size}}\"\n }\n }\n}"'
{
"script": {
"lang": "mustache",
"source": {
"query": {
"match": {
"message": "{{query_string}}"
}
},
"from": "{{from}}",
"size": "{{size}}"
}
}
}
{
"script": {
"lang": "painless",
"source": "Math.log(_score * 2) + params['my_modifier']"
}
}
Create or update a script or search template
Creates or updates a stored script or search template.
Query parameters
-
context
string The context in which the script or search template should run. To prevent errors, the API immediately compiles the script or template in this context. If you specify both this and the
<context>
path parameter, the API uses the request path parameter. -
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. It can also be set to
-1
to indicate that the request should never timeout. -
timeout
string The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. It can also be set to
-1
to indicate that the request should never timeout.
curl \
--request POST 'http://api.example.com/_scripts/{id}/{context}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"script\": {\n \"lang\": \"mustache\",\n \"source\": {\n \"query\": {\n \"match\": {\n \"message\": \"{{query_string}}\"\n }\n },\n \"from\": \"{{from}}\",\n \"size\": \"{{size}}\"\n }\n }\n}"'
{
"script": {
"lang": "mustache",
"source": {
"query": {
"match": {
"message": "{{query_string}}"
}
},
"from": "{{from}}",
"size": "{{size}}"
}
}
}
{
"script": {
"lang": "painless",
"source": "Math.log(_score * 2) + params['my_modifier']"
}
}
Bulk delete roles
Added in 8.15.0
The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. The bulk delete roles API cannot delete roles that are defined in roles files.
Query parameters
-
refresh
string If
true
(the default) then refresh the affected shards to make this operation visible to search, ifwait_for
then wait for a refresh to make this operation visible to search, iffalse
then do nothing with refreshes.Values are
true
,false
, orwait_for
.
curl \
--request DELETE 'http://api.example.com/_security/role' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"names\": [\"my_admin_role\", \"my_user_role\"]\n}"'
{
"names": ["my_admin_role", "my_user_role"]
}
{
"deleted": [
"my_admin_role",
"my_user_role"
]
}
{
"deleted": [
"my_admin_role"
],
"not_found": [
"not_an_existing_role"
]
}
{
"deleted": [
"my_admin_role"
],
"errors": {
"count": 1,
"details": {
"superuser": {
"type": "illegal_argument_exception",
"reason": "role [superuser] is reserved and cannot be deleted"
}
}
}
}
Get role mappings
Added in 5.5.0
Role mappings define which roles are assigned to each user. The role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The get role mappings API cannot retrieve role mappings that are defined in role mapping files.
Path parameters
-
name
string | array[string] Required The distinct name that identifies the role mapping. The name is used solely as an identifier to facilitate interaction via the API; it does not affect the behavior of the mapping in any way. You can specify multiple mapping names as a comma-separated list. If you do not specify this parameter, the API returns information about all role mappings.
curl \
--request GET 'http://api.example.com/_security/role_mapping/{name}' \
--header "Authorization: $API_KEY"
{
"mapping1": {
"enabled": true,
"roles": [
"user"
],
"rules": {
"field": {
"username": "*"
}
},
"metadata": {}
}
}
Create SAML service provider metadata
Added in 7.11.0
Generate SAML metadata for a SAML 2.0 Service Provider.
The SAML 2.0 specification provides a mechanism for Service Providers to describe their capabilities and configuration using a metadata file. This API generates Service Provider metadata based on the configuration of a SAML realm in Elasticsearch.
Path parameters
-
realm_name
string Required The name of the SAML realm in Elasticsearch.
curl \
--request GET 'http://api.example.com/_security/saml/metadata/{realm_name}' \
--header "Authorization: $API_KEY"
{
"acknowledged": true
}
Create a snapshot
Added in 0.0.0
Take a snapshot of a cluster or of data streams and indices.
Path parameters
-
repository
string Required The name of the repository for the snapshot.
-
snapshot
string Required The name of the snapshot. It supportes date math. It must be unique in the repository.
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.
-
wait_for_completion
boolean If
true
, the request returns a response when the snapshot is complete. Iffalse
, the request returns a response when the snapshot initializes.
Body
-
expand_wildcards
string | array[string] -
feature_states
array[string] The feature states to include in the snapshot. Each feature state includes one or more system indices containing related data. You can view a list of eligible features using the get features API.
If
include_global_state
istrue
, all current feature states are included by default. Ifinclude_global_state
isfalse
, no feature states are included by default.Note that specifying an empty array will result in the default behavior. To exclude all feature states, regardless of the
include_global_state
value, specify an array with only the valuenone
(["none"]
). -
include_global_state
boolean If
true
, the current cluster state is included in the snapshot. The cluster state includes persistent cluster settings, composable index templates, legacy index templates, ingest pipelines, and ILM policies. It also includes data stored in system indices, such as Watches and task records (configurable viafeature_states
). -
indices
string | array[string] -
metadata
object -
partial
boolean If
true
, it enables you to restore a partial snapshot of indices with unavailable shards. Only shards that were successfully included in the snapshot will be restored. All missing shards will be recreated as empty.If
false
, the entire restore operation will fail if one or more indices included in the snapshot do not have all primary shards available.
curl \
--request POST 'http://api.example.com/_snapshot/{repository}/{snapshot}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"indices\": \"index_1,index_2\",\n \"ignore_unavailable\": true,\n \"include_global_state\": false,\n \"metadata\": {\n \"taken_by\": \"user123\",\n \"taken_because\": \"backup before upgrading\"\n }\n}"'
{
"indices": "index_1,index_2",
"ignore_unavailable": true,
"include_global_state": false,
"metadata": {
"taken_by": "user123",
"taken_because": "backup before upgrading"
}
}
{
"snapshot": {
"snapshot": "snapshot_2",
"uuid": "vdRctLCxSketdKb54xw67g",
"repository": "my_repository",
"version_id": <version_id>,
"version": <version>,
"indices": [],
"data_streams": [],
"feature_states": [],
"include_global_state": false,
"metadata": {
"taken_by": "user123",
"taken_because": "backup before upgrading"
},
"state": "SUCCESS",
"start_time": "2020-06-25T14:00:28.850Z",
"start_time_in_millis": 1593093628850,
"end_time": "2020-06-25T14:00:28.850Z",
"end_time_in_millis": 1593094752018,
"duration_in_millis": 0,
"failures": [],
"shards": {
"total": 0,
"failed": 0,
"successful": 0
}
}
}
Get snapshot repository information
Added in 0.0.0
Query parameters
-
local
boolean If
true
, the request gets information from the local node only. Iffalse
, the request gets information from the master node. -
master_timeout
string The period to wait for the master node. If the master node is not available before the timeout expires, the request fails and returns an error. To indicate that the request should never timeout, set it to
-1
.
curl \
--request GET 'http://api.example.com/_snapshot' \
--header "Authorization: $API_KEY"
{
"my_repository" : {
"type" : "fs",
"uuid" : "0JLknrXbSUiVPuLakHjBrQ",
"settings" : {
"location" : "my_backup_location"
}
}
}
Start snapshot lifecycle management
Added in 7.6.0
Snapshot lifecycle management (SLM) starts automatically when a cluster is formed. Manually starting SLM is necessary only if it has been stopped using the stop SLM API.
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. To indicate that the request should never timeout, set it to
-1
. -
timeout
string The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. To indicate that the request should never timeout, set it to
-1
.
curl \
--request POST 'http://api.example.com/_slm/start' \
--header "Authorization: $API_KEY"
{
"acknowledged": true
}
curl \
--request POST 'http://api.example.com/_sql/close' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"cursor\": \"sDXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAEWYUpOYklQMHhRUEtld3RsNnFtYU1hQQ==:BAFmBGRhdGUBZgVsaWtlcwFzB21lc3NhZ2UBZgR1c2Vy9f///w8=\"\n}"'
{
"cursor": "sDXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAEWYUpOYklQMHhRUEtld3RsNnFtYU1hQQ==:BAFmBGRhdGUBZgVsaWtlcwFzB21lc3NhZ2UBZgR1c2Vy9f///w8="
}
Translate SQL into Elasticsearch queries
Added in 6.3.0
Translate an SQL search into a search API request containing Query DSL.
It accepts the same request body parameters as the SQL search API, excluding cursor
.
Body
Required
-
fetch_size
number The maximum number of rows (or entries) to return in one response.
-
filter
object An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation -
query
string Required The SQL query to run.
-
time_zone
string
curl \
--request GET 'http://api.example.com/_sql/translate' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"query\": \"SELECT * FROM library ORDER BY page_count DESC\",\n \"fetch_size\": 10\n}"'
{
"query": "SELECT * FROM library ORDER BY page_count DESC",
"fetch_size": 10
}