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.

Endpoint documentation

client.indices.resolveCluster({ ... })

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

Resolve indices. Resolve the names and/or index patterns for indices, aliases, and data streams. Multiple patterns and remote clusters are supported.

Endpoint documentation

client.indices.resolveIndex({ name })

Roll over to a new index. TIP: It is recommended to use the index lifecycle rollover action to automate rollovers.

The rollover API creates a new index for a data stream or index alias. The API behavior depends on the rollover target.

Roll over a data stream

If you roll over a data stream, the API creates a new write index for the stream. The stream’s previous write index becomes a regular backing index. A rollover also increments the data stream’s generation.

Roll over an index alias with a write index

If an index alias points to multiple indices, one of the indices must be a write index. The rollover API creates a new write index for the alias with is_write_index set to true. The API also sets is_write_index to false for the previous write index.

Roll over an index alias with one index

If you roll over an index alias that points to only one index, the API creates a new index for the alias and removes the original index from the alias.

Increment index names for an alias

When you roll over an index alias, you can specify a name for the new index. If you don’t specify a name and the current index ends with - and a number, such as my-index-000001 or my-index-3, the new index name increments that number. For example, if you roll over an alias with a current index of my-index-000001, the rollover creates a new index named my-index-000002. This number is always six characters and zero-padded, regardless of the previous index’s name.

If you use an index alias for time series data, you can use date math in the index name to track the rollover date. For example, you can create an alias that points to an index named <my-index-{now/d}-000001>. If you create the index on May 6, 2099, the index’s name is my-index-2099.05.06-000001. If you roll over the alias on May 7, 2099, the new index’s name is my-index-2099.05.07-000002.

Endpoint documentation

client.indices.rollover({ alias })

Get index segments. Get low-level information about the Lucene segments in index shards. For data streams, the API returns information about the stream’s backing indices.

Endpoint documentation

client.indices.segments({ ... })

Get index shard stores. Get store information about replica shards in one or more indices. For data streams, the API retrieves store information for the stream’s backing indices.

The index shard stores API returns the following information:

By default, the API returns store information only for primary shards that are unassigned or have one or more unassigned replica shards.

Endpoint documentation

client.indices.shardStores({ ... })

Shrink an index. Shrink an index into a new index with fewer primary shards.

Before you can shrink an index:

To make shard allocation easier, we recommend you also remove the index’s replica shards. You can later re-add replica shards as part of the shrink operation.

The requested number of primary shards in the target index must be a factor of the number of shards in the source index. For example an index with 8 primary shards can be shrunk into 4, 2 or 1 primary shards or an index with 15 primary shards can be shrunk into 5, 3 or 1. If the number of shards in the index is a prime number it can only be shrunk into a single primary shard Before shrinking, a (primary or replica) copy of every shard in the index must be present on the same node.

The current write index on a data stream cannot be shrunk. In order to shrink the current write index, the data stream must first be rolled over so that a new write index is created and then the previous write index can be shrunk.

A shrink operation:

Endpoint documentation

client.indices.shrink({ index, target })

Simulate an index. Get the index configuration that would be applied to the specified index from an existing index template.

Endpoint documentation

client.indices.simulateIndexTemplate({ name })

Simulate an index template. Get the index configuration that would be applied by a particular index template.

Endpoint documentation

client.indices.simulateTemplate({ ... })

Split an index. Split an index into a new index with more primary shards. * Before you can split an index:

You can do make an index read-only with the following request using the add index block API:

PUT /my_source_index/_block/write

The current write index on a data stream cannot be split. In order to split the current write index, the data stream must first be rolled over so that a new write index is created and then the previous write index can be split.

The number of times the index can be split (and the number of shards that each original shard can be split into) is determined by the index.number_of_routing_shards setting. The number of routing shards specifies the hashing space that is used internally to distribute documents across shards with consistent hashing. For instance, a 5 shard index with number_of_routing_shards set to 30 (5 x 2 x 3) could be split by a factor of 2 or 3.

A split operation:

Endpoint documentation

client.indices.split({ index, target })

Get index statistics. For data streams, the API retrieves statistics for the stream’s backing indices.

By default, the returned statistics are index-level with primaries and total aggregations. primaries are the values for only the primary shards. total are the accumulated values for both primary and replica shards.

To get shard-level statistics, set the level parameter to shards.

Endpoint documentation

client.indices.stats({ ... })

Unfreeze an index. When a frozen index is unfrozen, the index goes through the normal recovery process and becomes writeable again.

Endpoint documentation

client.indices.unfreeze({ index })

Create or update an alias. Adds a data stream or index to an alias.

Endpoint documentation

client.indices.updateAliases({ ... })

Validate a query. Validates a query without running it.

Endpoint documentation

client.indices.validateQuery({ ... })

Perform chat completion inference

Endpoint documentation

client.inference.chatCompletionUnified({ inference_id })

Perform completion inference on the service

Endpoint documentation

client.inference.completion({ inference_id, input })

Delete an inference endpoint

Endpoint documentation

client.inference.delete({ inference_id })

Get an inference endpoint

Endpoint documentation

client.inference.get({ ... })

Perform inference on the service.

This API enables you to use machine learning models to perform specific tasks on data that you provide as an input. It returns a response with the results of the tasks. The inference endpoint you use can perform one specific task that has been defined when the endpoint was created with the create inference API.

For details about using this API with a service, such as Amazon Bedrock, Anthropic, or HuggingFace, refer to the service-specific documentation.

Endpoint documentation

client.inference.inference({ inference_id, input })

Create an inference endpoint. When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running. After creating the endpoint, wait for the model deployment to complete before using it. To verify the deployment status, use the get trained model statistics API. Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count". Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.

Endpoint documentation

client.inference.put({ inference_id })

Create an AlibabaCloud AI Search inference endpoint.

Create an inference endpoint to perform an inference task with the alibabacloud-ai-search service.

When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running. After creating the endpoint, wait for the model deployment to complete before using it. To verify the deployment status, use the get trained model statistics API. Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count". Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.

Endpoint documentation

client.inference.putAlibabacloud({ task_type, alibabacloud_inference_id, service, service_settings })

Create an Amazon Bedrock inference endpoint.

Creates an inference endpoint to perform an inference task with the amazonbedrock service.

>info > You need to provide the access and secret keys only once, during the inference model creation. The get inference API does not retrieve your access or secret keys. After creating the inference model, you cannot change the associated key pairs. If you want to use a different access and secret key pair, delete the inference model and recreate it with the same name and the updated keys.

When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running. After creating the endpoint, wait for the model deployment to complete before using it. To verify the deployment status, use the get trained model statistics API. Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count". Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.

Endpoint documentation

client.inference.putAmazonbedrock({ task_type, amazonbedrock_inference_id, service, service_settings })

Create an Anthropic inference endpoint.

Create an inference endpoint to perform an inference task with the anthropic service.

When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running. After creating the endpoint, wait for the model deployment to complete before using it. To verify the deployment status, use the get trained model statistics API. Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count". Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.

Endpoint documentation

client.inference.putAnthropic({ task_type, anthropic_inference_id, service, service_settings })

Create an Azure AI studio inference endpoint.

Create an inference endpoint to perform an inference task with the azureaistudio service.

When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running. After creating the endpoint, wait for the model deployment to complete before using it. To verify the deployment status, use the get trained model statistics API. Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count". Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.

Endpoint documentation

client.inference.putAzureaistudio({ task_type, azureaistudio_inference_id, service, service_settings })

Create an Azure OpenAI inference endpoint.

Create an inference endpoint to perform an inference task with the azureopenai service.

The list of chat completion models that you can choose from in your Azure OpenAI deployment include:

The list of embeddings models that you can choose from in your deployment can be found in the [Azure models documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?tabs=global-standard%2Cstandard-chat-completions#embeddings).

When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running. After creating the endpoint, wait for the model deployment to complete before using it. To verify the deployment status, use the get trained model statistics API. Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count". Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.

Endpoint documentation

client.inference.putAzureopenai({ task_type, azureopenai_inference_id, service, service_settings })

Create a Cohere inference endpoint.

Create an inference endpoint to perform an inference task with the cohere service.

When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running. After creating the endpoint, wait for the model deployment to complete before using it. To verify the deployment status, use the get trained model statistics API. Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count". Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.

Endpoint documentation

client.inference.putCohere({ task_type, cohere_inference_id, service, service_settings })

Create an Elasticsearch inference endpoint.

Create an inference endpoint to perform an inference task with the elasticsearch service.

If you use the ELSER or the E5 model through the elasticsearch service, the API request will automatically download and deploy the model if it isn’t downloaded yet.

After creating the endpoint, wait for the model deployment to complete before using it. To verify the deployment status, use the get trained model statistics API. Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count". Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.

Endpoint documentation

client.inference.putElasticsearch({ task_type, elasticsearch_inference_id, service, service_settings })

Create an ELSER inference endpoint.

Create an inference endpoint to perform an inference task with the elser service. You can also deploy ELSER by using the Elasticsearch inference integration.

The API request will automatically download and deploy the ELSER model if it isn’t already downloaded.

After creating the endpoint, wait for the model deployment to complete before using it. To verify the deployment status, use the get trained model statistics API. Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count". Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.

Endpoint documentation

client.inference.putElser({ task_type, elser_inference_id, service, service_settings })

Create an Google AI Studio inference endpoint.

Create an inference endpoint to perform an inference task with the googleaistudio service.

When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running. After creating the endpoint, wait for the model deployment to complete before using it. To verify the deployment status, use the get trained model statistics API. Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count". Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.

Endpoint documentation

client.inference.putGoogleaistudio({ task_type, googleaistudio_inference_id, service, service_settings })

Create a Google Vertex AI inference endpoint.

Create an inference endpoint to perform an inference task with the googlevertexai service.

When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running. After creating the endpoint, wait for the model deployment to complete before using it. To verify the deployment status, use the get trained model statistics API. Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count". Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.

Endpoint documentation

client.inference.putGooglevertexai({ task_type, googlevertexai_inference_id, service, service_settings })

Create a Hugging Face inference endpoint.

Create an inference endpoint to perform an inference task with the hugging_face service.

You must first create an inference endpoint on the Hugging Face endpoint page to get an endpoint URL. Select the model you want to use on the new endpoint creation page (for example intfloat/e5-small-v2), then select the sentence embeddings task under the advanced configuration section. Create the endpoint and copy the URL after the endpoint initialization has been finished.

The following models are recommended for the Hugging Face service:

When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running. After creating the endpoint, wait for the model deployment to complete before using it. To verify the deployment status, use the get trained model statistics API. Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count". Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.

Endpoint documentation

client.inference.putHuggingFace({ task_type, huggingface_inference_id, service, service_settings })

Create an JinaAI inference endpoint.

Create an inference endpoint to perform an inference task with the jinaai service.

To review the available rerank models, refer to https://jina.ai/reranker. To review the available text_embedding models, refer to the https://jina.ai/embeddings/.

When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running. After creating the endpoint, wait for the model deployment to complete before using it. To verify the deployment status, use the get trained model statistics API. Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count". Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.

Endpoint documentation

client.inference.putJinaai({ task_type, jinaai_inference_id, service, service_settings })

Create a Mistral inference endpoint.

Creates an inference endpoint to perform an inference task with the mistral service.

When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running. After creating the endpoint, wait for the model deployment to complete before using it. To verify the deployment status, use the get trained model statistics API. Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count". Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.

client.inference.putMistral({ task_type, mistral_inference_id, service, service_settings })

Create an OpenAI inference endpoint.

Create an inference endpoint to perform an inference task with the openai service or openai compatible APIs.

When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running. After creating the endpoint, wait for the model deployment to complete before using it. To verify the deployment status, use the get trained model statistics API. Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count". Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.

Endpoint documentation

client.inference.putOpenai({ task_type, openai_inference_id, service, service_settings })

Create a VoyageAI inference endpoint.

Create an inference endpoint to perform an inference task with the voyageai service.

Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.

Endpoint documentation

client.inference.putVoyageai({ task_type, voyageai_inference_id, service, service_settings })

Create a Watsonx inference endpoint.

Create an inference endpoint to perform an inference task with the watsonxai service. You need an IBM Cloud Databases for Elasticsearch deployment to use the watsonxai inference service. You can provision one through the IBM catalog, the Cloud Databases CLI plug-in, the Cloud Databases API, or Terraform.

When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running. After creating the endpoint, wait for the model deployment to complete before using it. To verify the deployment status, use the get trained model statistics API. Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count". Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.

Endpoint documentation

client.inference.putWatsonx({ task_type, watsonx_inference_id, service, service_settings })

Perform rereanking inference on the service

Endpoint documentation

client.inference.rerank({ inference_id, query, input })

Perform sparse embedding inference on the service

Endpoint documentation

client.inference.sparseEmbedding({ inference_id, input })

Perform streaming inference. Get real-time responses for completion tasks by delivering answers incrementally, reducing response times during computation. This API works only with the completion task type.

This API requires the monitor_inference cluster privilege (the built-in inference_admin and inference_user roles grant this privilege). You must use a client that supports streaming.

Endpoint documentation

client.inference.streamCompletion({ inference_id, input })

Perform text embedding inference on the service

Endpoint documentation

client.inference.textEmbedding({ inference_id, input })

Update an inference endpoint.

Modify task_settings, secrets (within service_settings), or num_allocations for an inference endpoint, depending on the specific endpoint service and task_type.

Endpoint documentation

client.inference.update({ inference_id })

Delete GeoIP database configurations.

Delete one or more IP geolocation database configurations.

Endpoint documentation

client.ingest.deleteGeoipDatabase({ id })

Delete IP geolocation database configurations.

Endpoint documentation

client.ingest.deleteIpLocationDatabase({ id })

Delete pipelines. Delete one or more ingest pipelines.

Endpoint documentation

client.ingest.deletePipeline({ id })

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

Endpoint documentation

client.ingest.geoIpStats()

Get GeoIP database configurations.

Get information about one or more IP geolocation database configurations.

Endpoint documentation

client.ingest.getGeoipDatabase({ ... })

Get IP geolocation database configurations.

Endpoint documentation

client.ingest.getIpLocationDatabase({ ... })

Get pipelines.

Get information about one or more ingest pipelines. This API returns a local reference of the pipeline.

Endpoint documentation

client.ingest.getPipeline({ ... })

Run a grok processor. Extract structured fields out of a single text field within a document. You must choose which field to extract matched fields from, as well as the grok pattern you expect will match. A grok pattern is like a regular expression that supports aliased expressions that can be reused.

Endpoint documentation

client.ingest.processorGrok()

Create or update a GeoIP database configuration.

Refer to the create or update IP geolocation database configuration API.

Endpoint documentation

client.ingest.putGeoipDatabase({ id, name, maxmind })

Create or update an IP geolocation database configuration.

Endpoint documentation

client.ingest.putIpLocationDatabase({ id })

Create or update a pipeline. Changes made using this API take effect immediately.

Endpoint documentation

client.ingest.putPipeline({ id })

Simulate a pipeline.

Run an ingest pipeline against a set of provided documents. You can either specify an existing pipeline to use with the provided documents or supply a pipeline definition in the body of the request.

Endpoint documentation

client.ingest.simulate({ docs })

Delete the license.

When the license expires, your subscription level reverts to Basic.

If the operator privileges feature is enabled, only operator users can use this API.

Endpoint documentation

client.license.delete({ ... })

Get license information.

Get information about your Elastic license including its type, its status, when it was issued, and when it expires.

>info > If the master node is generating a new cluster state, the get license API may return a 404 Not Found response. > If you receive an unexpected 404 response after cluster startup, wait a short period and retry the request.

Endpoint documentation

client.license.get({ ... })

Get the basic license status.

Endpoint documentation

client.license.getBasicStatus()

Get the trial status.

Endpoint documentation

client.license.getTrialStatus()

Update the license.

You can update your license at runtime without shutting down your nodes. License updates take effect immediately. If the license you are installing does not support all of the features that were available with your previous license, however, you are notified in the response. You must then re-submit the API request with the acknowledge parameter set to true.

Endpoint documentation

client.license.post({ ... })

Start a basic license.

Start an indefinite basic license, which gives access to all the basic features.

If the basic license does not support all of the features that are available with your current license, however, you are notified in the response. You must then re-submit the API request with the acknowledge parameter set to true.

To check the status of your basic license, use the get basic license API.

Endpoint documentation

client.license.postStartBasic({ ... })

Start a trial. Start a 30-day trial, which gives access to all subscription features.

To check the status of your trial, use the get trial status API.

Endpoint documentation

client.license.postStartTrial({ ... })

Delete a Logstash pipeline. Delete a pipeline that is used for Logstash Central Management. If the request succeeds, you receive an empty response with an appropriate status code.

Endpoint documentation

client.logstash.deletePipeline({ id })

Get Logstash pipelines. Get pipelines that are used for Logstash Central Management.

Endpoint documentation

client.logstash.getPipeline({ ... })

Create or update a Logstash pipeline.

Create a pipeline that is used for Logstash Central Management. If the specified pipeline exists, it is replaced.

Endpoint documentation

client.logstash.putPipeline({ id })

Get deprecation information. Get information about different cluster, node, and index level settings that use deprecated features that will be removed or changed in the next major version.

Endpoint documentation

client.migration.deprecations({ ... })

Get feature migration information. Version upgrades sometimes require changes to how features store configuration information and data in system indices. Check which features need to be migrated and the status of any migrations that are in progress.

Endpoint documentation

client.migration.getFeatureUpgradeStatus()

Start the feature migration. Version upgrades sometimes require changes to how features store configuration information and data in system indices. This API starts the automatic migration process.

Some functionality might be temporarily unavailable during the migration process.

Endpoint documentation

client.migration.postFeatureUpgrade()

Clear trained model deployment cache.

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.

Endpoint documentation

client.ml.clearTrainedModelDeploymentCache({ model_id })

Close anomaly detection jobs.

A job can be opened and closed multiple times throughout its lifecycle. A closed job cannot receive data or perform analysis operations, but you can still explore and navigate results. When you close a job, it runs housekeeping tasks such as pruning the model history, flushing buffers, calculating final results and persisting the model snapshots. Depending upon the size of the job, it could take several minutes to close and the equivalent time to re-open. After it is closed, the job has a minimal overhead on the cluster except for maintaining its meta data. Therefore it is a best practice to close jobs that are no longer required to process data. If you close an anomaly detection job whose datafeed is running, the request first tries to stop the datafeed. This behavior is equivalent to calling stop datafeed API with the same timeout and force parameters as the close job request. When a datafeed that has a specified end date stops, it automatically closes its associated job.

Endpoint documentation

client.ml.closeJob({ job_id })

Delete a calendar.

Remove all scheduled events from a calendar, then delete it.

Endpoint documentation

client.ml.deleteCalendar({ calendar_id })

Delete events from a calendar.

Endpoint documentation

client.ml.deleteCalendarEvent({ calendar_id, event_id })

Delete anomaly jobs from a calendar.

Endpoint documentation

client.ml.deleteCalendarJob({ calendar_id, job_id })

Delete a data frame analytics job.

Endpoint documentation

client.ml.deleteDataFrameAnalytics({ id })

Delete a datafeed.

Endpoint documentation

client.ml.deleteDatafeed({ datafeed_id })

Delete expired ML data.

Delete all job results, model snapshots and forecast data that have exceeded their retention days period. Machine learning state documents that are not associated with any job are also deleted. You can limit the request to a single or set of anomaly detection jobs by using a job identifier, a group name, a list of jobs, or a wildcard expression. You can delete expired data for all anomaly detection jobs by using _all, by specifying * as the <job_id>, or by omitting the <job_id>.

Endpoint documentation

client.ml.deleteExpiredData({ ... })

Delete a filter.

If an anomaly detection job references the filter, you cannot delete the filter. You must update or delete the job before you can delete the filter.

Endpoint documentation

client.ml.deleteFilter({ filter_id })

Delete forecasts from a job.

By default, forecasts are retained for 14 days. You can specify a different retention period with the expires_in parameter in the forecast jobs API. The delete forecast API enables you to delete one or more forecasts before they expire.

Endpoint documentation

client.ml.deleteForecast({ job_id })

Delete an anomaly detection job.

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.

Endpoint documentation

client.ml.deleteJob({ job_id })

Delete a model snapshot.

You cannot delete the active model snapshot. To delete that snapshot, first revert to a different one. To identify the active model snapshot, refer to the model_snapshot_id in the results from the get jobs API.

Endpoint documentation

client.ml.deleteModelSnapshot({ job_id, snapshot_id })

Delete an unreferenced trained model.

The request deletes a trained inference model that is not referenced by an ingest pipeline.

Endpoint documentation

client.ml.deleteTrainedModel({ model_id })

Delete a trained model alias.

This API deletes an existing model alias that refers to a trained model. If the model alias is missing or refers to a model other than the one identified by the model_id, this API returns an error.

Endpoint documentation

client.ml.deleteTrainedModelAlias({ model_alias, model_id })

Estimate job model memory usage.

Make an estimation of the memory usage for an anomaly detection job model. The estimate is based on analysis configuration details for the job and cardinality estimates for the fields it references.

Endpoint documentation

client.ml.estimateModelMemory({ ... })

Evaluate data frame analytics.

The API packages together commonly used evaluation metrics for various types of machine learning features. This has been designed for use on indexes created by data frame analytics. Evaluation requires both a ground truth field and an analytics result field to be present.

Endpoint documentation

client.ml.evaluateDataFrame({ evaluation, index })

Explain data frame analytics config.

This API provides explanations for a data frame analytics config that either exists already or one that has not been created yet. The following explanations are provided: * which fields are included or not in the analysis and why, * how much memory is estimated to be required. The estimate can be used when deciding the appropriate value for model_memory_limit setting later on. If you have object fields or fields that are excluded via source filtering, they are not included in the explanation.

Endpoint documentation

client.ml.explainDataFrameAnalytics({ ... })

Force buffered data to be processed. The flush jobs API is only applicable when sending data for analysis using the post data API. Depending on the content of the buffer, then it might additionally calculate new results. Both flush and close operations are similar, however the flush is more efficient if you are expecting to send more data for analysis. When flushing, the job remains open and is available to continue analyzing data. A close operation additionally prunes and persists the model state to disk and the job must be opened again before analyzing further data.

Endpoint documentation

client.ml.flushJob({ job_id })

Predict future behavior of a time series.

Forecasts are not supported for jobs that perform population analysis; an error occurs if you try to create a forecast for a job that has an over_field_name in its configuration. Forcasts predict future behavior based on historical data.

Endpoint documentation

client.ml.forecast({ job_id })

Get anomaly detection job results for buckets. The API presents a chronological view of the records, grouped by bucket.

Endpoint documentation

client.ml.getBuckets({ job_id })

Get info about events in calendars.

Endpoint documentation

client.ml.getCalendarEvents({ calendar_id })

Get calendar configuration info.

Endpoint documentation

client.ml.getCalendars({ ... })

Get anomaly detection job results for categories.

Endpoint documentation

client.ml.getCategories({ job_id })

Get data frame analytics job configuration info. You can get information for multiple data frame analytics jobs in a single API request by using a list of data frame analytics jobs or a wildcard expression.

Endpoint documentation

client.ml.getDataFrameAnalytics({ ... })

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 (Optional, number): Skips the specified number of data frame analytics jobs. size (Optional, number): Specifies the maximum number of data frame analytics jobs to obtain. * *exclude_generated (Optional, 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.

Get data frame analytics jobs usage info.

Endpoint documentation

client.ml.getDataFrameAnalyticsStats({ ... })

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 (Optional, number): Skips the specified number of data frame analytics jobs. size (Optional, number): Specifies the maximum number of data frame analytics jobs to obtain. * *verbose (Optional, boolean): Defines whether the stats response should be verbose.

Get datafeeds usage info. You can get statistics for multiple datafeeds in a single API request by using a list of datafeeds or a wildcard expression. You can get statistics for all datafeeds by using _all, by specifying * as the <feed_id>, or by omitting the <feed_id>. If the datafeed is stopped, the only information you receive is the datafeed_id and the state. This API returns a maximum of 10,000 datafeeds.

Endpoint documentation

client.ml.getDatafeedStats({ ... })

The default value is true, which returns an empty datafeeds 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.

Get datafeeds configuration info. You can get information for multiple datafeeds in a single API request by using a list of datafeeds or a wildcard expression. You can get information for all datafeeds by using _all, by specifying * as the <feed_id>, or by omitting the <feed_id>. This API returns a maximum of 10,000 datafeeds.

Endpoint documentation

client.ml.getDatafeeds({ ... })

The default value is true, which returns an empty datafeeds 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. * *exclude_generated (Optional, 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.

Get filters. You can get a single filter or all filters.

Endpoint documentation

client.ml.getFilters({ ... })

Get anomaly detection job results for influencers. Influencers are the entities that have contributed to, or are to blame for, the anomalies. Influencer results are available only if an influencer_field_name is specified in the job configuration.

Endpoint documentation

client.ml.getInfluencers({ job_id })

Get anomaly detection jobs usage info.

Endpoint documentation

client.ml.getJobStats({ ... })

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.

Get anomaly detection jobs configuration info. You can get information for multiple anomaly detection jobs in a single API request by using a group name, a list of jobs, or a wildcard expression. You can get information for all anomaly detection jobs by using _all, by specifying * as the <job_id>, or by omitting the <job_id>.

Endpoint documentation

client.ml.getJobs({ ... })

The default value is true, which returns an empty jobs 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. * *exclude_generated (Optional, 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.

Get machine learning memory usage info. Get information about how machine learning jobs and trained models are using memory, on each node, both within the JVM heap, and natively, outside of the JVM.

Endpoint documentation

client.ml.getMemoryStats({ ... })

Get anomaly detection job model snapshot upgrade usage info.

Endpoint documentation

client.ml.getModelSnapshotUpgradeStats({ job_id, snapshot_id })

The default value is true, which returns an empty jobs 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.

Get model snapshots info.

Endpoint documentation

client.ml.getModelSnapshots({ job_id })

Get overall bucket results.

Retrievs overall bucket results that summarize the bucket results of multiple anomaly detection jobs.

The overall_score is calculated by combining the scores of all the buckets within the overall bucket span. First, the maximum anomaly_score per anomaly detection job in the overall bucket is calculated. Then the top_n of those scores are averaged to result in the overall_score. This means that you can fine-tune the overall_score so that it is more or less sensitive to the number of jobs that detect an anomaly at the same time. For example, if you set top_n to 1, the overall_score is the maximum bucket score in the overall bucket. Alternatively, if you set top_n to the number of jobs, the overall_score is high only when all jobs detect anomalies in that overall bucket. If you set the bucket_span parameter (to a value greater than its default), the overall_score is the maximum overall_score of the overall buckets that have a span equal to the jobs' largest bucket span.

Endpoint documentation

client.ml.getOverallBuckets({ job_id })

You can summarize the bucket results for all anomaly detection jobs by using _all or by specifying * as the <job_id>. allow_no_match (Optional, boolean): Refer to the description for the allow_no_match query parameter. bucket_span (Optional, string | -1 | 0): Refer to the description for the bucket_span query parameter. end (Optional, string | Unit): Refer to the description for the end query parameter. exclude_interim (Optional, boolean): Refer to the description for the exclude_interim query parameter. overall_score (Optional, number | string): Refer to the description for the overall_score query parameter. start (Optional, string | Unit): Refer to the description for the start query parameter. * *top_n (Optional, number): Refer to the description for the top_n query parameter.

Get anomaly records for an anomaly detection job. Records contain the detailed analytical results. They describe the anomalous activity that has been identified in the input data based on the detector configuration. There can be many anomaly records depending on the characteristics and size of the input data. In practice, there are often too many to be able to manually process them. The machine learning features therefore perform a sophisticated aggregation of the anomaly records into buckets. The number of record results depends on the number of anomalies found in each bucket, which relates to the number of time series being modeled and the number of detectors.

Endpoint documentation

client.ml.getRecords({ job_id })

Get trained model configuration info.

Endpoint documentation

client.ml.getTrainedModels({ ... })

You can get information for multiple trained models in a single API request by using a list of model IDs or a wildcard expression. * *allow_no_match (Optional, boolean): Specifies what to do when the request:

If true, it returns an empty array when there are no matches and the subset of results when there are partial matches. decompress_definition (Optional, boolean): Specifies whether the included model definition should be returned as a JSON map (true) or in a custom compressed format (false). exclude_generated (Optional, 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. from (Optional, number): Skips the specified number of models. include (Optional, Enum("definition" | "feature_importance_baseline" | "hyperparameters" | "total_feature_importance" | "definition_status")): A comma delimited string of optional fields to include in the response body. include_model_definition (Optional, boolean): parameter is deprecated! Use [include=definition] instead size (Optional, number): Specifies the maximum number of models to obtain. * *tags (Optional, string | string[]): A comma delimited string of tags. A trained model can have many tags, or none. When supplied, only trained models that contain all the supplied tags are returned.

Get trained models usage info. You can get usage information for multiple trained models in a single API request by using a list of model IDs or a wildcard expression.

Endpoint documentation

client.ml.getTrainedModelsStats({ ... })

If true, it returns an empty array when there are no matches and the subset of results when there are partial matches. from (Optional, number): Skips the specified number of models. size (Optional, number): Specifies the maximum number of models to obtain.

Evaluate a trained model.

Endpoint documentation

client.ml.inferTrainedModel({ model_id, docs })

Get machine learning information. Get defaults and limits used by machine learning. This endpoint is designed to be used by a user interface that needs to fully understand machine learning configurations where some options are not specified, meaning that the defaults should be used. This endpoint may be used to find out what those defaults are. It also provides information about the maximum size of machine learning jobs that could run in the current cluster configuration.

Endpoint documentation

client.ml.info()

Open anomaly detection jobs.

An anomaly detection job must be opened to be ready to receive and analyze data. It can be opened and closed multiple times throughout its lifecycle. When you open a new job, it starts with an empty model. When you open an existing job, the most recent model state is automatically loaded. The job is ready to resume its analysis from where it left off, once new data is received.

Endpoint documentation

client.ml.openJob({ job_id })

Add scheduled events to the calendar.

Endpoint documentation

client.ml.postCalendarEvents({ calendar_id, events })

Send data to an anomaly detection job for analysis.

Endpoint documentation

client.ml.postData({ job_id })

Preview features used by data frame analytics. Preview the extracted features used by a data frame analytics config.

Endpoint documentation

client.ml.previewDataFrameAnalytics({ ... })

Preview a datafeed. This API returns the first "page" of search results from a datafeed. You can preview an existing datafeed or provide configuration details for a datafeed and anomaly detection job in the API. The preview shows the structure of the data that will be passed to the anomaly detection engine. IMPORTANT: When Elasticsearch security features are enabled, the preview uses the credentials of the user that called the API. However, when the datafeed starts it uses the roles of the last user that created or updated the datafeed. To get a preview that accurately reflects the behavior of the datafeed, use the appropriate credentials. You can also use secondary authorization headers to supply the credentials.

Endpoint documentation

client.ml.previewDatafeed({ ... })

Create a calendar.

Endpoint documentation

client.ml.putCalendar({ calendar_id })

Add anomaly detection job to calendar.

Endpoint documentation

client.ml.putCalendarJob({ calendar_id, job_id })

Create a data frame analytics job. This API creates a data frame analytics job that performs an analysis on the source indices and stores the outcome in a destination index. By default, the query used in the source configuration is {"match_all": {}}.

If the destination index does not exist, it is created automatically when you start the job.

If you supply only a subset of the regression or classification parameters, hyperparameter optimization occurs. It determines a value for each of the undefined parameters.

Endpoint documentation

client.ml.putDataFrameAnalytics({ id, analysis, dest, source })

Create a datafeed. Datafeeds retrieve data from Elasticsearch for analysis by an anomaly detection job. You can associate only one datafeed with each anomaly detection job. The datafeed contains a query that runs at a defined interval (frequency). If you are concerned about delayed data, you can add a delay (query_delay') at each interval. By default, the datafeed uses the following query: `{"match_all": {"boost": 1}}.

When Elasticsearch security features are enabled, your datafeed remembers which roles the user who created it had at the time of creation and runs the query using those same roles. If you provide secondary authorization headers, those credentials are used instead. You must use Kibana, this API, or the create anomaly detection jobs API to create a datafeed. Do not add a datafeed directly to the .ml-config index. Do not give users write privileges on the .ml-config index.

Endpoint documentation

client.ml.putDatafeed({ datafeed_id })

Create a filter. A filter contains a list of strings. It can be used by one or more anomaly detection jobs. Specifically, filters are referenced in the custom_rules property of detector configuration objects.

Endpoint documentation

client.ml.putFilter({ filter_id })

Create an anomaly detection job.

If you include a datafeed_config, you must have read index privileges on the source index. If you include a datafeed_config but do not provide a query, the datafeed uses {"match_all": {"boost": 1}}.

Endpoint documentation

client.ml.putJob({ job_id, analysis_config, data_description })

Create a trained model. Enable you to supply a trained model that is not created by data frame analytics.

Endpoint documentation

client.ml.putTrainedModel({ model_id })

Create or update a trained model alias. A trained model alias is a logical name used to reference a single trained model. You can use aliases instead of trained model identifiers to make it easier to reference your models. For example, you can use aliases in inference aggregations and processors. An alias must be unique and refer to only a single trained model. However, you can have multiple aliases for each trained model. If you use this API to update an alias such that it references a different trained model ID and the model uses a different type of data frame analytics, an error occurs. For example, this situation occurs if you have a trained model for regression analysis and a trained model for classification analysis; you cannot reassign an alias from one type of trained model to another. If you use this API to update an alias and there are very few input fields in common between the old and new trained models for the model alias, the API returns a warning.

Endpoint documentation

client.ml.putTrainedModelAlias({ model_alias, model_id })

Create part of a trained model definition.

Endpoint documentation

client.ml.putTrainedModelDefinitionPart({ model_id, part, definition, total_definition_length, total_parts })

Create a trained model vocabulary. This API is supported only for natural language processing (NLP) models. The vocabulary is stored in the index as described in inference_config.*.vocabulary of the trained model definition.

Endpoint documentation

client.ml.putTrainedModelVocabulary({ model_id, vocabulary })

Reset an anomaly detection job. All model state and results are deleted. The job is ready to start over as if it had just been created. It is not currently possible to reset multiple jobs using wildcards or a comma separated list.

Endpoint documentation

client.ml.resetJob({ job_id })

Revert to a snapshot. The machine learning features react quickly to anomalous input, learning new behaviors in data. Highly anomalous input increases the variance in the models whilst the system learns whether this is a new step-change in behavior or a one-off event. In the case where this anomalous input is known to be a one-off, then it might be appropriate to reset the model state to a time before this event. For example, you might consider reverting to a saved snapshot after Black Friday or a critical system failure.

Endpoint documentation

client.ml.revertModelSnapshot({ job_id, snapshot_id })

Set upgrade_mode for ML indices. Sets a cluster wide upgrade_mode setting that prepares machine learning indices for an upgrade. When upgrading your cluster, in some circumstances you must restart your nodes and reindex your machine learning indices. In those circumstances, there must be no machine learning jobs running. You can close the machine learning jobs, do the upgrade, then open all the jobs again. Alternatively, you can use this API to temporarily halt tasks associated with the jobs and datafeeds and prevent new jobs from opening. You can also use this API during upgrades that do not require you to reindex your machine learning indices, though stopping jobs is not a requirement in that case. You can see the current value for the upgrade_mode setting by using the get machine learning info API.

Endpoint documentation

client.ml.setUpgradeMode({ ... })

Start a data frame analytics job. A data frame analytics job can be started and stopped multiple times throughout its lifecycle. If the destination index does not exist, it is created automatically the first time you start the data frame analytics job. The index.number_of_shards and index.number_of_replicas settings for the destination index are copied from the source index. If there are multiple source indices, the destination index copies the highest setting values. The mappings for the destination index are also copied from the source indices. If there are any mapping conflicts, the job fails to start. If the destination index exists, it is used as is. You can therefore set up the destination index in advance with custom settings and mappings.

Endpoint documentation

client.ml.startDataFrameAnalytics({ id })

Start datafeeds.

A datafeed must be started in order to retrieve data from Elasticsearch. A datafeed can be started and stopped multiple times throughout its lifecycle.

Before you can start a datafeed, the anomaly detection job must be open. Otherwise, an error occurs.

If you restart a stopped datafeed, it continues processing input data from the next millisecond after it was stopped. If new data was indexed for that exact millisecond between stopping and starting, it will be ignored.

When Elasticsearch security features are enabled, your datafeed remembers which roles the last user to create or update it had at the time of creation or update and runs the query using those same roles. If you provided secondary authorization headers when you created or updated the datafeed, those credentials are used instead.

Endpoint documentation

client.ml.startDatafeed({ datafeed_id })

Start a trained model deployment. It allocates the model to every machine learning node.

Endpoint documentation

client.ml.startTrainedModelDeployment({ model_id })

Stop data frame analytics jobs. A data frame analytics job can be started and stopped multiple times throughout its lifecycle.

Endpoint documentation

client.ml.stopDataFrameAnalytics({ id })

The default value is true, which 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. force (Optional, boolean): If true, the data frame analytics job is stopped forcefully. timeout (Optional, string | -1 | 0): Controls the amount of time to wait until the data frame analytics job stops. Defaults to 20 seconds.

Stop datafeeds. A datafeed that is stopped ceases to retrieve data from Elasticsearch. A datafeed can be started and stopped multiple times throughout its lifecycle.

Endpoint documentation

client.ml.stopDatafeed({ datafeed_id })

Stop a trained model deployment.

Endpoint documentation

client.ml.stopTrainedModelDeployment({ model_id })

Update a data frame analytics job.

Endpoint documentation

client.ml.updateDataFrameAnalytics({ id })

Update a datafeed. You must stop and start the datafeed for the changes to be applied. When Elasticsearch security features are enabled, your datafeed remembers which roles the user who updated it had at the time of the update and runs the query using those same roles. If you provide secondary authorization headers, those credentials are used instead.

Endpoint documentation

client.ml.updateDatafeed({ datafeed_id })

Update a filter. Updates the description of a filter, adds items, or removes items from the list.

Endpoint documentation

client.ml.updateFilter({ filter_id })

Update an anomaly detection job. Updates certain properties of an anomaly detection job.

Endpoint documentation

client.ml.updateJob({ job_id })

Update a snapshot. Updates certain properties of a snapshot.

Endpoint documentation

client.ml.updateModelSnapshot({ job_id, snapshot_id })

Update a trained model deployment.

Endpoint documentation

client.ml.updateTrainedModelDeployment({ model_id })

Upgrade a snapshot. Upgrade an anomaly detection model snapshot to the latest major version. Over time, older snapshot formats are deprecated and removed. Anomaly detection jobs support only snapshots that are from the current or previous major version. This API provides a means to upgrade a snapshot to the current major version. This aids in preparing the cluster for an upgrade to the next major version. Only one snapshot per anomaly detection job can be upgraded at a time and the upgraded snapshot cannot be the current snapshot of the anomaly detection job.

Endpoint documentation

client.ml.upgradeJobSnapshot({ job_id, snapshot_id })

Clear the archived repositories metering. Clear the archived repositories metering information in the cluster.

Endpoint documentation

client.nodes.clearRepositoriesMeteringArchive({ node_id, max_archive_version })