Rollup

Delete a behavioral analytics collection Deprecated Technical preview

DELETE /_application/analytics/{name}

Api key auth Basic auth Bearer auth

The associated data stream is also deleted.

Path parameters

name string Required

The name of the analytics collection to be deleted

Responses

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

DELETE /_application/analytics/{name}

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

Get aliases

GET /_cat/aliases/{name}

Api key auth Basic auth Bearer auth

Get the cluster's index aliases, including filter and routing information. This API does not return data stream aliases.

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

Path parameters

name string | array[string] Required

A comma-separated list of aliases to retrieve. Supports wildcards (*). To retrieve all aliases, omit this parameter or use * or _all.

Query parameters

h string | array[string]

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

List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.
expand_wildcards string | array[string]
The 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. It supports comma-separated values, such as open,hidden.

Supported values include:
- all: Match any data stream or index, including hidden ones.
- open: Match open, non-hidden indices. Also matches any non-hidden data stream.
- closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
- hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
- none: Wildcard expressions are not accepted.
Values are all, open, closed, hidden, or none.
master_timeout string

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. To indicated that the request should never timeout, you can set it to -1.

Values are -1 or 0.

Responses

200 application/json
Hide response attributes Show response attributes object
- alias string
  
  alias name
- index string
- filter string
  
  filter
- routing.index string
  
  index routing
- routing.search string
  
  search routing
- is_write_index string
  
  write index

GET /_cat/aliases/{name}

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

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

Response examples (200)

A successful response from `GET _cat/aliases?format=json&v=true`. This response shows that `alias2` has configured a filter and `alias3` and `alias4` have routing configurations.

[
  {
    "alias": "alias1",
    "index": "test1",
    "filter": "-",
    "routing.index": "-",
    "routing.search": "-",
    "is_write_index": "true"
  },
  {
    "alias": "alias1",
    "index": "test1",
    "filter": "*",
    "routing.index": "-",
    "routing.search": "-",
    "is_write_index": "true"
  },
  {
    "alias": "alias3",
    "index": "test1",
    "filter": "-",
    "routing.index": "1",
    "routing.search": "1",
    "is_write_index": "true"
  },
  {
    "alias": "alias4",
    "index": "test1",
    "filter": "-",
    "routing.index": "2",
    "routing.search": "1,2",
    "is_write_index": "true"
  }
]

Get component templates Added in 5.1.0

GET /_cat/component_templates

Api key auth Basic auth Bearer auth

Get information about component templates in a cluster. Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

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

Query parameters

h string | array[string]

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

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

If true, the request computes the list of selected nodes from the local cluster state. If false the list of selected nodes are computed from the cluster state of the master node. In both cases the coordinating node will send requests for further information to each selected node.
master_timeout string

The period to wait for a connection to the master node.

Values are -1 or 0.

Responses

200 application/json
Hide response attributes Show response attributes object
- name string Required
- version string | null Required
  
  One of:
  string-1 string string-2 string | null
- alias_count string Required
- mapping_count string Required
- settings_count string Required
- metadata_count string Required
- included_in string Required

GET /_cat/component_templates

GET _cat/component_templates/my-template-*?v=true&s=name&format=json

curl \
 --request GET 'http://api.example.com/_cat/component_templates' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `GET _cat/component_templates/my-template-*?v=true&s=name&format=json`.

[
  {
    "name": "my-template-1",
    "version": "null",
    "alias_count": "0",
    "mapping_count": "0",
    "settings_count": "1",
    "metadata_count": "0",
    "included_in": "[my-index-template]"
  },
    {
    "name": "my-template-2",
    "version": null,
    "alias_count": "0",
    "mapping_count": "3",
    "settings_count": "0",
    "metadata_count": "0",
    "included_in": "[my-index-template]"
  }
]

Get pending task information

GET /_cat/pending_tasks

Api key auth Basic auth Bearer auth

Get information about cluster-level changes that have not yet taken effect. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the pending cluster tasks API.

Query parameters

h string | array[string]

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

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

If true, the request computes the list of selected nodes from the local cluster state. If false the list of selected nodes are computed from the cluster state of the master node. In both cases the coordinating node will send requests for further information to each selected node.
master_timeout string

Period to wait for a connection to the master node.

Values are -1 or 0.
time string

Unit used to display time values.

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

Responses

200 application/json
Hide response attributes Show response attributes object
- insertOrder string
  
  The task insertion order.
- timeInQueue string
  
  Indicates how long the task has been in queue.
- priority string
  
  The task priority.
- source string
  
  The task source.

GET /_cat/pending_tasks

GET /_cat/pending_tasks?v=trueh=insertOrder,timeInQueue,priority,source&format=json

curl \
 --request GET 'http://api.example.com/_cat/pending_tasks' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `GET /_cat/pending_tasks?v=trueh=insertOrder,timeInQueue,priority,source&format=json`.

[
  { "insertOrder": "1685", "timeInQueue": "855ms", "priority": "HIGH", "source": "update-mapping [foo][t]"},
    { "insertOrder": "1686", "timeInQueue": "843ms", "priority": "HIGH", "source": "update-mapping [foo][t]"},
    { "insertOrder": "1693", "timeInQueue": "753ms", "priority": "HIGH", "source": "refresh-mapping [foo][[t]]"},
    { "insertOrder": "1688", "timeInQueue": "816ms", "priority": "HIGH", "source": "update-mapping [foo][t]"},
    { "insertOrder": "1689", "timeInQueue": "802ms", "priority": "HIGH", "source": "update-mapping [foo][t]"},
    { "insertOrder": "1690", "timeInQueue": "787ms", "priority": "HIGH", "source": "update-mapping [foo][t]"},
    { "insertOrder": "1691", "timeInQueue": "773ms", "priority": "HIGH", "source": "update-mapping [foo][t]"}
]

Get the hot threads for nodes

GET /_nodes/hot_threads

Api key auth Basic auth Bearer auth

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

Query parameters

ignore_idle_threads boolean

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

The interval to do the second sampling of threads.

Values are -1 or 0.
snapshots number

Number of samples of thread stacktrace.
threads number

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

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

Values are -1 or 0.
type string

The type to sample.

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

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

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

Responses

200 application/json

GET /_nodes/hot_threads

curl \
 --request GET 'http://api.example.com/_nodes/hot_threads' \
 --header "Authorization: $API_KEY"

Get node information Added in 1.3.0

GET /_nodes/{node_id}

Api key auth Basic auth Bearer auth

By default, the API returns all attributes and core settings for cluster nodes.

Path parameters

node_id string | array[string] Required

Comma-separated list of node IDs or names used to limit returned information.

Query parameters

flat_settings boolean

If true, returns settings in flat format.
timeout string

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

Values are -1 or 0.

Responses

200 application/json
Hide response attributes Show response attributes object
- _nodes object
  
  Hide _nodes attributes Show _nodes attributes object
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  total number Required
  
  Total number of nodes selected by the request.
  
  successful number Required
  
  Number of nodes that responded successfully to the request.
  
  failed number Required
  
  Number of nodes that rejected the request or failed to respond. If this value is not 0, a reason for the rejection or failure is included in the response.
- cluster_name string Required
- nodes object Required
  
  Hide nodes attribute Show nodes attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  attributes object Required
  
  Hide attributes attribute Show attributes attribute object
  
  * string Additional properties
  
  build_flavor string Required
  
  build_hash string Required
  
  Short hash of the last git commit in this release.
  
  build_type string Required
  
  host string Required
  
  http object
  
  Hide http attributes Show http attributes object
  
  bound_address array[string] Required
  
  max_content_length number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_content_length_in_bytes number Required
  
  publish_address string Required
  
  ip string Required
  
  jvm object
  
  Hide jvm attributes Show jvm attributes object
  
  gc_collectors array[string] Required
  
  mem object Required
  
  Hide mem attributes Show mem attributes object
  
  direct_max
  
  direct_max_in_bytes number Required
  
  heap_init
  
  heap_init_in_bytes number Required
  
  heap_max
  
  heap_max_in_bytes number Required
  
  non_heap_init
  
  non_heap_init_in_bytes number Required
  
  non_heap_max
  
  non_heap_max_in_bytes number Required
  
  memory_pools array[string] Required
  
  pid number Required
  
  Time unit for milliseconds
  
  version string Required
  
  vm_name string Required
  
  vm_vendor string Required
  
  vm_version string Required
  
  using_bundled_jdk boolean Required
  
  using_compressed_ordinary_object_pointers boolean | string
  
  One of:
  boolean-1 boolean string-2 string
  
  input_arguments array[string] Required
  
  name string Required
  
  network object
  
  Hide network attributes Show network attributes object
  
  primary_interface object Required
  
  Hide primary_interface attributes Show primary_interface attributes object
  
  address string Required
  
  mac_address string Required
  
  name string Required
  
  refresh_interval number Required
  
  os object
  
  Hide os attributes Show os attributes object
  
  arch string Required
  
  Name of the JVM architecture (ex: amd64, x86)
  
  available_processors number Required
  
  Number of processors available to the Java virtual machine
  
  allocated_processors number
  
  The number of processors actually used to calculate thread pool size. This number can be set with the node.processors setting of a node and defaults to the number of processors reported by the OS.
  
  name string Required
  
  pretty_name string Required
  
  Time unit for milliseconds
  
  version string Required
  
  cpu object
  
  Hide cpu attributes Show cpu attributes object
  
  cache_size string Required
  
  cache_size_in_bytes number Required
  
  cores_per_socket number Required
  
  mhz number Required
  
  model string Required
  
  total_cores number Required
  
  total_sockets number Required
  
  vendor string Required
  
  mem object
  
  Hide mem attributes Show mem attributes object
  
  total string Required
  
  total_in_bytes number Required
  
  swap object
  
  Hide swap attributes Show swap attributes object
  
  total string Required
  
  total_in_bytes number Required
  
  plugins array[object]
  
  Hide plugins attributes Show plugins attributes object
  
  classname string Required
  
  description string Required
  
  elasticsearch_version string Required
  
  extended_plugins array[string] Required
  
  has_native_controller boolean Required
  
  java_version string Required
  
  name string Required
  
  version string Required
  
  licensed boolean Required
  
  process object
  
  Hide process attributes Show process attributes object
  
  id number Required
  
  Process identifier (PID)
  
  mlockall boolean Required
  
  Indicates if the process address space has been successfully locked in memory
  
  Time unit for milliseconds
  
  roles array[string] Required
  
  @doc_id node-roles
  
  Values are master, data, data_cold, data_content, data_frozen, data_hot, data_warm, client, ingest, ml, voting_only, transform, remote_cluster_client, or coordinating_only.
  
  settings object
  
  Hide settings attributes Show settings attributes object
  
  cluster object Required
  
  Hide cluster attributes Show cluster attributes object
  
  name string Required
  
  routing object
  
  election object Required
  
  initial_master_nodes array[string]
  
  deprecation_indexing object
  
  node object Required
  
  Hide node attributes Show node attributes object
  
  name string Required
  
  attr object Required
  
  max_local_storage_nodes string
  
  path object
  
  Hide path attributes Show path attributes object
  
  logs string
  
  home string
  
  repo array[string]
  
  data
  
  repositories object
  
  Hide repositories attribute Show repositories attribute object
  
  url object Required
  
  discovery object
  
  Hide discovery attributes Show discovery attributes object
  
  seed_hosts array[string]
  
  type string
  
  seed_providers array[string]
  
  action object
  
  Hide action attribute Show action attribute object
  
  destructive_requires_name string Required
  
  client object
  
  Hide client attribute Show client attribute object
  
  type string Required
  
  http object Required
  
  Hide http attributes Show http attributes object
  
  type object Required
  
  type.default string
  
  compression
  
  port
  
  bootstrap object
  
  Hide bootstrap attribute Show bootstrap attribute object
  
  memory_lock string Required
  
  transport object Required
  
  Hide transport attributes Show transport attributes object
  
  type object Required
  
  type.default string
  
  features object
  
  network object
  
  Hide network attribute Show network attribute object
  
  host
  
  xpack object
  
  Hide xpack attributes Show xpack attributes object
  
  license object
  
  security object Required
  
  notification object
  
  ml object
  
  script object
  
  Hide script attributes Show script attributes object
  
  allowed_types string Required
  
  disable_max_compilations_rate string
  
  search object
  
  Hide search attribute Show search attribute object
  
  remote object Required
  
  ingest object
  
  Hide ingest attributes Show ingest attributes object
  
  attachment object
  
  append object
  
  csv object
  
  convert object
  
  date object
  
  date_index_name object
  
  dot_expander object
  
  enrich object
  
  fail object
  
  foreach object
  
  json object
  
  user_agent object
  
  kv object
  
  geoip object
  
  grok object
  
  gsub object
  
  join object
  
  lowercase object
  
  remove object
  
  rename object
  
  script object
  
  set object
  
  sort object
  
  split object
  
  trim object
  
  uppercase object
  
  urldecode object
  
  bytes object
  
  dissect object
  
  set_security_user object
  
  pipeline object
  
  drop object
  
  circle object
  
  inference object
  
  thread_pool object
  
  Hide thread_pool attribute Show thread_pool attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  core number
  
  keep_alive string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  max number
  
  queue_size number Required
  
  size number
  
  type string Required
  
  total_indexing_buffer number
  
  Total heap allowed to be used to hold recently indexed documents before they must be written to disk. This size is a shared pool across all shards on this node, and is controlled by Indexing Buffer settings.
  
  total_indexing_buffer_in_bytes number | string
  
  One of:
  ByteSize number ByteSize string
  
  transport object
  
  Hide transport attributes Show transport attributes object
  
  bound_address array[string] Required
  
  publish_address string Required
  
  profiles object Required
  
  Hide profiles attribute Show profiles attribute object
  
  * string Additional properties
  
  transport_address string Required
  
  version string Required
  
  modules array[object]
  
  Hide modules attributes Show modules attributes object
  
  classname string Required
  
  description string Required
  
  elasticsearch_version string Required
  
  extended_plugins array[string] Required
  
  has_native_controller boolean Required
  
  java_version string Required
  
  name string Required
  
  version string Required
  
  licensed boolean Required
  
  ingest object
  
  Hide ingest attribute Show ingest attribute object
  
  processors array[object] Required
  
  aggregations object
  
  Hide aggregations attribute Show aggregations attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  types array[string] Required

GET /_nodes/{node_id}

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

Response examples (200)

An abbreviated response when requesting cluster nodes information.

{
    "_nodes": {},
    "cluster_name": "elasticsearch",
    "nodes": {
      "USpTGYaBSIKbgSUJR2Z9lg": {
        "name": "node-0",
        "transport_address": "192.168.17:9300",
        "host": "node-0.elastic.co",
        "ip": "192.168.17",
        "version": "{version}",
        "transport_version": 100000298,
        "index_version": 100000074,
        "component_versions": {
          "ml_config_version": 100000162,
          "transform_config_version": 100000096
        },
        "build_flavor": "default",
        "build_type": "{build_type}",
        "build_hash": "587409e",
        "roles": [
          "master",
          "data",
          "ingest"
        ],
        "attributes": {},
        "plugins": [
          {
            "name": "analysis-icu",
            "version": "{version}",
            "description": "The ICU Analysis plugin integrates Lucene ICU
  module into elasticsearch, adding ICU relates analysis components.",
            "classname":
  "org.elasticsearch.plugin.analysis.icu.AnalysisICUPlugin",
            "has_native_controller": false
          }
        ],
        "modules": [
          {
            "name": "lang-painless",
            "version": "{version}",
            "description": "An easy, safe and fast scripting language for
  Elasticsearch",
            "classname": "org.elasticsearch.painless.PainlessPlugin",
            "has_native_controller": false
          }
        ]
      }
    }
}

Cancel a connector sync job Beta

PUT /_connector/_sync_job/{connector_sync_job_id}/_cancel

Api key auth Basic auth Bearer auth

Cancel a connector sync job, which sets the status to cancelling and updates cancellation_requested_at to the current time. The connector service is then responsible for setting the status of connector sync jobs to cancelled.

Path parameters

connector_sync_job_id string Required

The unique identifier of the connector sync job

Responses

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

PUT /_connector/_sync_job/{connector_sync_job_id}/_cancel

curl \
 --request PUT 'http://api.example.com/_connector/_sync_job/{connector_sync_job_id}/_cancel' \
 --header "Authorization: $API_KEY"

Get cross-cluster replication stats Added in 6.5.0

GET /_ccr/stats

Api key auth Basic auth Bearer auth

This API returns stats about auto-following and the same shard-level stats as the get follower stats API.

Query parameters

master_timeout string

The period to wait for a connection to the master node. If the master node is not available before the timeout expires, the request fails and returns an error. It can also be set to -1 to indicate that the request should never timeout.

Values are -1 or 0.
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.

Values are -1 or 0.

Responses

200 application/json
Hide response attributes Show response attributes object
- auto_follow_stats object Required
  
  Hide auto_follow_stats attributes Show auto_follow_stats attributes object
  
  auto_followed_clusters array[object] Required
  
  Hide auto_followed_clusters attributes Show auto_followed_clusters attributes object
  
  cluster_name string Required
  
  last_seen_metadata_version number Required
  
  time_since_last_check_millis number
  
  Time unit for milliseconds
  
  number_of_failed_follow_indices number Required
  
  The number of indices that the auto-follow coordinator failed to automatically follow. The causes of recent failures are captured in the logs of the elected master node and in the auto_follow_stats.recent_auto_follow_errors field.
  
  number_of_failed_remote_cluster_state_requests number Required
  
  The number of times that the auto-follow coordinator failed to retrieve the cluster state from a remote cluster registered in a collection of auto-follow patterns.
  
  number_of_successful_follow_indices number Required
  
  The number of indices that the auto-follow coordinator successfully followed.
  
  recent_auto_follow_errors array[object] Required
  
  An array of objects representing failures by the auto-follow coordinator.
  
  Hide recent_auto_follow_errors attributes Show recent_auto_follow_errors attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
- follow_stats object Required
  
  Hide follow_stats attribute Show follow_stats attribute object
  
  indices array[object] Required
  
  Hide indices attributes Show indices attributes object
  
  index string Required
  
  shards array[object] Required
  
  An array of shard-level following task statistics.
  
  Hide shards attributes Show shards attributes object
  
  bytes_read number Required
  
  The total of transferred bytes read from the leader. This is only an estimate and does not account for compression if enabled.
  
  failed_read_requests number Required
  
  The number of failed reads.
  
  failed_write_requests number Required
  
  The number of failed bulk write requests on the follower.
  
  fatal_exception object
  
  follower_aliases_version number Required
  
  follower_global_checkpoint number Required
  
  The current global checkpoint on the follower. The difference between the leader_global_checkpoint and the follower_global_checkpoint is an indication of how much the follower is lagging the leader.
  
  follower_index string Required
  
  The name of the follower index.
  
  follower_mapping_version number Required
  
  follower_max_seq_no number Required
  
  follower_settings_version number Required
  
  last_requested_seq_no number Required
  
  leader_global_checkpoint number Required
  
  The current global checkpoint on the leader known to the follower task.
  
  leader_index string Required
  
  The name of the index in the leader cluster being followed.
  
  leader_max_seq_no number Required
  
  operations_read number Required
  
  The total number of operations read from the leader.
  
  operations_written number Required
  
  The number of operations written on the follower.
  
  outstanding_read_requests number Required
  
  The number of active read requests from the follower.
  
  outstanding_write_requests number Required
  
  The number of active bulk write requests on the follower.
  
  read_exceptions array[object] Required
  
  An array of objects representing failed reads.
  
  remote_cluster string Required
  
  The remote cluster containing the leader index.
  
  shard_id number Required
  
  The numerical shard ID, with values from 0 to one less than the number of replicas.
  
  successful_read_requests number Required
  
  The number of successful fetches.
  
  successful_write_requests number Required
  
  The number of bulk write requests run on the follower.
  
  time_since_last_read string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  time_since_last_read_millis
  
  total_read_remote_exec_time string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  total_read_remote_exec_time_millis
  
  total_read_time string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  total_read_time_millis
  
  total_write_time string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  total_write_time_millis
  
  write_buffer_operation_count number Required
  
  The number of write operations queued on the follower.
  
  write_buffer_size_in_bytes

GET /_ccr/stats

GET /_ccr/stats

curl \
 --request GET 'http://api.example.com/_ccr/stats' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `GET /_ccr/stats` that returns cross-cluster replication stats.

{
  "auto_follow_stats" : {
    "number_of_failed_follow_indices" : 0,
    "number_of_failed_remote_cluster_state_requests" : 0,
    "number_of_successful_follow_indices" : 1,
    "recent_auto_follow_errors" : [],
    "auto_followed_clusters" : []
  },
  "follow_stats" : {
    "indices" : [
      {
        "index" : "follower_index",
        "total_global_checkpoint_lag" : 256,
        "shards" : [
          {
            "remote_cluster" : "remote_cluster",
            "leader_index" : "leader_index",
            "follower_index" : "follower_index",
            "shard_id" : 0,
            "leader_global_checkpoint" : 1024,
            "leader_max_seq_no" : 1536,
            "follower_global_checkpoint" : 768,
            "follower_max_seq_no" : 896,
            "last_requested_seq_no" : 897,
            "outstanding_read_requests" : 8,
            "outstanding_write_requests" : 2,
            "write_buffer_operation_count" : 64,
            "follower_mapping_version" : 4,
            "follower_settings_version" : 2,
            "follower_aliases_version" : 8,
            "total_read_time_millis" : 32768,
            "total_read_remote_exec_time_millis" : 16384,
            "successful_read_requests" : 32,
            "failed_read_requests" : 0,
            "operations_read" : 896,
            "bytes_read" : 32768,
            "total_write_time_millis" : 16384,
            "write_buffer_size_in_bytes" : 1536,
            "successful_write_requests" : 16,
            "failed_write_requests" : 0,
            "operations_written" : 832,
            "read_exceptions" : [ ],
            "time_since_last_read_millis" : 8
          }
        ]
      }
    ]
  }
}

Get a specific running ES|QL query information Technical preview

GET /_query/queries/{id}

Api key auth Basic auth Bearer auth

Returns an object extended information about a running ES|QL query.

Path parameters

id string Required

The query ID

Responses

200 application/json
Hide response attributes Show response attributes object
- id number Required
- node string Required
- start_time_millis number Required
- running_time_nanos number Required
- query string Required
- coordinating_node string Required
- data_nodes array[string] Required

GET /_query/queries/{id}

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

Create or update a component template Added in 7.8.0

POST /_component_template/{name}

Api key auth Basic auth Bearer auth

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

An index template can be composed of multiple component templates. To use a component template, specify it in an index template’s composed_of list. Component templates are only applied to new data streams and indices as part of a matching index template.

Settings and mappings specified directly in the index template or the create index request override any settings or mappings specified in a component template.

Component templates are only used during index creation. For data streams, this includes data stream creation and the creation of a stream’s backing indices. Changes to component templates do not affect existing indices, including a stream’s backing indices.

You can use C-style /* *\/ block comments in component templates. You can include comments anywhere in the request body except before the opening curly bracket.

Applying component templates

You cannot directly apply a component template to a data stream or index. To be applied, a component template must be included in an index template's composed_of list.

Path parameters

name string Required

Name of the component template to create. Elasticsearch includes the following built-in component templates: logs-mappings; logs-settings; metrics-mappings; metrics-settings;synthetics-mapping; synthetics-settings. Elastic Agent uses these templates to configure backing indices for its data streams. If you use Elastic Agent and want to overwrite one of these templates, set the version for your replacement template higher than the current version. If you don’t use Elastic Agent and want to disable all built-in component and index templates, set stack.templates.enabled to false using the cluster update settings API.

Query parameters

create boolean

If true, this request cannot replace or update existing component templates.
master_timeout string

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

Values are -1 or 0.

application/json

Body Required

template object Required
Hide template attributes Show template attributes object
- aliases object
  Hide aliases attribute Show aliases attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  index_routing string
  
  is_hidden boolean
  
  If true, the alias is hidden. All indices for the alias must have the same is_hidden value.
  
  is_write_index boolean
  
  If true, the index is the write index for the alias.
  
  routing string
  
  search_routing string
- mappings object
  Hide mappings attributes Show mappings attributes object
  
  all_field object
  
  Hide all_field attributes Show all_field attributes object
  
  analyzer string Required
  
  enabled boolean Required
  
  omit_norms boolean Required
  
  search_analyzer string Required
  
  similarity string Required
  
  store boolean Required
  
  store_term_vector_offsets boolean Required
  
  store_term_vector_payloads boolean Required
  
  store_term_vector_positions boolean Required
  
  store_term_vectors boolean Required
  
  date_detection boolean
  
  dynamic string
  
  Values are strict, runtime, true, or false.
  
  dynamic_date_formats array[string]
  
  dynamic_templates array[object]
  
  _field_names object
  
  Hide _field_names attribute Show _field_names attribute object
  
  enabled boolean Required
  
  index_field object
  
  Hide index_field attribute Show index_field attribute object
  
  enabled boolean Required
  
  _meta object
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
  
  numeric_detection boolean
  
  properties object
  
  _routing object
  
  Hide _routing attribute Show _routing attribute object
  
  required boolean Required
  
  _size object
  
  Hide _size attribute Show _size attribute object
  
  enabled boolean Required
  
  _source object
  
  Hide _source attributes Show _source attributes object
  
  compress boolean
  
  compress_threshold string
  
  enabled boolean
  
  excludes array[string]
  
  includes array[string]
  
  mode string
  
  Values are disabled, stored, or synthetic.
  
  runtime object
  
  Hide runtime attribute Show runtime attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string SearchRequestBody object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  enabled boolean
  
  subobjects string
  
  Values are true or false.
  
  _data_stream_timestamp object
  
  Hide _data_stream_timestamp attribute Show _data_stream_timestamp attribute object
  
  enabled boolean Required
- settings object
  Index settings
- defaults object
  Index settings
- data_stream string
- lifecycle object
  Hide lifecycle attributes Show lifecycle attributes object
  
  data_retention string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  downsampling object
  
  Hide downsampling attribute Show downsampling attribute object
  
  rounds array[object] Required
  
  The list of downsampling rounds to execute as part of this downsampling configuration
  
  Hide rounds attributes Show rounds attributes object
  
  after string Required
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  config object Required
  
  Hide config attribute Show config attribute object
  
  fixed_interval string Required
  
  A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)
  
  enabled boolean
  
  If defined, it turns data stream lifecycle on/off (true/false) for this data stream. A data stream lifecycle that's disabled (enabled: false) will have no effect on the data stream.
version number
_meta object
Hide _meta attribute Show _meta attribute object
- * object Additional properties
deprecated boolean

Marks this index template as deprecated. When creating or updating a non-deprecated index template that uses deprecated components, Elasticsearch will emit a deprecation warning.

Responses

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

POST /_component_template/{name}

PUT _component_template/template_1
{
  "template": null,
  "settings": {
    "number_of_shards": 1
  },
  "mappings": {
    "_source": {
      "enabled": false
    },
    "properties": {
      "host_name": {
        "type": "keyword"
      },
      "created_at": {
        "type": "date",
        "format": "EEE MMM dd HH:mm:ss Z yyyy"
      }
    }
  }
}

curl \
 --request POST 'http://api.example.com/_component_template/{name}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"template\": null,\n  \"settings\": {\n    \"number_of_shards\": 1\n  },\n  \"mappings\": {\n    \"_source\": {\n      \"enabled\": false\n    },\n    \"properties\": {\n      \"host_name\": {\n        \"type\": \"keyword\"\n      },\n      \"created_at\": {\n        \"type\": \"date\",\n        \"format\": \"EEE MMM dd HH:mm:ss Z yyyy\"\n      }\n    }\n  }\n}"'

Request examples

{
  "template": null,
  "settings": {
    "number_of_shards": 1
  },
  "mappings": {
    "_source": {
      "enabled": false
    },
    "properties": {
      "host_name": {
        "type": "keyword"
      },
      "created_at": {
        "type": "date",
        "format": "EEE MMM dd HH:mm:ss Z yyyy"
      }
    }
  }
}

You can include index aliases in a component template. During index creation, the `{index}` placeholder in the alias name will be replaced with the actual index name that the template gets applied to.

{
  "template": null,
  "settings": {
    "number_of_shards": 1
  },
  "aliases": {
    "alias1": {},
    "alias2": {
      "filter": {
        "term": {
          "user.id": "kimchy"
        }
      },
      "routing": "shard-1"
    },
    "{index}-alias": {}
  }
}

Get component templates Added in 7.8.0

GET /_component_template

Api key auth Basic auth Bearer auth

Get information about component templates.

Query parameters

flat_settings boolean

If true, returns settings in flat format.
include_defaults boolean

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

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

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

Values are -1 or 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- component_templates array[object] Required
  
  Hide component_templates attributes Show component_templates attributes object
  
  name string Required
  
  component_template object Required
  
  Hide component_template attributes Show component_template attributes object
  
  template object Required
  
  Hide template attributes Show template attributes object
  
  _meta object
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
  
  version number
  
  settings object
  
  Hide settings attribute Show settings attribute object
  
  * object
  
  mappings object
  
  Hide mappings attributes Show mappings attributes object
  
  all_field object
  
  date_detection boolean
  
  dynamic string
  
  Values are strict, runtime, true, or false.
  
  dynamic_date_formats array[string]
  
  dynamic_templates array[object]
  
  _field_names object
  
  index_field object
  
  _meta object
  
  numeric_detection boolean
  
  properties object
  
  _routing object
  
  _size object
  
  _source object
  
  runtime object
  
  enabled boolean
  
  subobjects string
  
  Values are true or false.
  
  _data_stream_timestamp object
  
  aliases object
  
  Hide aliases attribute Show aliases attribute object
  
  * object Additional properties
  
  lifecycle object
  
  data_stream_options object | string | null
  
  One of:
  DataStreamOptionsTemplate object string-2 string | null
  
  version number
  
  _meta object
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
  
  deprecated boolean

GET /_component_template

curl \
 --request GET 'http://api.example.com/_component_template' \
 --header "Authorization: $API_KEY"

Check index templates

HEAD /_index_template/{name}

Api key auth Basic auth Bearer auth

Check whether index templates exist.

Path parameters

name string Required

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

Query parameters

local boolean

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

If true, returns settings in flat format.
master_timeout string

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

Values are -1 or 0.

Responses

200 application/json

HEAD /_index_template/{name}

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

Force a merge Added in 2.1.0

POST /_forcemerge

Api key auth Basic auth Bearer auth

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

External documentation

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 with open, closed, or both.
- none: Wildcard expressions are not accepted.
Values are all, open, closed, hidden, or none.
flush boolean

Specify whether the index should be flushed after performing the operation (default: true)
ignore_unavailable boolean

Whether specified concrete indices should be ignored when unavailable (missing or closed)
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.

Responses

200 application/json
Hide response attributes Show response attributes object
- _shards object
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  shard number Required
  
  status string
  
  skipped number
- task string
  
  task contains a task id returned when wait_for_completion=false, you can use the task_id to get the status of the task at _tasks/

POST /_forcemerge

curl \
 --request POST 'http://api.example.com/_forcemerge' \
 --header "Authorization: $API_KEY"

Update index settings

PUT /{index}/_settings

Api key auth Basic auth Bearer auth

Changes dynamic index settings in real time. For data streams, index setting changes are applied to all backing indices by default.

To revert a setting to the default value, use a null value. The list of per-index settings that can be updated dynamically on live indices can be found in index settings documentation. To preserve existing settings from being updated, set the preserve_existing parameter to true.

There are multiple valid ways to represent index settings in the request body. You can specify only the setting, for example:

{
  "number_of_replicas": 1
}

Or you can use an index setting object:

{
  "index": {
    "number_of_replicas": 1
  }
}

Or you can use dot annotation:

{
  "index.number_of_replicas": 1
}

Or you can embed any of the aforementioned options in a settings object. For example:

{
  "settings": {
    "index": {
      "number_of_replicas": 1
    }
  }
}

NOTE: You can only define new analyzers on closed indices. To add an analyzer, you must close the index, define the analyzer, and reopen the index. You cannot close the write index of a data stream. To update the analyzer for a data stream's write index and future backing indices, update the analyzer in the index template used by the stream. Then roll over the data stream to apply the new analyzer to the stream's write index and future backing indices. This affects searches and any new data added to the stream after the rollover. However, it does not affect the data stream's backing indices or their existing data. To change the analyzer for existing backing indices, you must create a new data stream and reindex your data into it.

External documentation

Path parameters

index string | array[string] Required

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

Query parameters

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 targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.
expand_wildcards string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden.

Supported values include:
- all: Match any data stream or index, including hidden ones.
- open: Match open, non-hidden indices. Also matches any non-hidden data stream.
- closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
- hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
- none: Wildcard expressions are not accepted.
Values are all, open, closed, hidden, or none.
flat_settings boolean

If true, returns settings in flat format.
ignore_unavailable boolean

If true, returns settings in flat format.
master_timeout string

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

Values are -1 or 0.
preserve_existing boolean

If true, existing index settings remain unchanged.
reopen boolean

Whether to close and reopen the index to apply non-dynamic settings. If set to true the indices to which the settings are being applied will be closed temporarily and then reopened in order to apply the changes.
timeout string

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

Values are -1 or 0.

application/json

Body Required

object

Index settings

Responses

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

PUT /{index}/_settings

PUT /my-index-000001/_settings
{
  "index" : {
    "number_of_replicas" : 2
  }
}

curl \
 --request PUT 'http://api.example.com/{index}/_settings' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"index\" : {\n    \"number_of_replicas\" : 2\n  }\n}"'

Request examples

{
  "index" : {
    "number_of_replicas" : 2
  }
}

To revert a setting to the default value, use `null`.

{
  "index" : {
    "refresh_interval" : null
  }
}

To add an analyzer, you must close the index, define the analyzer, then reopen the index.

{
  "analysis" : {
    "analyzer":{
      "content":{
        "type":"custom",
        "tokenizer":"whitespace"
      }
    }
  }
}

POST /my-index-000001/_open

Get the ILM status Added in 6.6.0

GET /_ilm/status

Api key auth Basic auth Bearer auth

Get the current index lifecycle management status.

Responses

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

GET /_ilm/status

curl \
 --request GET 'http://api.example.com/_ilm/status' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response when retrieving the current ILM status.

{
  "operation_mode": "RUNNING"
}

Remove policies from an index Added in 6.6.0

POST /{index}/_ilm/remove

Api key auth Basic auth Bearer auth

Remove the assigned lifecycle policies from an index or a data stream's backing indices. It also stops managing the indices.

Path parameters

index string Required

The name of the index to remove policy on

Responses

200 application/json
Hide response attributes Show response attributes object
- failed_indexes array[string] Required
- has_failures boolean Required

POST /{index}/_ilm/remove

curl \
 --request POST 'http://api.example.com/{index}/_ilm/remove' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response when removing a lifecycle policy from an index.

{
  "has_failures" : false,
  "failed_indexes" : []
}

Stop the ILM plugin Added in 6.6.0

POST /_ilm/stop

Api key auth Basic auth Bearer auth

Halt all lifecycle management operations and stop the index lifecycle management plugin. This is useful when you are performing maintenance on the cluster and need to prevent ILM from performing any actions on your indices.

The API returns as soon as the stop request has been acknowledged, but the plugin might continue to run until in-progress operations complete and the plugin can be safely stopped. Use the get ILM status API to check whether ILM is running.

Query parameters

master_timeout string

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

Values are -1 or 0.
timeout string

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

Values are -1 or 0.

Responses

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

POST /_ilm/stop

curl \
 --request POST 'http://api.example.com/_ilm/stop' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response when stopping the ILM plugin.

{
  "acknowledged": true
}

Create an JinaAI inference endpoint Added in 8.18.0

PUT /_inference/{task_type}/{jinaai_inference_id}

Api key auth Basic auth Bearer auth

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

Path parameters

task_type string Required

The type of the inference task that the model will perform.

Values are rerank or text_embedding.
jinaai_inference_id string Required

The unique identifier of the inference endpoint.

application/json

Body

chunking_settings object
Hide chunking_settings attributes Show chunking_settings attributes object
- max_chunk_size number
  
  The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).
- overlap number
  
  The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.
- sentence_overlap number
  
  The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.
- strategy string
  
  The chunking strategy: sentence or word.
service string Required

Value is jinaai.
service_settings object Required
Hide service_settings attributes Show service_settings attributes object
- api_key string Required
  
  A valid API key of your JinaAI account.
  
  IMPORTANT: You need to provide the API key only once, during the inference model creation. The get inference endpoint API does not retrieve your API key. After creating the inference model, you cannot change the associated API key. If you want to use a different API key, delete the inference model and recreate it with the same name and the updated API key.
  
  External documentation
- model_id string
  
  The name of the model to use for the inference task. For a rerank task, it is required. For a text_embedding task, it is optional.
- rate_limit object
  Hide rate_limit attribute Show rate_limit attribute object
  
  requests_per_minute number
  
  The number of requests allowed per minute.
- similarity string
  
  Values are cosine, dot_product, or l2_norm.
task_settings object
Hide task_settings attributes Show task_settings attributes object
- return_documents boolean
  
  For a rerank task, return the doc text within the results.
- task string
  
  Values are classification, clustering, ingest, or search.
- top_n number
  
  For a rerank task, the number of most relevant documents to return. It defaults to the number of the documents. If this inference endpoint is used in a text_similarity_reranker retriever query and top_n is set, it must be greater than or equal to rank_window_size in the query.

Responses

200 application/json
Hide response attributes Show response attributes object
- chunking_settings object
  
  Hide chunking_settings attributes Show chunking_settings attributes object
  
  max_chunk_size number
  
  The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).
  
  overlap number
  
  The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.
  
  sentence_overlap number
  
  The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.
  
  strategy string
  
  The chunking strategy: sentence or word.
- service string Required
  
  The service type
- service_settings object Required
- task_settings object
- inference_id string Required
  
  The inference Id
- task_type string Required
  
  Values are text_embedding or rerank.

PUT /_inference/{task_type}/{jinaai_inference_id}

PUT _inference/text_embedding/jinaai-embeddings
{
    "service": "jinaai",
    "service_settings": {
        "model_id": "jina-embeddings-v3",
        "api_key": "JinaAi-Api-key"
    }
}

curl \
 --request PUT 'http://api.example.com/_inference/{task_type}/{jinaai_inference_id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n    \"service\": \"jinaai\",\n    \"service_settings\": {\n        \"model_id\": \"jina-embeddings-v3\",\n        \"api_key\": \"JinaAi-Api-key\"\n    }\n}"'

Request examples

Run `PUT _inference/text_embedding/jinaai-embeddings` to create an inference endpoint for text embedding tasks using the JinaAI service.

{
    "service": "jinaai",
    "service_settings": {
        "model_id": "jina-embeddings-v3",
        "api_key": "JinaAi-Api-key"
    }
}

Run `PUT _inference/rerank/jinaai-rerank` to create an inference endpoint for rerank tasks using the JinaAI service.

{
    "service": "jinaai",
    "service_settings": {
        "api_key": "JinaAI-Api-key",
        "model_id": "jina-reranker-v2-base-multilingual"
    },
    "task_settings": {
        "top_n": 10,
        "return_documents": true
    }
}

Get IP geolocation database configurations Added in 8.15.0

GET /_ingest/ip_location/database/{id}

Api key auth Basic auth Bearer auth

Path parameters

id string | array[string] Required

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

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. A value of -1 indicates that the request should never time out.

Values are -1 or 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- databases array[object] Required
  
  Hide databases attributes Show databases attributes object
  
  id string Required
  
  version number Required
  
  modified_date_millis number
  
  Time unit for milliseconds
  
  modified_date number
  
  Time unit for milliseconds
  
  database object
  
  Hide database attributes Show database attributes object
  
  name string Required
  
  web object
  
  local object
  
  Hide local attribute Show local attribute object
  
  type string Required
  
  maxmind object
  
  Hide maxmind attribute Show maxmind attribute object
  
  account_id string Required
  
  ipinfo object

GET /_ingest/ip_location/database/{id}

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

Delete pipelines Added in 5.0.0

DELETE /_ingest/pipeline/{id}

Api key auth Basic auth Bearer auth

Delete one or more ingest pipelines.

External documentation

Path parameters

id string Required

Pipeline ID or wildcard expression of pipeline IDs used to limit the request. To delete all ingest pipelines in a cluster, use a value of *.

Query parameters

master_timeout string

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

Values are -1 or 0.
timeout string

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

Values are -1 or 0.

Responses

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

DELETE /_ingest/pipeline/{id}

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

Get filters Added in 5.5.0

GET /_ml/filters/{filter_id}

Api key auth Basic auth Bearer auth

You can get a single filter or all filters.

Path parameters

filter_id string | array[string] Required

A string that uniquely identifies a filter.

Query parameters

from number

Skips the specified number of filters.
size number

Specifies the maximum number of filters to obtain.

Responses

200 application/json
Hide response attributes Show response attributes object
- count number Required
- filters array[object] Required
  
  Hide filters attributes Show filters attributes object
  
  description string
  
  A description of the filter.
  
  filter_id string Required
  
  items array[string] Required
  
  An array of strings which is the filter item list.

GET /_ml/filters/{filter_id}

curl \
 --request GET 'http://api.example.com/_ml/filters/{filter_id}' \
 --header "Authorization: $API_KEY"

Get info about events in calendars Added in 6.2.0

GET /_ml/calendars/{calendar_id}/events

Api key auth Basic auth Bearer auth

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.

Query parameters

end string | number

Specifies to get events with timestamps earlier than this time.
from number

Skips the specified number of events.
job_id string

Specifies to get events for a specific anomaly detection job identifier or job group. It must be used with a calendar identifier of _all or *.
size number

Specifies the maximum number of events to obtain.
start string | number

Specifies to get events with timestamps after this time.

Responses

200 application/json
Hide response attributes Show response attributes object
- count number Required
- events array[object] Required
  
  Hide events attributes Show events attributes object
  
  calendar_id string
  
  event_id string
  
  description string Required
  
  A description of the scheduled event.
  
  end_time string | number Required
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  start_time string | number Required
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  skip_result boolean
  
  When true the model will not create results for this calendar period.
  
  skip_model_update boolean
  
  When true the model will not be updated for this calendar period.
  
  force_time_shift number
  
  Shift time by this many seconds. For example adjust time for daylight savings changes

GET /_ml/calendars/{calendar_id}/events

curl \
 --request GET 'http://api.example.com/_ml/calendars/{calendar_id}/events' \
 --header "Authorization: $API_KEY"

Get overall bucket results Added in 6.1.0

GET /_ml/anomaly_detectors/{job_id}/results/overall_buckets

Api key auth Basic auth Bearer auth

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.

Path parameters

job_id string Required

Identifier for the anomaly detection job. It can be a job identifier, a group name, a comma-separated list of jobs or groups, or a wildcard expression.

You can summarize the bucket results for all anomaly detection jobs by using _all or by specifying * as the <job_id>.

Query parameters

allow_no_match boolean
Specifies what to do when the request:
1. Contains wildcard expressions and there are no jobs that match.
2. Contains the _all string or no identifiers and there are no matches.
3. Contains wildcard expressions and there are only partial matches.
If true, the request 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.
bucket_span string

The span of the overall buckets. Must be greater or equal to the largest bucket span of the specified anomaly detection jobs, which is the default value.

By default, an overall bucket has a span equal to the largest bucket span of the specified anomaly detection jobs. To override that behavior, use the optional bucket_span parameter.

Values are -1 or 0.
end string | number

Returns overall buckets with timestamps earlier than this time.
exclude_interim boolean

If true, the output excludes interim results.
overall_score number | string

Returns overall buckets with overall scores greater than or equal to this value.
start string | number

Returns overall buckets with timestamps after this time.
top_n number

The number of top anomaly detection job bucket scores to be used in the overall_score calculation.

application/json

Body

allow_no_match boolean

Refer to the description for the allow_no_match query parameter.
bucket_span string

A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
end string | number

A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.

One of:
DateTime string UnitMillis number
exclude_interim boolean

Refer to the description for the exclude_interim query parameter.
overall_score number | string

Refer to the description for the overall_score query parameter.

One of:
number-1 number string-2 string
start string | number

A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.

One of:
DateTime string UnitMillis number
top_n number

Refer to the description for the top_n query parameter.

Responses

200 application/json
Hide response attributes Show response attributes object
- count number Required
- overall_buckets array[object] Required
  
  Array of overall bucket objects
  
  Hide overall_buckets attributes Show overall_buckets attributes object
  
  bucket_span number
  
  Time unit for seconds
  
  is_interim boolean Required
  
  If true, this is an interim result. In other words, the results are calculated based on partial input data.
  
  jobs array[object] Required
  
  An array of objects that contain the max_anomaly_score per job_id.
  
  Hide jobs attributes Show jobs attributes object
  
  job_id string Required
  
  max_anomaly_score number Required
  
  overall_score number Required
  
  The top_n average of the maximum bucket anomaly_score per job.
  
  result_type string Required
  
  Internal. This is always set to overall_bucket.
  
  timestamp number
  
  Time unit for milliseconds
  
  timestamp_string string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number

GET /_ml/anomaly_detectors/{job_id}/results/overall_buckets

curl \
 --request GET 'http://api.example.com/_ml/anomaly_detectors/{job_id}/results/overall_buckets' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"allow_no_match":true,"bucket_span":"string","":"string","exclude_interim":true,"overall_score":42.0,"top_n":42.0}'

Explain data frame analytics config Added in 7.3.0

GET /_ml/data_frame/analytics/{id}/_explain

Api key auth Basic auth Bearer auth

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.

Path parameters

id string Required

Identifier for the data frame analytics job. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must start and end with alphanumeric characters.

application/json

Body

source object
Hide source attributes Show source attributes object
- index string | array[string] Required
- runtime_mappings object
  Hide runtime_mappings attribute Show runtime_mappings attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string SearchRequestBody object
  
  Hide attributes Show attributes
  
  aggregations object
  
  Defines the aggregations that are run as part of the search request.
  
  collapse object
  
  explain boolean
  
  If true, the request returns detailed information about score computation as part of a hit.
  
  ext object
  
  Configuration of search extensions defined by Elasticsearch plugins.
  
  from number
  
  The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
  
  highlight
  
  track_total_hits boolean | number
  
  Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
  
  indices_boost array[object]
  
  Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.
  
  docvalue_fields array[object]
  
  An array of wildcard (*) field patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.
  
  knn
  
  rank object
  
  min_score number
  
  The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
  
  post_filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  profile boolean
  
  Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.
  
  query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  rescore
  
  retriever object
  
  script_fields object
  
  Retrieve a script evaluation (based on different fields) for each hit.
  
  search_after array[number | string | boolean | null]
  
  A field value.
  
  size number
  
  The number of hits to return, which must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after property.
  
  slice object
  
  sort
  
  _source
  
  fields array[object]
  
  An array of wildcard (*) field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
  
  suggest object
  
  terminate_after number
  
  The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.
  
  IMPORTANT: Use with caution. Elasticsearch applies this property to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this property for requests that target data streams with backing indices across multiple data tiers.
  
  If set to 0 (default), the query does not terminate early.
  
  timeout string
  
  The period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.
  
  track_scores boolean
  
  If true, calculate and return document scores, even if the scores are not used for sorting.
  
  version boolean
  
  If true, the request returns the document version as part of a hit.
  
  seq_no_primary_term boolean
  
  If true, the request returns sequence number and primary term of the last modification of each hit.
  
  stored_fields string | array[string]
  
  pit object
  
  runtime_mappings object
  
  stats array[string]
  
  The stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
- _source object
  Hide _source attributes Show _source attributes object
  
  includes array[string]
  
  An array of strings that defines the fields that will be excluded from the analysis. You do not need to add fields with unsupported data types to excludes, these fields are excluded from the analysis automatically.
  
  excludes array[string]
  
  An array of strings that defines the fields that will be included in the analysis.
- query object
  
  The Elasticsearch query domain-specific language (DSL). This value corresponds to the query object in an Elasticsearch search POST body. All the options that are supported by Elasticsearch can be used, as this object is passed verbatim to Elasticsearch. By default, this property has the following value: {"match_all": {}}.
  
  Query DSL
dest object
Hide dest attributes Show dest attributes object
- index string Required
- results_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
analysis object
Hide analysis attributes Show analysis attributes object
- classification object
  Hide classification attributes Show classification attributes object
  
  alpha number
  
  Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This parameter affects loss calculations by acting as a multiplier of the tree depth. Higher alpha values result in shallower trees and faster training times. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to zero.
  
  dependent_variable string Required
  
  Defines which field of the document is to be predicted. It must match one of the fields in the index being used to train. If this field is missing from a document, then that document will not be used for training, but a prediction with the trained model will be generated for it. It is also known as continuous target variable. For classification analysis, the data type of the field must be numeric (integer, short, long, byte), categorical (ip or keyword), or boolean. There must be no more than 30 different values in this field. For regression analysis, the data type of the field must be numeric.
  
  downsample_factor number
  
  Advanced configuration option. Controls the fraction of data that is used to compute the derivatives of the loss function for tree training. A small value results in the use of a small fraction of the data. If this value is set to be less than 1, accuracy typically improves. However, too small a value may result in poor convergence for the ensemble and so require more trees. By default, this value is calculated during hyperparameter optimization. It must be greater than zero and less than or equal to 1.
  
  early_stopping_enabled boolean
  
  Advanced configuration option. Specifies whether the training process should finish if it is not finding any better performing models. If disabled, the training process can take significantly longer and the chance of finding a better performing model is unremarkable.
  
  eta number
  
  Advanced configuration option. The shrinkage applied to the weights. Smaller values result in larger forests which have a better generalization error. However, larger forests cause slower training. By default, this value is calculated during hyperparameter optimization. It must be a value between 0.001 and 1.
  
  eta_growth_rate_per_tree number
  
  Advanced configuration option. Specifies the rate at which eta increases for each new tree that is added to the forest. For example, a rate of 1.05 increases eta by 5% for each extra tree. By default, this value is calculated during hyperparameter optimization. It must be between 0.5 and 2.
  
  feature_bag_fraction number
  
  Advanced configuration option. Defines the fraction of features that will be used when selecting a random bag for each candidate split. By default, this value is calculated during hyperparameter optimization.
  
  feature_processors array[object]
  
  Advanced configuration option. A collection of feature preprocessors that modify one or more included fields. The analysis uses the resulting one or more features instead of the original document field. However, these features are ephemeral; they are not stored in the destination index. Multiple feature_processors entries can refer to the same document fields. Automatic categorical feature encoding still occurs for the fields that are unprocessed by a custom processor or that have categorical values. Use this property only if you want to override the automatic feature encoding of the specified fields.
  
  Hide feature_processors attributes Show feature_processors attributes object
  
  frequency_encoding object
  
  Hide frequency_encoding attributes Show frequency_encoding attributes object
  
  feature_name string Required
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  frequency_map object Required
  
  The resulting frequency map for the field value. If the field value is missing from the frequency_map, the resulting value is 0.
  
  multi_encoding object
  
  Hide multi_encoding attribute Show multi_encoding attribute object
  
  processors array[number] Required
  
  The ordered array of custom processors to execute. Must be more than 1.
  
  n_gram_encoding object
  
  Hide n_gram_encoding attributes Show n_gram_encoding attributes object
  
  feature_prefix string
  
  The feature name prefix. Defaults to ngram__.
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  length number
  
  Specifies the length of the n-gram substring. Defaults to 50. Must be greater than 0.
  
  n_grams array[number] Required
  
  Specifies which n-grams to gather. It’s an array of integer values where the minimum value is 1, and a maximum value is 5.
  
  start number
  
  Specifies the zero-indexed start of the n-gram substring. Negative values are allowed for encoding n-grams of string suffixes. Defaults to 0.
  
  custom boolean
  
  one_hot_encoding object
  
  Hide one_hot_encoding attributes Show one_hot_encoding attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  hot_map string Required
  
  The one hot map mapping the field value with the column name.
  
  target_mean_encoding object
  
  Hide target_mean_encoding attributes Show target_mean_encoding attributes object
  
  default_value number Required
  
  The default value if field value is not found in the target_map.
  
  feature_name string Required
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_map object Required
  
  The field value to target mean transition map.
  
  gamma number
  
  Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies a linear penalty associated with the size of individual trees in the forest. A high gamma value causes training to prefer small trees. A small gamma value results in larger individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.
  
  lambda number
  
  Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies an L2 regularization term which applies to leaf weights of the individual trees in the forest. A high lambda value causes training to favor small leaf weights. This behavior makes the prediction function smoother at the expense of potentially not being able to capture relevant relationships between the features and the dependent variable. A small lambda value results in large individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.
  
  max_optimization_rounds_per_hyperparameter number
  
  Advanced configuration option. A multiplier responsible for determining the maximum number of hyperparameter optimization steps in the Bayesian optimization procedure. The maximum number of steps is determined based on the number of undefined hyperparameters times the maximum optimization rounds per hyperparameter. By default, this value is calculated during hyperparameter optimization.
  
  max_trees number
  
  Advanced configuration option. Defines the maximum number of decision trees in the forest. The maximum value is 2000. By default, this value is calculated during hyperparameter optimization.
  
  num_top_feature_importance_values number
  
  Advanced configuration option. Specifies the maximum number of feature importance values per document to return. By default, no feature importance calculation occurs.
  
  prediction_field_name string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  randomize_seed number
  
  Defines the seed for the random generator that is used to pick training data. By default, it is randomly generated. Set it to a specific value to use the same training data each time you start a job (assuming other related parameters such as source and analyzed_fields are the same).
  
  soft_tree_depth_limit number
  
  Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This soft limit combines with the soft_tree_depth_tolerance to penalize trees that exceed the specified depth; the regularized loss increases quickly beyond this depth. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.
  
  soft_tree_depth_tolerance number
  
  Advanced configuration option. This option controls how quickly the regularized loss increases when the tree depth exceeds soft_tree_depth_limit. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.01.
  
  training_percent string | number
  
  One of:
  Percentage string Percentage number
  
  class_assignment_objective string
  
  num_top_classes number
  
  Defines the number of categories for which the predicted probabilities are reported. It must be non-negative or -1. If it is -1 or greater than the total number of categories, probabilities are reported for all categories; if you have a large number of categories, there could be a significant effect on the size of your destination index. NOTE: To use the AUC ROC evaluation method, num_top_classes must be set to -1 or a value greater than or equal to the total number of categories.
- outlier_detection object
  Hide outlier_detection attributes Show outlier_detection attributes object
  
  compute_feature_influence boolean
  
  Specifies whether the feature influence calculation is enabled.
  
  feature_influence_threshold number
  
  The minimum outlier score that a document needs to have in order to calculate its feature influence score. Value range: 0-1.
  
  method string
  
  The method that outlier detection uses. Available methods are lof, ldof, distance_kth_nn, distance_knn, and ensemble. The default value is ensemble, which means that outlier detection uses an ensemble of different methods and normalises and combines their individual outlier scores to obtain the overall outlier score.
  
  n_neighbors number
  
  Defines the value for how many nearest neighbors each method of outlier detection uses to calculate its outlier score. When the value is not set, different values are used for different ensemble members. This default behavior helps improve the diversity in the ensemble; only override it if you are confident that the value you choose is appropriate for the data set.
  
  outlier_fraction number
  
  The proportion of the data set that is assumed to be outlying prior to outlier detection. For example, 0.05 means it is assumed that 5% of values are real outliers and 95% are inliers.
  
  standardization_enabled boolean
  
  If true, the following operation is performed on the columns before computing outlier scores: (x_i - mean(x_i)) / sd(x_i).
- regression object
  Hide regression attributes Show regression attributes object
  
  alpha number
  
  Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This parameter affects loss calculations by acting as a multiplier of the tree depth. Higher alpha values result in shallower trees and faster training times. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to zero.
  
  dependent_variable string Required
  
  Defines which field of the document is to be predicted. It must match one of the fields in the index being used to train. If this field is missing from a document, then that document will not be used for training, but a prediction with the trained model will be generated for it. It is also known as continuous target variable. For classification analysis, the data type of the field must be numeric (integer, short, long, byte), categorical (ip or keyword), or boolean. There must be no more than 30 different values in this field. For regression analysis, the data type of the field must be numeric.
  
  downsample_factor number
  
  Advanced configuration option. Controls the fraction of data that is used to compute the derivatives of the loss function for tree training. A small value results in the use of a small fraction of the data. If this value is set to be less than 1, accuracy typically improves. However, too small a value may result in poor convergence for the ensemble and so require more trees. By default, this value is calculated during hyperparameter optimization. It must be greater than zero and less than or equal to 1.
  
  early_stopping_enabled boolean
  
  Advanced configuration option. Specifies whether the training process should finish if it is not finding any better performing models. If disabled, the training process can take significantly longer and the chance of finding a better performing model is unremarkable.
  
  eta number
  
  Advanced configuration option. The shrinkage applied to the weights. Smaller values result in larger forests which have a better generalization error. However, larger forests cause slower training. By default, this value is calculated during hyperparameter optimization. It must be a value between 0.001 and 1.
  
  eta_growth_rate_per_tree number
  
  Advanced configuration option. Specifies the rate at which eta increases for each new tree that is added to the forest. For example, a rate of 1.05 increases eta by 5% for each extra tree. By default, this value is calculated during hyperparameter optimization. It must be between 0.5 and 2.
  
  feature_bag_fraction number
  
  Advanced configuration option. Defines the fraction of features that will be used when selecting a random bag for each candidate split. By default, this value is calculated during hyperparameter optimization.
  
  feature_processors array[object]
  
  Advanced configuration option. A collection of feature preprocessors that modify one or more included fields. The analysis uses the resulting one or more features instead of the original document field. However, these features are ephemeral; they are not stored in the destination index. Multiple feature_processors entries can refer to the same document fields. Automatic categorical feature encoding still occurs for the fields that are unprocessed by a custom processor or that have categorical values. Use this property only if you want to override the automatic feature encoding of the specified fields.
  
  Hide feature_processors attributes Show feature_processors attributes object
  
  frequency_encoding object
  
  Hide frequency_encoding attributes Show frequency_encoding attributes object
  
  feature_name string Required
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  frequency_map object Required
  
  The resulting frequency map for the field value. If the field value is missing from the frequency_map, the resulting value is 0.
  
  multi_encoding object
  
  Hide multi_encoding attribute Show multi_encoding attribute object
  
  processors array[number] Required
  
  The ordered array of custom processors to execute. Must be more than 1.
  
  n_gram_encoding object
  
  Hide n_gram_encoding attributes Show n_gram_encoding attributes object
  
  feature_prefix string
  
  The feature name prefix. Defaults to ngram__.
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  length number
  
  Specifies the length of the n-gram substring. Defaults to 50. Must be greater than 0.
  
  n_grams array[number] Required
  
  Specifies which n-grams to gather. It’s an array of integer values where the minimum value is 1, and a maximum value is 5.
  
  start number
  
  Specifies the zero-indexed start of the n-gram substring. Negative values are allowed for encoding n-grams of string suffixes. Defaults to 0.
  
  custom boolean
  
  one_hot_encoding object
  
  Hide one_hot_encoding attributes Show one_hot_encoding attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  hot_map string Required
  
  The one hot map mapping the field value with the column name.
  
  target_mean_encoding object
  
  Hide target_mean_encoding attributes Show target_mean_encoding attributes object
  
  default_value number Required
  
  The default value if field value is not found in the target_map.
  
  feature_name string Required
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_map object Required
  
  The field value to target mean transition map.
  
  gamma number
  
  Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies a linear penalty associated with the size of individual trees in the forest. A high gamma value causes training to prefer small trees. A small gamma value results in larger individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.
  
  lambda number
  
  Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies an L2 regularization term which applies to leaf weights of the individual trees in the forest. A high lambda value causes training to favor small leaf weights. This behavior makes the prediction function smoother at the expense of potentially not being able to capture relevant relationships between the features and the dependent variable. A small lambda value results in large individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.
  
  max_optimization_rounds_per_hyperparameter number
  
  Advanced configuration option. A multiplier responsible for determining the maximum number of hyperparameter optimization steps in the Bayesian optimization procedure. The maximum number of steps is determined based on the number of undefined hyperparameters times the maximum optimization rounds per hyperparameter. By default, this value is calculated during hyperparameter optimization.
  
  max_trees number
  
  Advanced configuration option. Defines the maximum number of decision trees in the forest. The maximum value is 2000. By default, this value is calculated during hyperparameter optimization.
  
  num_top_feature_importance_values number
  
  Advanced configuration option. Specifies the maximum number of feature importance values per document to return. By default, no feature importance calculation occurs.
  
  prediction_field_name string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  randomize_seed number
  
  Defines the seed for the random generator that is used to pick training data. By default, it is randomly generated. Set it to a specific value to use the same training data each time you start a job (assuming other related parameters such as source and analyzed_fields are the same).
  
  soft_tree_depth_limit number
  
  Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This soft limit combines with the soft_tree_depth_tolerance to penalize trees that exceed the specified depth; the regularized loss increases quickly beyond this depth. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.
  
  soft_tree_depth_tolerance number
  
  Advanced configuration option. This option controls how quickly the regularized loss increases when the tree depth exceeds soft_tree_depth_limit. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.01.
  
  training_percent string | number
  
  One of:
  Percentage string Percentage number
  
  loss_function string
  
  The loss function used during regression. Available options are mse (mean squared error), msle (mean squared logarithmic error), huber (Pseudo-Huber loss).
  
  loss_function_parameter number
  
  A positive number that is used as a parameter to the loss_function.
description string

A description of the job.
model_memory_limit string

The approximate maximum amount of memory resources that are permitted for analytical processing. If your elasticsearch.yml file contains an xpack.ml.max_model_memory_limit setting, an error occurs when you try to create data frame analytics jobs that have model_memory_limit values greater than that setting.
max_num_threads number

The maximum number of threads to be used by the analysis. Using more threads may decrease the time necessary to complete the analysis at the cost of using more CPU. Note that the process may use additional threads for operational functionality other than the analysis itself.
analyzed_fields object
Hide analyzed_fields attributes Show analyzed_fields attributes object
- includes array[string]
  
  An array of strings that defines the fields that will be excluded from the analysis. You do not need to add fields with unsupported data types to excludes, these fields are excluded from the analysis automatically.
- excludes array[string]
  
  An array of strings that defines the fields that will be included in the analysis.
allow_lazy_start boolean

Specifies whether this job can start when there is insufficient machine learning node capacity for it to be immediately assigned to a node.

Responses

200 application/json
Hide response attributes Show response attributes object
- field_selection array[object] Required
  
  An array of objects that explain selection for each field, sorted by the field names.
  
  Hide field_selection attributes Show field_selection attributes object
  
  is_included boolean Required
  
  Whether the field is selected to be included in the analysis.
  
  is_required boolean Required
  
  Whether the field is required.
  
  feature_type string
  
  The feature type of this field for the analysis. May be categorical or numerical.
  
  mapping_types array[string] Required
  
  The mapping types of the field.
  
  name string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  reason string
  
  The reason a field is not selected to be included in the analysis.
- memory_estimation object Required
  
  Hide memory_estimation attributes Show memory_estimation attributes object
  
  expected_memory_with_disk string Required
  
  Estimated memory usage under the assumption that overflowing to disk is allowed during data frame analytics. expected_memory_with_disk is usually smaller than expected_memory_without_disk as using disk allows to limit the main memory needed to perform data frame analytics.
  
  expected_memory_without_disk string Required
  
  Estimated memory usage under the assumption that the whole data frame analytics should happen in memory (i.e. without overflowing to disk).

GET /_ml/data_frame/analytics/{id}/_explain

POST _ml/data_frame/analytics/_explain
{
  "source": {
    "index": "houses_sold_last_10_yrs"
  },
  "analysis": {
    "regression": {
      "dependent_variable": "price"
    }
  }
}

curl \
 --request GET 'http://api.example.com/_ml/data_frame/analytics/{id}/_explain' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"source\": {\n    \"index\": \"houses_sold_last_10_yrs\"\n  },\n  \"analysis\": {\n    \"regression\": {\n      \"dependent_variable\": \"price\"\n    }\n  }\n}"'

Request example

Run `POST _ml/data_frame/analytics/_explain` to explain a data frame analytics job configuration.

{
  "source": {
    "index": "houses_sold_last_10_yrs"
  },
  "analysis": {
    "regression": {
      "dependent_variable": "price"
    }
  }
}

Response examples (200)

A succesful response for explaining a data frame analytics job configuration.

{
  "field_selection": [
    {
      "field": "number_of_bedrooms",
      "mappings_types": [
        "integer"
      ],
      "is_included": true,
      "is_required": false,
      "feature_type": "numerical"
    },
    {
      "field": "postcode",
      "mappings_types": [
        "text"
      ],
      "is_included": false,
      "is_required": false,
      "reason": "[postcode.keyword] is preferred because it is aggregatable"
    },
    {
      "field": "postcode.keyword",
      "mappings_types": [
        "keyword"
      ],
      "is_included": true,
      "is_required": false,
      "feature_type": "categorical"
    },
    {
      "field": "price",
      "mappings_types": [
        "float"
      ],
      "is_included": true,
      "is_required": true,
      "feature_type": "numerical"
    }
  ],
  "memory_estimation": {
    "expected_memory_without_disk": "128MB",
    "expected_memory_with_disk": "32MB"
  }
}

Cancel a migration reindex operation Technical preview

POST /_migration/reindex/{index}/_cancel

Api key auth Basic auth Bearer auth

Cancel a migration reindex attempt for a data stream or index.

Path parameters

index string | array[string] Required

The index or data stream name

Responses

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

POST /_migration/reindex/{index}/_cancel

curl \
 --request POST 'http://api.example.com/_migration/reindex/{index}/_cancel' \
 --header "Authorization: $API_KEY"

Delete a behavioral analytics collection Deprecated Technical preview

Get component templates Added in 5.1.0

version string | null Required

Get node information Added in 1.3.0

reason string | null

max_content_length number | string

using_compressed_ordinary_object_pointers boolean | string

total_indexing_buffer_in_bytes number | string

Cancel a connector sync job Beta

Get cross-cluster replication stats Added in 6.5.0

reason string | null

Get a specific running ES|QL query information Technical preview

Create or update a component template Added in 7.8.0

Body Required

source string | object

lang string

Get component templates Added in 7.8.0

data_stream_options object | string | null

Force a merge Added in 2.1.0

Body Required

Get the ILM status Added in 6.6.0

Remove policies from an index Added in 6.6.0

Stop the ILM plugin Added in 6.6.0

Create an JinaAI inference endpoint Added in 8.18.0

Get IP geolocation database configurations Added in 8.15.0

Delete pipelines Added in 5.0.0

Get filters Added in 5.5.0

Get info about events in calendars Added in 6.2.0

end_time string | number Required

start_time string | number Required

Get overall bucket results Added in 6.1.0

end string | number

overall_score number | string

start string | number

timestamp_string string | number

Explain data frame analytics config Added in 7.3.0

source string | object

lang string

training_percent string | number

training_percent string | number

Cancel a migration reindex operation Technical preview

Rollup Dismiss highlight