Get an autoscaling policy Generally available; Added in 7.11.0

GET /_autoscaling/policy/{name}

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

External documentation

Path parameters

  • name string Required

    the name of the autoscaling policy

Query parameters

  • master_timeout string

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

    Values are -1 or 0.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • roles array[string] Required
    • deciders object Required

      Decider settings.

      External documentation
      Hide deciders attribute Show deciders attribute object
      • * object Additional properties
GET /_autoscaling/policy/my_autoscaling_policy
resp = client.autoscaling.get_autoscaling_policy(
    name="my_autoscaling_policy",
)
const response = await client.autoscaling.getAutoscalingPolicy({
  name: "my_autoscaling_policy",
});
response = client.autoscaling.get_autoscaling_policy(
  name: "my_autoscaling_policy"
)
$resp = $client->autoscaling()->getAutoscalingPolicy([
    "name" => "my_autoscaling_policy",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_autoscaling/policy/my_autoscaling_policy"
client.autoscaling().getAutoscalingPolicy(g -> g
    .name("my_autoscaling_policy")
);
Response examples (200)
This may be a response to `GET /_autoscaling/policy/my_autoscaling_policy`.
{
   "roles": <roles>,
   "deciders": <deciders>
}













Get behavioral analytics collections Technical preview; Added in 8.8.0

GET /_application/analytics/{name}

All methods and paths for this operation:

GET /_application/analytics

GET /_application/analytics/{name}

Path parameters

  • name array[string] Required

    A list of analytics collections to limit the returned information

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • * object Additional properties
      Hide * attribute Show * attribute object
      • event_data_stream object Required
        Hide event_data_stream attribute Show event_data_stream attribute object
        • name string Required
GET /_application/analytics/{name}
GET _application/analytics/my*
resp = client.search_application.get_behavioral_analytics(
    name="my*",
)
const response = await client.searchApplication.getBehavioralAnalytics({
  name: "my*",
});
response = client.search_application.get_behavioral_analytics(
  name: "my*"
)
$resp = $client->searchApplication()->getBehavioralAnalytics([
    "name" => "my*",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_application/analytics/my*"
client.searchApplication().getBehavioralAnalytics(g -> g
    .name("my*")
);
Response examples (200)
A successful response from `GET _application/analytics/my*`
{
  "my_analytics_collection": {
      "event_data_stream": {
          "name": "behavioral_analytics-events-my_analytics_collection"
      }
  },
  "my_analytics_collection2": {
      "event_data_stream": {
          "name": "behavioral_analytics-events-my_analytics_collection2"
      }
  }
}





















Get component templates Generally available; Added in 5.1.0

GET /_cat/component_templates/{name}

All methods and paths for this operation:

GET /_cat/component_templates

GET /_cat/component_templates/{name}

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.

Required authorization

  • Cluster privileges: monitor

Path parameters

  • name string Required

    The name of the component template. It accepts wildcard expressions. If it is omitted, all component templates are returned.

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

    • alias_count string Required
    • mapping_count string Required
    • settings_count string Required
    • metadata_count string Required
    • included_in string Required
GET /_cat/component_templates/{name}
GET _cat/component_templates/my-template-*?v=true&s=name&format=json
resp = client.cat.component_templates(
    name="my-template-*",
    v=True,
    s="name",
    format="json",
)
const response = await client.cat.componentTemplates({
  name: "my-template-*",
  v: "true",
  s: "name",
  format: "json",
});
response = client.cat.component_templates(
  name: "my-template-*",
  v: "true",
  s: "name",
  format: "json"
)
$resp = $client->cat()->componentTemplates([
    "name" => "my-template-*",
    "v" => "true",
    "s" => "name",
    "format" => "json",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/component_templates/my-template-*?v=true&s=name&format=json"
client.cat().componentTemplates();
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 a document count Generally available

GET /_cat/count/{index}

All methods and paths for this operation:

GET /_cat/count

GET /_cat/count/{index}

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

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

Required authorization

  • Index privileges: read

Path parameters

  • index string | array[string] Required

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

Query parameters

  • h string | array[string]

    List of columns to appear in the response. Supports simple wildcards.

  • s string | array[string]

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

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • epoch number | string

      Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.

      Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.

      One of:

      Time unit for seconds

    • timestamp string

      Time of day, expressed as HH:MM:SS

    • count string

      the document count

GET /_cat/count/my-index-000001?v=true&format=json
resp = client.cat.count(
    index="my-index-000001",
    v=True,
    format="json",
)
const response = await client.cat.count({
  index: "my-index-000001",
  v: "true",
  format: "json",
});
response = client.cat.count(
  index: "my-index-000001",
  v: "true",
  format: "json"
)
$resp = $client->cat()->count([
    "index" => "my-index-000001",
    "v" => "true",
    "format" => "json",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/count/my-index-000001?v=true&format=json"
client.cat().count();
Response examples (200)
A successful response from `GET /_cat/count/my-index-000001?v=true&format=json`. It retrieves the document count for the `my-index-000001` data stream or index.
[
  {
    "epoch": "1475868259",
    "timestamp": "15:24:20",
    "count": "120"
  }
]
A successful response from `GET /_cat/count?v=true&format=json`. It retrieves the document count for all data streams and indices in the cluster.
[
  {
    "epoch": "1475868259",
    "timestamp": "15:24:20",
    "count": "121"
  }
]




Get the cluster health status Generally available

GET /_cat/health

IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the cluster health API. This API is often used to check malfunctioning clusters. To help you track cluster health alongside log files and alerting systems, the API returns timestamps in two formats: HH:MM:SS, which is human-readable but includes no date information; Unix epoch time, which is machine-sortable and includes date information. The latter format is useful for cluster recoveries that take multiple days. You can use the cat health API to verify cluster health across multiple nodes. You also can use the API to track the recovery of a large cluster over a longer period of time.

Required authorization

  • Cluster privileges: monitor

Query parameters

  • time string

    The unit used to display time values.

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

  • ts boolean

    If true, returns HH:MM:SS and Unix epoch timestamps.

  • h string | array[string]

    List of columns to appear in the response. Supports simple wildcards.

  • s string | array[string]

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

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • epoch number | string

      Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.

      Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.

      One of:

      Time unit for seconds

    • timestamp string

      Time of day, expressed as HH:MM:SS

    • cluster string

      cluster name

    • status string

      health status

    • node.total string

      total number of nodes

    • node.data string

      number of nodes that can store data

    • shards string

      total number of shards

    • pri string

      number of primary shards

    • relo string

      number of relocating nodes

    • init string

      number of initializing nodes

    • unassign.pri string

      number of unassigned primary shards

    • unassign string

      number of unassigned shards

    • pending_tasks string

      number of pending tasks

    • max_task_wait_time string

      wait time of longest task pending

    • active_shards_percent string

      active number of shards in percent

GET /_cat/health?v=true&format=json
resp = client.cat.health(
    v=True,
    format="json",
)
const response = await client.cat.health({
  v: "true",
  format: "json",
});
response = client.cat.health(
  v: "true",
  format: "json"
)
$resp = $client->cat()->health([
    "v" => "true",
    "format" => "json",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/health?v=true&format=json"
client.cat().health();
Response examples (200)
A successful response from `GET /_cat/health?v=true&format=json`. By default, it returns `HH:MM:SS` and Unix epoch timestamps.
[
  {
    "epoch": "1475871424",
    "timestamp": "16:17:04",
    "cluster": "elasticsearch",
    "status": "green",
    "node.total": "1",
    "node.data": "1",
    "shards": "1",
    "pri": "1",
    "relo": "0",
    "init": "0",
    "unassign": "0",
    "unassign.pri": "0",
    "pending_tasks": "0",
    "max_task_wait_time": "-",
    "active_shards_percent": "100.0%"
  }
]

Get CAT help Generally available

GET /_cat

Get help for the CAT APIs.

Responses

  • 200 application/json
GET /_cat
curl \
 --request GET 'http://api.example.com/_cat' \
 --header "Authorization: $API_KEY"




























































Get task information Technical preview; Added in 5.0.0

GET /_cat/tasks

Get information about tasks currently running in the cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the task management API.

Required authorization

  • Cluster privileges: monitor

Query parameters

  • actions array[string]

    The task action names, which are used to limit the response.

  • detailed boolean

    If true, the response includes detailed information about shard recoveries.

  • nodes array[string]

    Unique node identifiers, which are used to limit the response.

  • parent_task_id string

    The parent task identifier, which is used to limit the response.

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

  • time string

    Unit used to display time values.

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

  • timeout string

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

    Values are -1 or 0.

  • wait_for_completion boolean

    If true, the request blocks until the task has completed.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • id string
    • action string

      The task action.

    • task_id string
    • parent_task_id string

      The parent task identifier.

    • type string

      The task type.

    • start_time string

      The start time in milliseconds.

    • timestamp string

      The start time in HH:MM:SS format.

    • running_time_ns string

      The running time in nanoseconds.

    • running_time string

      The running time.

    • node_id string
    • ip string

      The IP address for the node.

    • port string

      The bound transport port for the node.

    • node string

      The node name.

    • version string
    • x_opaque_id string

      The X-Opaque-ID header.

    • description string

      The task action description.

GET _cat/tasks?v=true&format=json
resp = client.cat.tasks(
    v=True,
    format="json",
)
const response = await client.cat.tasks({
  v: "true",
  format: "json",
});
response = client.cat.tasks(
  v: "true",
  format: "json"
)
$resp = $client->cat()->tasks([
    "v" => "true",
    "format" => "json",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/tasks?v=true&format=json"
client.cat().tasks();
Response examples (200)
A successful response from `GET _cat/tasks?v=true&format=json`.
[
  {
    "action": "cluster:monitor/tasks/lists[n]",
    "task_id": "oTUltX4IQMOUUVeiohTt8A:124",
    "parent_task_id": "oTUltX4IQMOUUVeiohTt8A:123",
    "type": "direct",
    "start_time": "1458585884904",
    "timestamp": "01:48:24",
    "running_time": "44.1micros",
    "ip": "127.0.0.1:9300",
    "node": "oTUltX4IQMOUUVeiohTt8A"
  },
  {
    "action": "cluster:monitor/tasks/lists",
    "task_id": "oTUltX4IQMOUUVeiohTt8A:123",
    "parent_task_id": "-",
    "type": "transport",
    "start_time": "1458585884904",
    "timestamp": "01:48:24",
    "running_time": "186.2micros",
    "ip": "127.0.0.1:9300",
    "node": "oTUltX4IQMOUUVeiohTt8A"
  }
]

Get index template information Generally available; Added in 5.2.0

GET /_cat/templates/{name}

All methods and paths for this operation:

GET /_cat/templates

GET /_cat/templates/{name}

Get information about the index templates in a cluster. You can use index templates to apply index settings and field mappings to new indices at creation. 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 index template API.

Required authorization

  • Cluster privileges: monitor

Path parameters

  • name string Required

    The name of the template to return. Accepts wildcard expressions. If omitted, all templates are returned.

Query parameters

  • h string | array[string]

    List of columns to appear in the response. Supports simple wildcards.

  • s string | array[string]

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

  • local boolean

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

  • master_timeout string

    Period to wait for a connection to the master node.

    Values are -1 or 0.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • name string
    • index_patterns string

      The template index patterns.

    • order string

      The template application order or priority number.

    • version string | null

      The template version.

    • composed_of string

      The component templates that comprise the index template.

GET _cat/templates/my-template-*?v=true&s=name&format=json
resp = client.cat.templates(
    name="my-template-*",
    v=True,
    s="name",
    format="json",
)
const response = await client.cat.templates({
  name: "my-template-*",
  v: "true",
  s: "name",
  format: "json",
});
response = client.cat.templates(
  name: "my-template-*",
  v: "true",
  s: "name",
  format: "json"
)
$resp = $client->cat()->templates([
    "name" => "my-template-*",
    "v" => "true",
    "s" => "name",
    "format" => "json",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/templates/my-template-*?v=true&s=name&format=json"
client.cat().templates();
Response examples (200)
A successful response from `GET _cat/templates/my-template-*?v=true&s=name&format=json`.
[
  {
    "name": "my-template-0",
    "index_patterns": "[te*]",
    "order": "500",
    "version": null,
    "composed_of": "[]"
  },
  {
    "name": "my-template-1",
    "index_patterns": "[tea*]",
    "order": "501",
    "version": null,
    "composed_of": "[]"
  },
  {
    "name": "my-template-2",
    "index_patterns": "[teak*]",
    "order": "502",
    "version": "7",
    "composed_of": "[]"
  }
]













Update voting configuration exclusions Generally available; Added in 7.0.0

POST /_cluster/voting_config_exclusions

Update the cluster voting config exclusions by node IDs or node names. By default, if there are more than three master-eligible nodes in the cluster and you remove fewer than half of the master-eligible nodes in the cluster at once, the voting configuration automatically shrinks. If you want to shrink the voting configuration to contain fewer than three nodes or to remove half or more of the master-eligible nodes in the cluster at once, use this API to remove departing nodes from the voting configuration manually. The API adds an entry for each specified node to the cluster’s voting configuration exclusions list. It then waits until the cluster has reconfigured its voting configuration to exclude the specified nodes.

Clusters should have no voting configuration exclusions in normal operation. Once the excluded nodes have stopped, clear the voting configuration exclusions with DELETE /_cluster/voting_config_exclusions. This API waits for the nodes to be fully removed from the cluster before it returns. If your cluster has voting configuration exclusions for nodes that you no longer intend to remove, use DELETE /_cluster/voting_config_exclusions?wait_for_removal=false to clear the voting configuration exclusions without waiting for the nodes to leave the cluster.

A response to POST /_cluster/voting_config_exclusions with an HTTP status code of 200 OK guarantees that the node has been removed from the voting configuration and will not be reinstated until the voting configuration exclusions are cleared by calling DELETE /_cluster/voting_config_exclusions. If the call to POST /_cluster/voting_config_exclusions fails or returns a response with an HTTP status code other than 200 OK then the node may not have been removed from the voting configuration. In that case, you may safely retry the call.

NOTE: Voting exclusions are required only when you remove at least half of the master-eligible nodes from a cluster in a short time period. They are not required when removing master-ineligible nodes or when removing fewer than half of the master-eligible nodes.

External documentation

Query parameters

  • node_names string | array[string]

    A comma-separated list of the names of the nodes to exclude from the voting configuration. If specified, you may not also specify node_ids.

  • node_ids string | array[string]

    A comma-separated list of the persistent ids of the nodes to exclude from the voting configuration. If specified, you may not also specify node_names.

  • master_timeout string

    Period to wait for a connection to the master node.

    Values are -1 or 0.

  • timeout string

    When adding a voting configuration exclusion, the API waits for the specified nodes to be excluded from the voting configuration before returning. If the timeout expires before the appropriate condition is satisfied, the request fails and returns an error.

    Values are -1 or 0.

Responses

  • 200 application/json
POST /_cluster/voting_config_exclusions
curl \
 --request POST 'http://api.example.com/_cluster/voting_config_exclusions' \
 --header "Authorization: $API_KEY"
















Get cluster info Generally available; Added in 8.9.0

GET /_info/{target}

Returns basic information about the cluster.

Path parameters

  • target string | array[string]

    Limits the information returned to the specific target. Supports a comma-separated list, such as http,ingest.

    Supported values include: _all, http, ingest, thread_pool, script

    Values are _all, http, ingest, thread_pool, or script.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • cluster_name string Required
    • http object
      Hide http attributes Show http attributes object
      • current_open number

        Current number of open HTTP connections for the node.

      • total_opened number

        Total number of HTTP connections opened for the node.

      • clients array[object]

        Information on current and recently-closed HTTP client connections. Clients that have been closed longer than the http.client_stats.closed_channels.max_age setting will not be represented here.

        Hide clients attributes Show clients attributes object
        • id number

          Unique ID for the HTTP client.

        • agent string

          Reported agent for the HTTP client. If unavailable, this property is not included in the response.

        • local_address string

          Local address for the HTTP connection.

        • remote_address string

          Remote address for the HTTP connection.

        • last_uri string

          The URI of the client’s most recent request.

        • opened_time_millis number

          Time at which the client opened the connection.

        • closed_time_millis number

          Time at which the client closed the connection if the connection is closed.

        • last_request_time_millis number

          Time of the most recent request from this client.

        • request_count number

          Number of requests from this client.

        • request_size_bytes number

          Cumulative size in bytes of all requests from this client.

        • x_opaque_id string

          Value from the client’s x-opaque-id HTTP header. If unavailable, this property is not included in the response.

      • routes object Required Generally available; Added in 8.12.0

        Detailed HTTP stats broken down by route

        Hide routes attribute Show routes attribute object
        • * object Additional properties
          Hide * attributes Show * attributes object
          • requests object Required
            Hide requests attributes Show requests attributes object
            • count number Required
            • total_size_in_bytes number Required
            • size_histogram array[object] Required
          • responses object Required
            Hide responses attributes Show responses attributes object
            • count number Required
            • total_size_in_bytes number Required
            • handling_time_histogram array[object] Required
            • size_histogram array[object] Required
    • ingest object
      Hide ingest attributes Show ingest attributes object
      • pipelines object

        Contains statistics about ingest pipelines for the node.

        Hide pipelines attribute Show pipelines attribute object
        • * object Additional properties
          Hide * attributes Show * attributes object
          • count number Required

            Total number of documents ingested during the lifetime of this node.

          • current number Required

            Total number of documents currently being ingested.

          • failed number Required

            Total number of failed ingest operations during the lifetime of this node.

          • processors array[object] Required

            Total number of ingest processors.

            Hide processors attribute Show processors attribute object
            • * object Additional properties
          • time_in_millis number

            Time unit for milliseconds

          • ingested_as_first_pipeline_in_bytes number Required Generally available; Added in 8.15.0

            Total number of bytes of all documents ingested by the pipeline. This field is only present on pipelines which are the first to process a document. Thus, it is not present on pipelines which only serve as a final pipeline after a default pipeline, a pipeline run after a reroute processor, or pipelines in pipeline processors.

          • produced_as_first_pipeline_in_bytes number Required Generally available; Added in 8.15.0

            Total number of bytes of all documents produced by the pipeline. This field is only present on pipelines which are the first to process a document. Thus, it is not present on pipelines which only serve as a final pipeline after a default pipeline, a pipeline run after a reroute processor, or pipelines in pipeline processors. In situations where there are subsequent pipelines, the value represents the size of the document after all pipelines have run.

      • total object
        Hide total attributes Show total attributes object
        • count number Required

          Total number of documents ingested during the lifetime of this node.

        • current number Required

          Total number of documents currently being ingested.

        • failed number Required

          Total number of failed ingest operations during the lifetime of this node.

        • time_in_millis number

          Time unit for milliseconds

    • thread_pool object
      Hide thread_pool attribute Show thread_pool attribute object
      • * object Additional properties
        Hide * attributes Show * attributes object
        • active number

          Number of active threads in the thread pool.

        • completed number

          Number of tasks completed by the thread pool executor.

        • largest number

          Highest number of active threads in the thread pool.

        • queue number

          Number of tasks in queue for the thread pool.

        • rejected number

          Number of tasks rejected by the thread pool executor.

        • threads number

          Number of threads in the thread pool.

    • script object
      Hide script attributes Show script attributes object
      • cache_evictions number

        Total number of times the script cache has evicted old data.

      • compilations number

        Total number of inline script compilations performed by the node.

      • compilations_history object

        Contains this recent history of script compilations.

        Hide compilations_history attribute Show compilations_history attribute object
        • * number Additional properties
      • compilation_limit_triggered number

        Total number of times the script compilation circuit breaker has limited inline script compilations.

      • contexts array[object]
        Hide contexts attributes Show contexts attributes object
        • context string
        • compilations number
        • cache_evictions number
        • compilation_limit_triggered number
GET /_info/_all
resp = client.cluster.info(
    target="_all",
)
const response = await client.cluster.info({
  target: "_all",
});
response = client.cluster.info(
  target: "_all"
)
$resp = $client->cluster()->info([
    "target" => "_all",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_info/_all"
client.cluster().info(i -> i
    .target("_all")
);
































Get the hot threads for nodes Generally available

GET /_nodes/{node_id}/hot_threads

All methods and paths for this operation:

GET /_nodes/hot_threads

GET /_nodes/{node_id}/hot_threads

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

Required authorization

  • Cluster privileges: monitor,manage

Path parameters

  • node_id string | array[string] Required

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

Query parameters

  • ignore_idle_threads boolean

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

  • interval string

    The interval to do the second sampling of threads.

    Values are -1 or 0.

  • snapshots number

    Number of samples of thread stacktrace.

  • threads number

    Specifies the number of hot threads to provide information for.

  • timeout string

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

    Values are -1 or 0.

  • type string

    The type to sample.

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

  • sort string

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

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

Responses

  • 200 application/json
GET /_nodes/{node_id}/hot_threads
GET /_nodes/hot_threads
resp = client.nodes.hot_threads()
const response = await client.nodes.hotThreads();
response = client.nodes.hot_threads
$resp = $client->nodes()->hotThreads();
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_nodes/hot_threads"
client.nodes().hotThreads(h -> h);
















Cluster - Health





Connector

The connector and sync jobs APIs provide a convenient way to create and manage Elastic connectors and sync jobs in an internal index. Connectors are Elasticsearch integrations that bring content from third-party data sources, which can be deployed on Elastic Cloud or hosted on your own infrastructure:

  • Elastic managed connectors (Native connectors) are a managed service on Elastic Cloud
  • Self-managed connectors (Connector clients) are self-managed on your infrastructure.

This API provides an alternative to relying solely on Kibana UI for connector and sync job management. The API comes with a set of validations and assertions to ensure that the state representation in the internal index remains valid.

Check out the connector API tutorial




























Check in a connector sync job Technical preview

PUT /_connector/_sync_job/{connector_sync_job_id}/_check_in

Check in a connector sync job and set the last_seen field to the current time before updating it in the internal index.

To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure. This service runs automatically on Elastic Cloud for Elastic managed connectors.

Path parameters

  • connector_sync_job_id string Required

    The unique identifier of the connector sync job to be checked in.

Responses

  • 200 application/json
PUT /_connector/_sync_job/{connector_sync_job_id}/_check_in
PUT _connector/_sync_job/my-connector-sync-job/_check_in
resp = client.connector.sync_job_check_in(
    connector_sync_job_id="my-connector-sync-job",
)
const response = await client.connector.syncJobCheckIn({
  connector_sync_job_id: "my-connector-sync-job",
});
response = client.connector.sync_job_check_in(
  connector_sync_job_id: "my-connector-sync-job"
)
$resp = $client->connector()->syncJobCheckIn([
    "connector_sync_job_id" => "my-connector-sync-job",
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/_sync_job/my-connector-sync-job/_check_in"
client.connector().syncJobCheckIn(s -> s
    .connectorSyncJobId("my-connector-sync-job")
);








Delete a connector sync job Beta; Added in 8.12.0

DELETE /_connector/_sync_job/{connector_sync_job_id}

Remove a connector sync job and its associated data. This is a destructive action that is not recoverable.

Path parameters

  • connector_sync_job_id string Required

    The unique identifier of the connector sync job 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 /_connector/_sync_job/{connector_sync_job_id}
DELETE _connector/_sync_job/my-connector-sync-job-id
resp = client.connector.sync_job_delete(
    connector_sync_job_id="my-connector-sync-job-id",
)
const response = await client.connector.syncJobDelete({
  connector_sync_job_id: "my-connector-sync-job-id",
});
response = client.connector.sync_job_delete(
  connector_sync_job_id: "my-connector-sync-job-id"
)
$resp = $client->connector()->syncJobDelete([
    "connector_sync_job_id" => "my-connector-sync-job-id",
]);
curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/_sync_job/my-connector-sync-job-id"
client.connector().syncJobDelete(s -> s
    .connectorSyncJobId("my-connector-sync-job-id")
);
Response examples (200)
{
  "acknowledged": true
}








































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

PUT /_connector/{connector_id}/_filtering/_validation

Update the draft filtering validation info for a connector.

Path parameters

  • connector_id string Required

    The unique identifier of the connector to be updated

application/json

Body Required

  • validation object Required
    Hide validation attributes Show validation attributes object
    • errors array[object] Required
      Hide errors attributes Show errors attributes object
      • ids array[string] Required
      • messages array[string] Required
    • state string Required

      Values are edited, invalid, or valid.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • result string Required

      Values are created, updated, deleted, not_found, or noop.

PUT /_connector/{connector_id}/_filtering/_validation
curl \
 --request PUT 'http://api.example.com/_connector/{connector_id}/_filtering/_validation' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"validation":{"errors":[{"ids":["string"],"messages":["string"]}],"state":"edited"}}'




Update the connector name and description Beta; Added in 8.12.0

PUT /_connector/{connector_id}/_name

Path parameters

  • connector_id string Required

    The unique identifier of the connector to be updated

application/json

Body Required

  • name string
  • description string

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • result string Required

      Values are created, updated, deleted, not_found, or noop.

PUT /_connector/{connector_id}/_name
PUT _connector/my-connector/_name
{
    "name": "Custom connector",
    "description": "This is my customized connector"
}
resp = client.connector.update_name(
    connector_id="my-connector",
    name="Custom connector",
    description="This is my customized connector",
)
const response = await client.connector.updateName({
  connector_id: "my-connector",
  name: "Custom connector",
  description: "This is my customized connector",
});
response = client.connector.update_name(
  connector_id: "my-connector",
  body: {
    "name": "Custom connector",
    "description": "This is my customized connector"
  }
)
$resp = $client->connector()->updateName([
    "connector_id" => "my-connector",
    "body" => [
        "name" => "Custom connector",
        "description" => "This is my customized connector",
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"name":"Custom connector","description":"This is my customized connector"}' "$ELASTICSEARCH_URL/_connector/my-connector/_name"
client.connector().updateName(u -> u
    .connectorId("my-connector")
    .description("This is my customized connector")
    .name("Custom connector")
);
Request example
{
    "name": "Custom connector",
    "description": "This is my customized connector"
}
Response examples (200)
{
  "result": "updated"
}












Update the connector service type Beta; Added in 8.12.0

PUT /_connector/{connector_id}/_service_type

Path parameters

  • connector_id string Required

    The unique identifier of the connector to be updated

application/json

Body Required

  • service_type string Required

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • result string Required

      Values are created, updated, deleted, not_found, or noop.

PUT /_connector/{connector_id}/_service_type
PUT _connector/my-connector/_service_type
{
    "service_type": "sharepoint_online"
}
resp = client.connector.update_service_type(
    connector_id="my-connector",
    service_type="sharepoint_online",
)
const response = await client.connector.updateServiceType({
  connector_id: "my-connector",
  service_type: "sharepoint_online",
});
response = client.connector.update_service_type(
  connector_id: "my-connector",
  body: {
    "service_type": "sharepoint_online"
  }
)
$resp = $client->connector()->updateServiceType([
    "connector_id" => "my-connector",
    "body" => [
        "service_type" => "sharepoint_online",
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"service_type":"sharepoint_online"}' "$ELASTICSEARCH_URL/_connector/my-connector/_service_type"
client.connector().updateServiceType(u -> u
    .connectorId("my-connector")
    .serviceType("sharepoint_online")
);
Request example
{
    "service_type": "sharepoint_online"
}
Response examples (200)
{
  "result": "updated"
}

































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

POST /_ccr/auto_follow/{name}/pause

Pause a cross-cluster replication auto-follow pattern. When the API returns, the auto-follow pattern is inactive. New indices that are created on the remote cluster and match the auto-follow patterns are ignored.

You can resume auto-following with the resume auto-follow pattern API. When it resumes, the auto-follow pattern is active again and automatically configures follower indices for newly created indices on the remote cluster that match its patterns. Remote indices that were created while the pattern was paused will also be followed, unless they have been deleted or closed in the interim.

Required authorization

  • Cluster privileges: manage_ccr
External documentation

Path parameters

  • name string Required

    The name of the auto-follow pattern to pause.

Query parameters

  • master_timeout string

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

    Values are -1 or 0.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • acknowledged boolean Required

      For a successful response, this value is always true. On failure, an exception is returned instead.

POST /_ccr/auto_follow/{name}/pause
POST /_ccr/auto_follow/my_auto_follow_pattern/pause
resp = client.ccr.pause_auto_follow_pattern(
    name="my_auto_follow_pattern",
)
const response = await client.ccr.pauseAutoFollowPattern({
  name: "my_auto_follow_pattern",
});
response = client.ccr.pause_auto_follow_pattern(
  name: "my_auto_follow_pattern"
)
$resp = $client->ccr()->pauseAutoFollowPattern([
    "name" => "my_auto_follow_pattern",
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ccr/auto_follow/my_auto_follow_pattern/pause"
client.ccr().pauseAutoFollowPattern(p -> p
    .name("my_auto_follow_pattern")
);
Response examples (200)
A successful response from `POST /_ccr/auto_follow/my_auto_follow_pattern/pause`, which pauses an auto-follow pattern.
{
  "acknowledged" : true
}













































Downsample an index Technical preview; Added in 8.5.0

POST /{index}/_downsample/{target_index}

Aggregate a time series (TSDS) index and store pre-computed statistical summaries (min, max, sum, value_count and avg) for each metric field grouped by a configured time interval. For example, a TSDS index that contains metrics sampled every 10 seconds can be downsampled to an hourly index. All documents within an hour interval are summarized and stored as a single document in the downsample index.

NOTE: Only indices in a time series data stream are supported. Neither field nor document level security can be defined on the source index. The source index must be read only (index.blocks.write: true).

Path parameters

  • index string Required

    Name of the time series index to downsample.

  • target_index string Required

    Name of the index to create.

application/json

Body Required

  • fixed_interval string Required

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

Responses

  • 200 application/json
POST /{index}/_downsample/{target_index}
POST /my-time-series-index/_downsample/my-downsampled-time-series-index
{
  "fixed_interval": "1d"
}
resp = client.indices.downsample(
    index="my-time-series-index",
    target_index="my-downsampled-time-series-index",
    config={
        "fixed_interval": "1d"
    },
)
const response = await client.indices.downsample({
  index: "my-time-series-index",
  target_index: "my-downsampled-time-series-index",
  config: {
    fixed_interval: "1d",
  },
});
response = client.indices.downsample(
  index: "my-time-series-index",
  target_index: "my-downsampled-time-series-index",
  body: {
    "fixed_interval": "1d"
  }
)
$resp = $client->indices()->downsample([
    "index" => "my-time-series-index",
    "target_index" => "my-downsampled-time-series-index",
    "body" => [
        "fixed_interval" => "1d",
    ],
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"fixed_interval":"1d"}' "$ELASTICSEARCH_URL/my-time-series-index/_downsample/my-downsampled-time-series-index"
client.indices().downsample(d -> d
    .index("my-time-series-index")
    .targetIndex("my-downsampled-time-series-index")
    .config(c -> c
        .fixedInterval(f -> f
            .time("1d")
        )
    )
);
Request example
{
  "fixed_interval": "1d"
}








Convert an index alias to a data stream Generally available; Added in 7.9.0

POST /_data_stream/_migrate/{name}

Converts an index alias to a data stream. You must have a matching index template that is data stream enabled. The alias must meet the following criteria: The alias must have a write index; All indices for the alias must have a @timestamp field mapping of a date or date_nanos field type; The alias must not have any filters; The alias must not use custom routing. If successful, the request removes the alias and creates a data stream with the same name. The indices for the alias become hidden backing indices for the stream. The write index for the alias becomes the write index for the stream.

Required authorization

  • Index privileges: manage

Path parameters

  • name string Required

    Name of the index alias to convert to a data stream.

Query parameters

  • master_timeout string

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

    Values are -1 or 0.

  • 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 /_data_stream/_migrate/{name}
POST _data_stream/_migrate/my-time-series-data
resp = client.indices.migrate_to_data_stream(
    name="my-time-series-data",
)
const response = await client.indices.migrateToDataStream({
  name: "my-time-series-data",
});
response = client.indices.migrate_to_data_stream(
  name: "my-time-series-data"
)
$resp = $client->indices()->migrateToDataStream([
    "name" => "my-time-series-data",
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_data_stream/_migrate/my-time-series-data"
client.indices().migrateToDataStream(m -> m
    .name("my-time-series-data")
);




Promote a data stream Generally available; Added in 7.9.0

POST /_data_stream/_promote/{name}

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

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

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

Path parameters

  • name string Required

    The name of the data stream

Query parameters

  • master_timeout string

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

    Values are -1 or 0.

Responses

  • 200 application/json
POST /_data_stream/_promote/{name}
POST /_data_stream/_promote/my-data-stream
resp = client.indices.promote_data_stream(
    name="my-data-stream",
)
const response = await client.indices.promoteDataStream({
  name: "my-data-stream",
});
response = client.indices.promote_data_stream(
  name: "my-data-stream"
)
$resp = $client->indices()->promoteDataStream([
    "name" => "my-data-stream",
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_data_stream/_promote/my-data-stream"
client.indices().promoteDataStream(p -> p
    .name("my-data-stream")
);





Create a new document in the index Generally available; Added in 5.0.0

POST /{index}/_create/{id}

All methods and paths for this operation:

PUT /{index}/_create/{id}

POST /{index}/_create/{id}

You can index a new JSON document with the /<target>/_doc/ or /<target>/_create/<_id> APIs Using _create guarantees that the document is indexed only if it does not already exist. It returns a 409 response when a document with a same ID already exists in the index. To update an existing document, you must use the /<target>/_doc/ API.

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

  • To add a document using the PUT /<target>/_create/<_id> or POST /<target>/_create/<_id> request formats, you must have the create_doc, create, index, or write index privilege.
  • To automatically create a data stream or index with this API request, you must have the auto_configure, create_index, or manage index privilege.

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

Automatically create data streams and indices

If the request's target doesn't exist and matches an index template with a data_stream definition, the index operation automatically creates the data stream.

If the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.

NOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.

If no mapping exists, the index operation creates a dynamic mapping. By default, new fields and objects are automatically added to the mapping if needed.

Automatic index creation is controlled by the action.auto_create_index setting. If it is true, any index can be created automatically. You can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to false to turn off automatic index creation entirely. Specify a comma-separated list of patterns you want to allow or prefix each pattern with + or - to indicate whether it should be allowed or blocked. When a list is specified, the default behaviour is to disallow.

NOTE: The action.auto_create_index setting affects the automatic creation of indices only. It does not affect the creation of data streams.

Routing

By default, shard placement — or routing — is controlled by using a hash of the document's ID value. For more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the routing parameter.

When setting up explicit mapping, you can also use the _routing field to direct the index operation to extract the routing value from the document itself. This does come at the (very minimal) cost of an additional document parsing pass. If the _routing mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.

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

Distributed

The index operation is directed to the primary shard based on its route and performed on the actual node containing this shard. After the primary shard completes the operation, if needed, the update is distributed to applicable replicas.

Active shards

To improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation. If the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs. By default, write operations only wait for the primary shards to be active before proceeding (that is to say wait_for_active_shards is 1). This default can be overridden in the index settings dynamically by setting index.write.wait_for_active_shards. To alter this behavior per operation, use the wait_for_active_shards request parameter.

Valid values are all or any positive integer up to the total number of configured copies per shard in the index (which is number_of_replicas+1). Specifying a negative value or a number greater than the number of shard copies will throw an error.

For example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes). If you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding. This means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data. If wait_for_active_shards is set on the request to 3 (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding. This requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard. However, if you set wait_for_active_shards to all (or to 4, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index. The operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.

It is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts. After the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary. The _shards section of the API response reveals the number of shard copies on which replication succeeded and failed.

Required authorization

  • Index privileges: create
External documentation

Path parameters

  • index string Required

    The name of the data stream or index to target. If the target doesn't exist and matches the name or wildcard (*) pattern of an index template with a data_stream definition, this request creates the data stream. If the target doesn't exist and doesn’t match a data stream template, this request creates the index.

  • id string Required

    A unique identifier for the document. To automatically generate a document ID, use the POST /<target>/_doc/ request format.

Query parameters

  • include_source_on_error boolean

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

  • pipeline string

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

  • refresh string

    If true, Elasticsearch refreshes the affected shards to make this operation visible to search. If wait_for, it waits for a refresh to make this operation visible to search. If false, it does nothing with refreshes.

    Values are true, false, or wait_for.

  • require_alias boolean

    If true, the destination must be an index alias.

  • require_data_stream boolean

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

  • routing string

    A custom value that is used to route operations to a specific shard.

  • timeout string

    The period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards. Elasticsearch waits for at least the specified timeout period before failing. The actual wait time could be longer, particularly when multiple waits occur.

    This parameter is useful for situations where the primary shard assigned to perform the operation might not be available when the operation runs. Some reasons for this might be that the primary shard is currently recovering from a gateway or undergoing relocation. By default, the operation will wait on the primary shard to become available for at least 1 minute before failing and responding with an error. The actual wait time could be longer, particularly when multiple waits occur.

    Values are -1 or 0.

  • version number

    The explicit version number for concurrency control. It must be a non-negative long number.

  • version_type string

    The version type.

    Supported values include:

    • internal: Use internal versioning that starts at 1 and increments with each update or delete.
    • external: Only index the document if the specified version is strictly higher than the version of the stored document or if there is no existing document.
    • external_gte: Only index the document if the specified version is equal or higher than the version of the stored document or if there is no existing document. NOTE: The external_gte version type is meant for special use cases and should be used with care. If used incorrectly, it can result in loss of data.
    • force: This option is deprecated because it can cause primary and replica shards to diverge.

    Values are internal, external, external_gte, or force.

  • wait_for_active_shards number | string

    The number of shard copies that must be active before proceeding with the operation. You can set it to all or any positive integer up to the total number of shards in the index (number_of_replicas+1). The default value of 1 means it waits for each primary shard to be active.

    Values are all or index-setting.

application/json

Body Required

object object

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • _id string Required
    • _index string Required
    • _primary_term number

      The primary term assigned to the document for the indexing operation.

    • result string Required

      Values are created, updated, deleted, not_found, or noop.

    • _seq_no number
    • _shards object Required
      Hide _shards attributes Show _shards attributes object
      • failed number Required
      • successful number Required
      • total number Required
      • failures array[object]
        Hide failures attributes Show failures attributes object
        • index string
        • node string
        • reason object Required

          Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

          Hide reason attributes Show reason attributes object
          • type string Required

            The type of error

          • reason string | null

            A human-readable explanation of the error, in English.

          • stack_trace string

            The server stack trace. Present only if the error_trace=true parameter was sent with the request.

          • caused_by object

            Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

          • root_cause array[object]

            Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

            Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

          • suppressed array[object]

            Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

            Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

        • shard number Required
        • status string
      • skipped number
    • _version number Required
    • forced_refresh boolean
PUT my-index-000001/_create/1
{
  "@timestamp": "2099-11-15T13:12:00",
  "message": "GET /search HTTP/1.1 200 1070000",
  "user": {
    "id": "kimchy"
  }
}
resp = client.create(
    index="my-index-000001",
    id="1",
    document={
        "@timestamp": "2099-11-15T13:12:00",
        "message": "GET /search HTTP/1.1 200 1070000",
        "user": {
            "id": "kimchy"
        }
    },
)
const response = await client.create({
  index: "my-index-000001",
  id: 1,
  document: {
    "@timestamp": "2099-11-15T13:12:00",
    message: "GET /search HTTP/1.1 200 1070000",
    user: {
      id: "kimchy",
    },
  },
});
response = client.create(
  index: "my-index-000001",
  id: "1",
  body: {
    "@timestamp": "2099-11-15T13:12:00",
    "message": "GET /search HTTP/1.1 200 1070000",
    "user": {
      "id": "kimchy"
    }
  }
)
$resp = $client->create([
    "index" => "my-index-000001",
    "id" => "1",
    "body" => [
        "@timestamp" => "2099-11-15T13:12:00",
        "message" => "GET /search HTTP/1.1 200 1070000",
        "user" => [
            "id" => "kimchy",
        ],
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"@timestamp":"2099-11-15T13:12:00","message":"GET /search HTTP/1.1 200 1070000","user":{"id":"kimchy"}}' "$ELASTICSEARCH_URL/my-index-000001/_create/1"
client.create(c -> c
    .id("1")
    .index("my-index-000001")
    .document(JsonData.fromJson("{\"@timestamp\":\"2099-11-15T13:12:00\",\"message\":\"GET /search HTTP/1.1 200 1070000\",\"user\":{\"id\":\"kimchy\"}}"))
);
Request example
Run `PUT my-index-000001/_create/1` to index a document into the `my-index-000001` index if no document with that ID exists.
{
  "@timestamp": "2099-11-15T13:12:00",
  "message": "GET /search HTTP/1.1 200 1070000",
  "user": {
    "id": "kimchy"
  }
}
Response examples (200)
A successful response from `PUT my-index-000001/_create/1` which indexes a document.
{
   "_index": "my-index-000001",
   "_id": "1",
   "_version": 1,
   "result": "created",
   "_shards": {
     "total": 1,
     "successful": 1,
     "failed": 0
   },
   "_seq_no": 0,
   "_primary_term": 1
}








Delete a document Generally available

DELETE /{index}/_doc/{id}

Remove a JSON document from the specified index.

NOTE: You cannot send deletion requests directly to a data stream. To delete a document in a data stream, you must target the backing index containing the document.

Optimistic concurrency control

Delete operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the if_seq_no and if_primary_term parameters. If a mismatch is detected, the operation will result in a VersionConflictException and a status code of 409.

Versioning

Each document indexed is versioned. When deleting a document, the version can be specified to make sure the relevant document you are trying to delete is actually being deleted and it has not changed in the meantime. Every write operation run on a document, deletes included, causes its version to be incremented. The version number of a deleted document remains available for a short time after deletion to allow for control of concurrent operations. The length of time for which a deleted document's version remains available is determined by the index.gc_deletes index setting.

Routing

If routing is used during indexing, the routing value also needs to be specified to delete a document.

If the _routing mapping is set to required and no routing value is specified, the delete API throws a RoutingMissingException and rejects the request.

For example:

DELETE /my-index-000001/_doc/1?routing=shard-1

This request deletes the document with ID 1, but it is routed based on the user. The document is not deleted if the correct routing is not specified.

Distributed

The delete operation gets hashed into a specific shard ID. It then gets redirected into the primary shard within that ID group and replicated (if needed) to shard replicas within that ID group.

Required authorization

  • Index privileges: delete

Path parameters

  • index string Required

    The name of the target index.

  • id string Required

    A unique identifier for the document.

Query parameters

  • if_primary_term number

    Only perform the operation if the document has this primary term.

  • if_seq_no number

    Only perform the operation if the document has this sequence number.

  • refresh string

    If true, Elasticsearch refreshes the affected shards to make this operation visible to search. If wait_for, it waits for a refresh to make this operation visible to search. If false, it does nothing with refreshes.

    Values are true, false, or wait_for.

  • routing string

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

  • timeout string

    The period to wait for active shards.

    This parameter is useful for situations where the primary shard assigned to perform the delete operation might not be available when the delete operation runs. Some reasons for this might be that the primary shard is currently recovering from a store or undergoing relocation. By default, the delete operation will wait on the primary shard to become available for up to 1 minute before failing and responding with an error.

    Values are -1 or 0.

  • version number

    An explicit version number for concurrency control. It must match the current version of the document for the request to succeed.

  • version_type string

    The version type.

    Supported values include:

    • internal: Use internal versioning that starts at 1 and increments with each update or delete.
    • external: Only index the document if the specified version is strictly higher than the version of the stored document or if there is no existing document.
    • external_gte: Only index the document if the specified version is equal or higher than the version of the stored document or if there is no existing document. NOTE: The external_gte version type is meant for special use cases and should be used with care. If used incorrectly, it can result in loss of data.
    • force: This option is deprecated because it can cause primary and replica shards to diverge.

    Values are internal, external, external_gte, or force.

  • wait_for_active_shards number | string

    The minimum number of shard copies that must be active before proceeding with the operation. You can set it to all or any positive integer up to the total number of shards in the index (number_of_replicas+1). The default value of 1 means it waits for each primary shard to be active.

    Values are all or index-setting.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • _id string Required
    • _index string Required
    • _primary_term number

      The primary term assigned to the document for the indexing operation.

    • result string Required

      Values are created, updated, deleted, not_found, or noop.

    • _seq_no number
    • _shards object Required
      Hide _shards attributes Show _shards attributes object
      • failed number Required
      • successful number Required
      • total number Required
      • failures array[object]
        Hide failures attributes Show failures attributes object
        • index string
        • node string
        • reason object Required

          Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

          Hide reason attributes Show reason attributes object
          • type string Required

            The type of error

          • reason string | null

            A human-readable explanation of the error, in English.

          • stack_trace string

            The server stack trace. Present only if the error_trace=true parameter was sent with the request.

          • caused_by object

            Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

          • root_cause array[object]

            Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

            Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

          • suppressed array[object]

            Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

            Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

        • shard number Required
        • status string
      • skipped number
    • _version number Required
    • forced_refresh boolean
DELETE /my-index-000001/_doc/1
resp = client.delete(
    index="my-index-000001",
    id="1",
)
const response = await client.delete({
  index: "my-index-000001",
  id: 1,
});
response = client.delete(
  index: "my-index-000001",
  id: "1"
)
$resp = $client->delete([
    "index" => "my-index-000001",
    "id" => "1",
]);
curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/my-index-000001/_doc/1"
client.delete(d -> d
    .id("1")
    .index("my-index-000001")
);
Response examples (200)
A successful response from `DELETE /my-index-000001/_doc/1`, which deletes the JSON document 1 from the `my-index-000001` index.
{
  "_shards": {
    "total": 2,
    "failed": 0,
    "successful": 2
  },
  "_index": "my-index-000001",
  "_id": "1",
  "_version": 2,
  "_primary_term": 1,
  "_seq_no": 5,
  "result": "deleted"
}
































Throttle a reindex operation Generally available; Added in 2.4.0

POST /_reindex/{task_id}/_rethrottle

Change the number of requests per second for a particular reindex operation. For example:

POST _reindex/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1

Rethrottling that speeds up the query takes effect immediately. Rethrottling that slows down the query will take effect after completing the current batch. This behavior prevents scroll timeouts.

Path parameters

  • task_id string Required

    The task identifier, which can be found by using the tasks API.

Query parameters

  • requests_per_second number

    The throttle for this request in sub-requests per second. It can be either -1 to turn off throttling or any decimal number like 1.7 or 12 to throttle to that level.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • nodes object Required
POST /_reindex/{task_id}/_rethrottle
POST _reindex/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1
resp = client.reindex_rethrottle(
    task_id="r1A2WoRbTwKZ516z6NEs5A:36619",
    requests_per_second="-1",
)
const response = await client.reindexRethrottle({
  task_id: "r1A2WoRbTwKZ516z6NEs5A:36619",
  requests_per_second: "-1",
});
response = client.reindex_rethrottle(
  task_id: "r1A2WoRbTwKZ516z6NEs5A:36619",
  requests_per_second: "-1"
)
$resp = $client->reindexRethrottle([
    "task_id" => "r1A2WoRbTwKZ516z6NEs5A:36619",
    "requests_per_second" => "-1",
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_reindex/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1"
client.reindexRethrottle(r -> r
    .requestsPerSecond(-1.0F)
    .taskId("r1A2WoRbTwKZ516z6NEs5A:36619")
);












Throttle an update by query operation Generally available; Added in 6.5.0

POST /_update_by_query/{task_id}/_rethrottle

Change the number of requests per second for a particular update by query operation. Rethrottling that speeds up the query takes effect immediately but rethrotting that slows down the query takes effect after completing the current batch to prevent scroll timeouts.

Path parameters

  • task_id string Required

    The ID for the task.

Query parameters

  • requests_per_second number

    The throttle for this request in sub-requests per second. To turn off throttling, set it to -1.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • nodes object Required
POST /_update_by_query/{task_id}/_rethrottle
POST _update_by_query/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1
resp = client.update_by_query_rethrottle(
    task_id="r1A2WoRbTwKZ516z6NEs5A:36619",
    requests_per_second="-1",
)
const response = await client.updateByQueryRethrottle({
  task_id: "r1A2WoRbTwKZ516z6NEs5A:36619",
  requests_per_second: "-1",
});
response = client.update_by_query_rethrottle(
  task_id: "r1A2WoRbTwKZ516z6NEs5A:36619",
  requests_per_second: "-1"
)
$resp = $client->updateByQueryRethrottle([
    "task_id" => "r1A2WoRbTwKZ516z6NEs5A:36619",
    "requests_per_second" => "-1",
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_update_by_query/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1"
client.updateByQueryRethrottle(u -> u
    .requestsPerSecond(-1.0F)
    .taskId("r1A2WoRbTwKZ516z6NEs5A:36619")
);

Get an enrich policy Generally available; Added in 7.5.0

GET /_enrich/policy/{name}

All methods and paths for this operation:

GET /_enrich/policy

GET /_enrich/policy/{name}

Returns information about an enrich policy.

Path parameters

  • name string | array[string] Required

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

Query parameters

  • master_timeout string

    Period to wait for a connection to the master node.

    Values are -1 or 0.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • policies array[object] Required
      Hide policies attribute Show policies attribute object
      • config object Required
        Hide config attribute Show config attribute object
        • * object Additional properties
          Hide * attributes Show * attributes object
          • enrich_fields string | array[string] Required
          • indices string | array[string] Required
          • match_field string Required

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • query object

            An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

            External documentation
          • name string
          • elasticsearch_version string
GET /_enrich/policy/my-policy
resp = client.enrich.get_policy(
    name="my-policy",
)
const response = await client.enrich.getPolicy({
  name: "my-policy",
});
response = client.enrich.get_policy(
  name: "my-policy"
)
$resp = $client->enrich()->getPolicy([
    "name" => "my-policy",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_enrich/policy/my-policy"
client.enrich().getPolicy(g -> g
    .name("my-policy")
);








Run an enrich policy Generally available; Added in 7.5.0

PUT /_enrich/policy/{name}/_execute

Create the enrich index for an existing enrich policy.

Path parameters

  • name string Required

    Enrich policy to execute.

Query parameters

  • master_timeout string

    Period to wait for a connection to the master node.

    Values are -1 or 0.

  • wait_for_completion boolean

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

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • status object
      Hide status attributes Show status attributes object
      • phase string Required

        Values are SCHEDULED, RUNNING, COMPLETE, FAILED, or CANCELLED.

      • step string
    • task string | number

PUT /_enrich/policy/{name}/_execute
PUT /_enrich/policy/my-policy/_execute?wait_for_completion=false
resp = client.enrich.execute_policy(
    name="my-policy",
    wait_for_completion=False,
)
const response = await client.enrich.executePolicy({
  name: "my-policy",
  wait_for_completion: "false",
});
response = client.enrich.execute_policy(
  name: "my-policy",
  wait_for_completion: "false"
)
$resp = $client->enrich()->executePolicy([
    "name" => "my-policy",
    "wait_for_completion" => "false",
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_enrich/policy/my-policy/_execute?wait_for_completion=false"
client.enrich().executePolicy(e -> e
    .name("my-policy")
    .waitForCompletion(false)
);




EQL

Event Query Language (EQL) is a query language for event-based time series data, such as logs, metrics, and traces.

Learn more about EQL search








Get the async EQL status Generally available; Added in 7.9.0

GET /_eql/search/status/{id}

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

Path parameters

  • id string Required

    Identifier for the search.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • id string Required
    • is_partial boolean Required

      If true, the search request is still executing. If false, the search is completed.

    • is_running boolean Required

      If true, the response does not contain complete search results. This could be because either the search is still running (is_running status is false), or because it is already completed (is_running status is true) and results are partial due to failures or timeouts.

    • start_time_in_millis number

      Time unit for milliseconds

    • expiration_time_in_millis number

      Time unit for milliseconds

    • completion_status number

      For a completed search shows the http status code of the completed search.

GET /_eql/search/status/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=
resp = client.eql.get_status(
    id="FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
)
const response = await client.eql.getStatus({
  id: "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
});
response = client.eql.get_status(
  id: "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE="
)
$resp = $client->eql()->getStatus([
    "id" => "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_eql/search/status/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE="
client.eql().getStatus(g -> g
    .id("FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=")
);
Response examples (200)
A successful response for getting status information for an async EQL search.
{
  "id": "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
  "is_running" : true,
  "is_partial" : true,
  "start_time_in_millis" : 1611690235000,
  "expiration_time_in_millis" : 1611690295000
}

























Features

The feature APIs enable you to introspect and manage features provided by Elasticsearch and Elasticsearch plugins.








































Check component templates Generally available; Added in 7.8.0

HEAD /_component_template/{name}

Returns information about whether a particular component template exists.

Path parameters

  • name string | array[string] Required

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

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.

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

Responses

  • 200 application/json
HEAD /_component_template/{name}
curl \
 --request HEAD 'http://api.example.com/_component_template/{name}' \
 --header "Authorization: $API_KEY"




































































Delete an index template Generally available; Added in 7.8.0

DELETE /_index_template/{name}

The provided may contain multiple template names separated by a comma. If multiple template names are specified then there is no wildcard support and the provided names should match completely with existing templates.

Required authorization

  • Cluster privileges: manage_index_templates

Path parameters

  • name string | array[string] Required

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

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 /_index_template/my-index-template
resp = client.indices.delete_index_template(
    name="my-index-template",
)
const response = await client.indices.deleteIndexTemplate({
  name: "my-index-template",
});
response = client.indices.delete_index_template(
  name: "my-index-template"
)
$resp = $client->indices()->deleteIndexTemplate([
    "name" => "my-index-template",
]);
curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_index_template/my-index-template"
client.indices().deleteIndexTemplate(d -> d
    .name("my-index-template")
);












Delete a legacy index template Deprecated Generally available

DELETE /_template/{name}

IMPORTANT: This documentation is about legacy index templates, which are deprecated and will be replaced by the composable templates introduced in Elasticsearch 7.8.

Required authorization

  • Cluster privileges: manage_index_templates

Path parameters

  • name string Required

    The name of the legacy index template to delete. Wildcard (*) expressions are supported.

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 _template/.cloud-hot-warm-allocation-0
resp = client.indices.delete_template(
    name=".cloud-hot-warm-allocation-0",
)
const response = await client.indices.deleteTemplate({
  name: ".cloud-hot-warm-allocation-0",
});
response = client.indices.delete_template(
  name: ".cloud-hot-warm-allocation-0"
)
$resp = $client->indices()->deleteTemplate([
    "name" => ".cloud-hot-warm-allocation-0",
]);
curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_template/.cloud-hot-warm-allocation-0"
client.indices().deleteTemplate(d -> d
    .name(".cloud-hot-warm-allocation-0")
);




Analyze the index disk usage Technical preview; Added in 7.15.0

POST /{index}/_disk_usage

Analyze the disk usage of each field of an index or data stream. This API might not support indices created in previous Elasticsearch versions. The result of a small index can be inaccurate as some parts of an index might not be analyzed by the API.

NOTE: The total size of fields of the analyzed shards of the index in the response is usually smaller than the index store_size value because some small metadata files are ignored and some parts of data files might not be scanned by the API. Since stored fields are stored together in a compressed format, the sizes of stored fields are also estimates and can be inaccurate. The stored size of the _id field is likely underestimated while the _source field is overestimated.

Path parameters

  • index string | array[string] Required

    Comma-separated list of data streams, indices, and aliases used to limit the request. It’s recommended to execute this API with a single index (or the latest backing index of a data stream) as the API consumes resources significantly.

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.

  • flush boolean

    If true, the API performs a flush before analysis. If false, the response may not include uncommitted data.

  • ignore_unavailable boolean

    If true, missing or closed indices are not included in the response.

  • run_expensive_tasks boolean

    Analyzing field disk usage is resource-intensive. To use the API, this parameter must be set to true.

Responses

  • 200 application/json
POST /my-index-000001/_disk_usage?run_expensive_tasks=true
resp = client.indices.disk_usage(
    index="my-index-000001",
    run_expensive_tasks=True,
)
const response = await client.indices.diskUsage({
  index: "my-index-000001",
  run_expensive_tasks: "true",
});
response = client.indices.disk_usage(
  index: "my-index-000001",
  run_expensive_tasks: "true"
)
$resp = $client->indices()->diskUsage([
    "index" => "my-index-000001",
    "run_expensive_tasks" => "true",
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/my-index-000001/_disk_usage?run_expensive_tasks=true"
client.indices().diskUsage(d -> d
    .index("my-index-000001")
    .runExpensiveTasks(true)
);








































































Get index shard stores Generally available

GET /{index}/_shard_stores

All methods and paths for this operation:

GET /_shard_stores

GET /{index}/_shard_stores

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

The index shard stores API returns the following information:

  • The node on which each replica shard exists.
  • The allocation ID for each replica shard.
  • A unique ID for each replica shard.
  • Any errors encountered while opening the shard index or from an earlier failure.

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

Required authorization

  • Index privileges: monitor

Path parameters

  • index string | array[string] Required

    List of data streams, indices, and aliases used to limit the request.

Query parameters

  • allow_no_indices boolean

    If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.

  • expand_wildcards string | array[string]

    Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.

    Supported values include:

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

    Values are all, open, closed, hidden, or none.

  • ignore_unavailable boolean

    If true, missing or closed indices are not included in the response.

  • status string | array[string]

    List of shard health statuses used to limit the request.

    Supported values include:

    • green: The primary shard and all replica shards are assigned.
    • yellow: One or more replica shards are unassigned.
    • red: The primary shard is unassigned.
    • all: Return all shards, regardless of health status.

    Values are green, yellow, red, or all.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • indices object Required
      Hide indices attribute Show indices attribute object
      • * object Additional properties
        Hide * attribute Show * attribute object
        • shards object Required
          Hide shards attribute Show shards attribute object
          • * object Additional properties
            Hide * attribute Show * attribute object
            • stores array[object] Required
GET /_shard_stores?status=green
resp = client.indices.shard_stores(
    status="green",
)
const response = await client.indices.shardStores({
  status: "green",
});
response = client.indices.shard_stores(
  status: "green"
)
$resp = $client->indices()->shardStores([
    "status" => "green",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_shard_stores?status=green"
Response examples (200)
An abbreviated response from `GET /_shard_stores?status=green`.
{
  "indices": {
    "my-index-000001": {
      "shards": {
        "0": {
          "stores": [
            {
              "sPa3OgxLSYGvQ4oPs-Tajw": {
                "name": "node_t0",
                "ephemeral_id": "9NlXRFGCT1m8tkvYCMK-8A",
                "transport_address": "local[1]",
                "external_id": "node_t0",
                "attributes": {},
                "roles": [],
                "version": "8.10.0",
                "min_index_version": 7000099,
                "max_index_version": 8100099
              },
              "allocation_id": "2iNySv_OQVePRX-yaRH_lQ",
              "allocation": "primary",
              "store_exception": {}
            }
          ]
        }
      }
    }
  }
}




















Unfreeze an index Deprecated Generally available; Added in 6.6.0

POST /{index}/_unfreeze

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

Required authorization

  • Index privileges: manage

Path parameters

  • index string Required

    Identifier for the index.

Query parameters

  • allow_no_indices boolean

    If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.

  • expand_wildcards string | array[string]

    Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.

    Supported values include:

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

    Values are all, open, closed, hidden, or none.

  • ignore_unavailable boolean

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

  • master_timeout string

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

    Values are -1 or 0.

  • timeout string

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

    Values are -1 or 0.

  • wait_for_active_shards string

    The number of shard copies that must be active before proceeding with the operation. Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • acknowledged boolean Required
    • shards_acknowledged boolean Required
POST /{index}/_unfreeze
curl \
 --request POST 'http://api.example.com/{index}/_unfreeze' \
 --header "Authorization: $API_KEY"

























Get the ILM status Generally available; Added in 6.6.0

GET /_ilm/status

Get the current index lifecycle management status.

Required authorization

  • Cluster privileges: read_ilm

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • operation_mode string Required

      Values are RUNNING, STOPPING, or STOPPED.

GET _ilm/status
resp = client.ilm.get_status()
const response = await client.ilm.getStatus();
response = client.ilm.get_status
$resp = $client->ilm()->getStatus();
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ilm/status"
client.ilm().getStatus();
Response examples (200)
A successful response when retrieving the current ILM status.
{
  "operation_mode": "RUNNING"
}













































































Create an ELSER inference endpoint Deprecated Generally available; Added in 8.11.0

PUT /_inference/{task_type}/{elser_inference_id}

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


Your Elasticsearch deployment contains a preconfigured ELSER inference endpoint, you only need to create the enpoint using the API if you want to customize the settings.

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


You might see a 502 bad gateway error in the response when using the Kibana Console. This error usually just reflects a timeout, while the model downloads in the background. You can check the download progress in the Machine Learning UI. If using the Python client, you can set the timeout parameter to a higher value.

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

Required authorization

  • Cluster privileges: manage_inference

Path parameters

  • task_type string

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

    Value is sparse_embedding.

  • elser_inference_id string Required

    The unique identifier of the inference endpoint.

Query parameters

  • timeout string

    Specifies the amount of time to wait for the inference endpoint to be created.

    Values are -1 or 0.

application/json

Body

  • chunking_settings object

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

      Default value is 250.

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

      Default value is 100.

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

      Default value is 1.

    • strategy string

      The chunking strategy: sentence or word.

      Default value is sentence.

  • service string Required

    Value is elser.

  • service_settings object Required
    Hide service_settings attributes Show service_settings attributes object
    • adaptive_allocations object
      Hide adaptive_allocations attributes Show adaptive_allocations attributes object
      • enabled boolean

        Turn on adaptive_allocations.

        Default value is false.

      • max_number_of_allocations number

        The maximum number of allocations to scale to. If set, it must be greater than or equal to min_number_of_allocations.

      • min_number_of_allocations number

        The minimum number of allocations to scale to. If set, it must be greater than or equal to 0. If not defined, the deployment scales to 0.

    • num_allocations number Required

      The total number of allocations this model is assigned across machine learning nodes. Increasing this value generally increases the throughput. If adaptive allocations is enabled, do not set this value because it's automatically set.

    • num_threads number Required

      The number of threads used by each model allocation during inference. Increasing this value generally increases the speed per inference request. The inference process is a compute-bound process; threads_per_allocations must not exceed the number of available allocated processors per node. The value must be a power of 2. The maximum value is 32.


      If you want to optimize your ELSER endpoint for ingest, set the number of threads to 1. If you want to optimize your ELSER endpoint for search, set the number of threads to greater than 1.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • chunking_settings object

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

        Default value is 250.

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

        Default value is 100.

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

        Default value is 1.

      • strategy string

        The chunking strategy: sentence or word.

        Default value is sentence.

    • service string Required

      The service type

    • service_settings object Required
    • task_settings object
    • inference_id string Required

      The inference Id

    • task_type string Required

      Value is sparse_embedding.

PUT /_inference/{task_type}/{elser_inference_id}
PUT _inference/sparse_embedding/my-elser-model
{
    "service": "elser",
    "service_settings": {
        "num_allocations": 1,
        "num_threads": 1
    }
}
resp = client.inference.put(
    task_type="sparse_embedding",
    inference_id="my-elser-model",
    inference_config={
        "service": "elser",
        "service_settings": {
            "num_allocations": 1,
            "num_threads": 1
        }
    },
)
const response = await client.inference.put({
  task_type: "sparse_embedding",
  inference_id: "my-elser-model",
  inference_config: {
    service: "elser",
    service_settings: {
      num_allocations: 1,
      num_threads: 1,
    },
  },
});
response = client.inference.put(
  task_type: "sparse_embedding",
  inference_id: "my-elser-model",
  body: {
    "service": "elser",
    "service_settings": {
      "num_allocations": 1,
      "num_threads": 1
    }
  }
)
$resp = $client->inference()->put([
    "task_type" => "sparse_embedding",
    "inference_id" => "my-elser-model",
    "body" => [
        "service" => "elser",
        "service_settings" => [
            "num_allocations" => 1,
            "num_threads" => 1,
        ],
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"service":"elser","service_settings":{"num_allocations":1,"num_threads":1}}' "$ELASTICSEARCH_URL/_inference/sparse_embedding/my-elser-model"
client.inference().put(p -> p
    .inferenceId("my-elser-model")
    .taskType(TaskType.SparseEmbedding)
    .inferenceConfig(i -> i
        .service("elser")
        .serviceSettings(JsonData.fromJson("{\"num_allocations\":1,\"num_threads\":1}"))
    )
);
Request examples
Run `PUT _inference/sparse_embedding/my-elser-model` to create an inference endpoint that performs a `sparse_embedding` task. The request will automatically download the ELSER model if it isn't already downloaded and then deploy the model.
{
    "service": "elser",
    "service_settings": {
        "num_allocations": 1,
        "num_threads": 1
    }
}
Run `PUT _inference/sparse_embedding/my-elser-model` to create an inference endpoint that performs a `sparse_embedding` task with adaptive allocations. When adaptive allocations are enabled, the number of allocations of the model is set automatically based on the current load.
{
    "service": "elser",
    "service_settings": {
        "adaptive_allocations": {
            "enabled": true,
            "min_number_of_allocations": 3,
            "max_number_of_allocations": 10
        },
        "num_threads": 1
    }
}
Response examples (200)
A successful response when creating an ELSER inference endpoint.
{
  "inference_id": "my-elser-model",
  "task_type": "sparse_embedding",
  "service": "elser",
  "service_settings": {
    "num_allocations": 1,
    "num_threads": 1
  },
  "task_settings": {}
}

Create an Google AI Studio inference endpoint Generally available; Added in 8.15.0

PUT /_inference/{task_type}/{googleaistudio_inference_id}

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

Required authorization

  • Cluster privileges: manage_inference

Path parameters

  • task_type string

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

    Values are completion or text_embedding.

  • googleaistudio_inference_id string Required

    The unique identifier of the inference endpoint.

Query parameters

  • timeout string

    Specifies the amount of time to wait for the inference endpoint to be created.

    Values are -1 or 0.

application/json

Body

  • chunking_settings object

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

      Default value is 250.

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

      Default value is 100.

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

      Default value is 1.

    • strategy string

      The chunking strategy: sentence or word.

      Default value is sentence.

  • service string Required

    Value is googleaistudio.

  • service_settings object Required
    Hide service_settings attributes Show service_settings attributes object
    • api_key string Required

      A valid API key of your Google Gemini account.

    • model_id string Required

      The name of the model to use for the inference task. Refer to the Google documentation for the list of supported models.

      External documentation
    • rate_limit object
      Hide rate_limit attribute Show rate_limit attribute object
      • requests_per_minute number

        The number of requests allowed per minute.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • chunking_settings object

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

        Default value is 250.

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

        Default value is 100.

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

        Default value is 1.

      • strategy string

        The chunking strategy: sentence or word.

        Default value is sentence.

    • 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 completion.

PUT /_inference/{task_type}/{googleaistudio_inference_id}
PUT _inference/completion/google_ai_studio_completion
{
    "service": "googleaistudio",
    "service_settings": {
        "api_key": "api-key",
        "model_id": "model-id"
    }
}
resp = client.inference.put(
    task_type="completion",
    inference_id="google_ai_studio_completion",
    inference_config={
        "service": "googleaistudio",
        "service_settings": {
            "api_key": "api-key",
            "model_id": "model-id"
        }
    },
)
const response = await client.inference.put({
  task_type: "completion",
  inference_id: "google_ai_studio_completion",
  inference_config: {
    service: "googleaistudio",
    service_settings: {
      api_key: "api-key",
      model_id: "model-id",
    },
  },
});
response = client.inference.put(
  task_type: "completion",
  inference_id: "google_ai_studio_completion",
  body: {
    "service": "googleaistudio",
    "service_settings": {
      "api_key": "api-key",
      "model_id": "model-id"
    }
  }
)
$resp = $client->inference()->put([
    "task_type" => "completion",
    "inference_id" => "google_ai_studio_completion",
    "body" => [
        "service" => "googleaistudio",
        "service_settings" => [
            "api_key" => "api-key",
            "model_id" => "model-id",
        ],
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"service":"googleaistudio","service_settings":{"api_key":"api-key","model_id":"model-id"}}' "$ELASTICSEARCH_URL/_inference/completion/google_ai_studio_completion"
client.inference().put(p -> p
    .inferenceId("google_ai_studio_completion")
    .taskType(TaskType.Completion)
    .inferenceConfig(i -> i
        .service("googleaistudio")
        .serviceSettings(JsonData.fromJson("{\"api_key\":\"api-key\",\"model_id\":\"model-id\"}"))
    )
);
Request example
Run `PUT _inference/completion/google_ai_studio_completion` to create an inference endpoint to perform a `completion` task type.
{
    "service": "googleaistudio",
    "service_settings": {
        "api_key": "api-key",
        "model_id": "model-id"
    }
}




















Create a VoyageAI inference endpoint Generally available; Added in 8.19.0

PUT /_inference/{task_type}/{voyageai_inference_id}

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

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

Required authorization

  • Cluster privileges: manage_inference

Path parameters

  • task_type string

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

    Values are text_embedding or rerank.

  • voyageai_inference_id string Required

    The unique identifier of the inference endpoint.

Query parameters

  • timeout string

    Specifies the amount of time to wait for the inference endpoint to be created.

    Values are -1 or 0.

application/json

Body

  • chunking_settings object

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

      Default value is 250.

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

      Default value is 100.

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

      Default value is 1.

    • strategy string

      The chunking strategy: sentence or word.

      Default value is sentence.

  • service string Required

    Value is voyageai.

  • service_settings object Required
    Hide service_settings attributes Show service_settings attributes object
    • dimensions number

      The number of dimensions for resulting output embeddings. This setting maps to output_dimension in the VoyageAI documentation. Only for the text_embedding task type.

      External documentation
    • model_id string Required

      The name of the model to use for the inference task. Refer to the VoyageAI documentation for the list of available text embedding and rerank models.

      External documentation
    • rate_limit object
      Hide rate_limit attribute Show rate_limit attribute object
      • requests_per_minute number

        The number of requests allowed per minute.

    • embedding_type number

      The data type for the embeddings to be returned. This setting maps to output_dtype in the VoyageAI documentation. Permitted values: float, int8, bit. int8 is a synonym of byte in the VoyageAI documentation. bit is a synonym of binary in the VoyageAI documentation. Only for the text_embedding task type.

      External documentation
  • task_settings object
    Hide task_settings attributes Show task_settings attributes object
    • input_type string

      Type of the input text. Permitted values: ingest (maps to document in the VoyageAI documentation), search (maps to query in the VoyageAI documentation). Only for the text_embedding task type.

    • return_documents boolean

      Whether to return the source documents in the response. Only for the rerank task type.

      Default value is false.

    • top_k number

      The number of most relevant documents to return. If not specified, the reranking results of all documents will be returned. Only for the rerank task type.

    • truncation boolean

      Whether to truncate the input texts to fit within the context length.

      Default value is true.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • chunking_settings object

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

        Default value is 250.

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

        Default value is 100.

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

        Default value is 1.

      • strategy string

        The chunking strategy: sentence or word.

        Default value is sentence.

    • 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}/{voyageai_inference_id}
PUT _inference/text_embedding/openai-embeddings
{
    "service": "voyageai",
    "service_settings": {
        "model_id": "voyage-3-large",
        "dimensions": 512
    }
}
resp = client.inference.put(
    task_type="text_embedding",
    inference_id="openai-embeddings",
    inference_config={
        "service": "voyageai",
        "service_settings": {
            "model_id": "voyage-3-large",
            "dimensions": 512
        }
    },
)
const response = await client.inference.put({
  task_type: "text_embedding",
  inference_id: "openai-embeddings",
  inference_config: {
    service: "voyageai",
    service_settings: {
      model_id: "voyage-3-large",
      dimensions: 512,
    },
  },
});
response = client.inference.put(
  task_type: "text_embedding",
  inference_id: "openai-embeddings",
  body: {
    "service": "voyageai",
    "service_settings": {
      "model_id": "voyage-3-large",
      "dimensions": 512
    }
  }
)
$resp = $client->inference()->put([
    "task_type" => "text_embedding",
    "inference_id" => "openai-embeddings",
    "body" => [
        "service" => "voyageai",
        "service_settings" => [
            "model_id" => "voyage-3-large",
            "dimensions" => 512,
        ],
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"service":"voyageai","service_settings":{"model_id":"voyage-3-large","dimensions":512}}' "$ELASTICSEARCH_URL/_inference/text_embedding/openai-embeddings"
client.inference().put(p -> p
    .inferenceId("openai-embeddings")
    .taskType(TaskType.TextEmbedding)
    .inferenceConfig(i -> i
        .service("voyageai")
        .serviceSettings(JsonData.fromJson("{\"model_id\":\"voyage-3-large\",\"dimensions\":512}"))
    )
);
Request examples
Run `PUT _inference/text_embedding/voyageai-embeddings` to create an inference endpoint that performs a `text_embedding` task. The embeddings created by requests to this endpoint will have 512 dimensions.
{
    "service": "voyageai",
    "service_settings": {
        "model_id": "voyage-3-large",
        "dimensions": 512
    }
}
Run `PUT _inference/rerank/voyageai-rerank` to create an inference endpoint that performs a `rerank` task.
{
    "service": "voyageai",
    "service_settings": {
        "model_id": "rerank-2"
    }
}
















Perform text embedding inference on the service Generally available; Added in 8.11.0

POST /_inference/text_embedding/{inference_id}

Path parameters

  • inference_id string Required

    The inference Id

Query parameters

  • timeout string

    Specifies the amount of time to wait for the inference request to complete.

    Values are -1 or 0.

application/json

Body

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • text_embedding_bytes array[object]

      The text embedding result object for byte representation

      Hide text_embedding_bytes attribute Show text_embedding_bytes attribute object
      • embedding array[number] Required

        Text Embedding results containing bytes are represented as Dense Vectors of bytes.

    • text_embedding array[object]

      The text embedding result object

      Hide text_embedding attribute Show text_embedding attribute object
      • embedding array[number] Required

        Text Embedding results are represented as Dense Vectors of floats.

POST /_inference/text_embedding/{inference_id}
POST _inference/text_embedding/my-cohere-endpoint
{
  "input": "The sky above the port was the color of television tuned to a dead channel.",
  "task_settings": {
    "input_type": "ingest"
  }
}
resp = client.inference.text_embedding(
    inference_id="my-cohere-endpoint",
    input="The sky above the port was the color of television tuned to a dead channel.",
    task_settings={
        "input_type": "ingest"
    },
)
const response = await client.inference.textEmbedding({
  inference_id: "my-cohere-endpoint",
  input:
    "The sky above the port was the color of television tuned to a dead channel.",
  task_settings: {
    input_type: "ingest",
  },
});
response = client.inference.text_embedding(
  inference_id: "my-cohere-endpoint",
  body: {
    "input": "The sky above the port was the color of television tuned to a dead channel.",
    "task_settings": {
      "input_type": "ingest"
    }
  }
)
$resp = $client->inference()->textEmbedding([
    "inference_id" => "my-cohere-endpoint",
    "body" => [
        "input" => "The sky above the port was the color of television tuned to a dead channel.",
        "task_settings" => [
            "input_type" => "ingest",
        ],
    ],
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"input":"The sky above the port was the color of television tuned to a dead channel.","task_settings":{"input_type":"ingest"}}' "$ELASTICSEARCH_URL/_inference/text_embedding/my-cohere-endpoint"
client.inference().textEmbedding(t -> t
    .inferenceId("my-cohere-endpoint")
    .input("The sky above the port was the color of television tuned to a dead channel.")
    .taskSettings(JsonData.fromJson("{\"input_type\":\"ingest\"}"))
);
Request example
Run `POST _inference/text_embedding/my-cohere-endpoint` to perform text embedding on the example sentence using the Cohere integration,
{
  "input": "The sky above the port was the color of television tuned to a dead channel.",
  "task_settings": {
    "input_type": "ingest"
  }
}
Response examples (200)
An abbreviated response from `POST _inference/text_embedding/my-cohere-endpoint`.
{
  "text_embedding": [
    {
      "embedding": [
        {
          0.018569946,
          -0.036895752,
          0.01486969,
          -0.0045204163,
          -0.04385376,
          0.0075950623,
          0.04260254,
          -0.004005432,
          0.007865906,
          0.030792236,
          -0.050476074,
          0.011795044,
          -0.011642456,
          -0.010070801
        }
      ]
    }
  ]
}









Ingest

Ingest APIs enable you to manage tasks and resources related to ingest pipelines and processors.

Get GeoIP database configurations Generally available; Added in 8.15.0

GET /_ingest/geoip/database/{id}

All methods and paths for this operation:

GET /_ingest/geoip/database

GET /_ingest/geoip/database/{id}

Get information about one or more IP geolocation database configurations.

Path parameters

  • id string | array[string] Required

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

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • databases array[object] Required
      Hide databases attributes Show databases attributes object
      • id string Required
      • version number Required
      • modified_date_millis number

        Time unit for milliseconds

      • database object

        The configuration necessary to identify which IP geolocation provider to use to download a database, as well as any provider-specific configuration necessary for such downloading. At present, the only supported providers are maxmind and ipinfo, and the maxmind provider requires that an account_id (string) is configured. A provider (either maxmind or ipinfo) must be specified. The web and local providers can be returned as read only configurations.

        Hide database attributes Show database attributes object
        • name string Required
        • maxmind object
          Hide maxmind attribute Show maxmind attribute object
          • account_id string Required
        • ipinfo object
GET /_ingest/geoip/database/{id}
curl \
 --request GET 'http://api.example.com/_ingest/geoip/database/{id}' \
 --header "Authorization: $API_KEY"

Create or update a GeoIP database configuration Generally available; Added in 8.15.0

PUT /_ingest/geoip/database/{id}

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

Path parameters

  • id string Required

    ID of the database configuration to create or update.

Query parameters

  • master_timeout string

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

    Values are -1 or 0.

  • timeout string

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

    Values are -1 or 0.

application/json

Body Required

  • name string Required
  • maxmind object Required
    Hide maxmind attribute Show maxmind attribute object
    • account_id string Required

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 /_ingest/geoip/database/{id}
curl \
 --request PUT 'http://api.example.com/_ingest/geoip/database/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"name":"string","maxmind":{"account_id":"string"}}'




Get IP geolocation database configurations Generally available; Added in 8.15.0

GET /_ingest/ip_location/database/{id}

All methods and paths for this operation:

GET /_ingest/ip_location/database

GET /_ingest/ip_location/database/{id}

Required authorization

  • Cluster privileges: manage

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

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}
GET /_ingest/ip_location/database/my-database-id
resp = client.ingest.get_ip_location_database(
    id="my-database-id",
)
const response = await client.ingest.getIpLocationDatabase({
  id: "my-database-id",
});
response = client.ingest.get_ip_location_database(
  id: "my-database-id"
)
$resp = $client->ingest()->getIpLocationDatabase([
    "id" => "my-database-id",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ingest/ip_location/database/my-database-id"
client.ingest().getIpLocationDatabase(g -> g
    .id("my-database-id")
);

Create or update an IP geolocation database configuration Generally available; Added in 8.15.0

PUT /_ingest/ip_location/database/{id}

Required authorization

  • Cluster privileges: manage

Path parameters

  • id string Required

    The database configuration identifier.

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.

  • timeout string

    The period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata. If no response is received before the timeout expires, the cluster metadata update still applies but the response indicates that it was not completely acknowledged. A value of -1 indicates that the request should never time out.

    Values are -1 or 0.

application/json

Body Required

The configuration necessary to identify which IP geolocation provider to use to download a database, as well as any provider-specific configuration necessary for such downloading. At present, the only supported providers are maxmind and ipinfo, and the maxmind provider requires that an account_id (string) is configured. A provider (either maxmind or ipinfo) must be specified. The web and local providers can be returned as read only configurations.

  • name string Required
  • maxmind object
    Hide maxmind attribute Show maxmind attribute object
    • account_id string Required
  • ipinfo object

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 /_ingest/ip_location/database/{id}
PUT _ingest/ip_location/database/my-database-1
{
  "name": "GeoIP2-Domain",
  "maxmind": {
    "account_id": "1234567"
  }
}
resp = client.ingest.put_ip_location_database(
    id="my-database-1",
    configuration={
        "name": "GeoIP2-Domain",
        "maxmind": {
            "account_id": "1234567"
        }
    },
)
const response = await client.ingest.putIpLocationDatabase({
  id: "my-database-1",
  configuration: {
    name: "GeoIP2-Domain",
    maxmind: {
      account_id: "1234567",
    },
  },
});
response = client.ingest.put_ip_location_database(
  id: "my-database-1",
  body: {
    "name": "GeoIP2-Domain",
    "maxmind": {
      "account_id": "1234567"
    }
  }
)
$resp = $client->ingest()->putIpLocationDatabase([
    "id" => "my-database-1",
    "body" => [
        "name" => "GeoIP2-Domain",
        "maxmind" => [
            "account_id" => "1234567",
        ],
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"name":"GeoIP2-Domain","maxmind":{"account_id":"1234567"}}' "$ELASTICSEARCH_URL/_ingest/ip_location/database/my-database-1"
client.ingest().putIpLocationDatabase(p -> p
    .id("my-database-1")
    .configuration(c -> c
        .maxmind(m -> m
            .accountId("1234567")
        )
        .name("GeoIP2-Domain")
    )
);
Request example
An example body for a `PUT _ingest/ip_location/database/my-database-1` request.
{
  "name": "GeoIP2-Domain",
  "maxmind": {
    "account_id": "1234567"
  }
}



















































































Set upgrade_mode for ML indices Generally available; Added in 6.7.0

POST /_ml/set_upgrade_mode

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

Required authorization

  • Cluster privileges: manage_ml

Query parameters

  • enabled boolean

    When true, it enables upgrade_mode which temporarily halts all job and datafeed tasks and prohibits new job and datafeed tasks from starting.

  • timeout string

    The time to wait for the request to be completed.

    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 _ml/set_upgrade_mode?enabled=true
resp = client.ml.set_upgrade_mode(
    enabled=True,
)
const response = await client.ml.setUpgradeMode({
  enabled: "true",
});
response = client.ml.set_upgrade_mode(
  enabled: "true"
)
$resp = $client->ml()->setUpgradeMode([
    "enabled" => "true",
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ml/set_upgrade_mode?enabled=true"
client.ml().setUpgradeMode(s -> s
    .enabled(true)
);













































































Delete a model snapshot Generally available; Added in 5.4.0

DELETE /_ml/anomaly_detectors/{job_id}/model_snapshots/{snapshot_id}

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

Required authorization

  • Cluster privileges: manage_ml

Path parameters

  • job_id string Required

    Identifier for the anomaly detection job.

  • snapshot_id string Required

    Identifier for the model snapshot.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • acknowledged boolean Required

      For a successful response, this value is always true. On failure, an exception is returned instead.

DELETE /_ml/anomaly_detectors/{job_id}/model_snapshots/{snapshot_id}
DELETE _ml/anomaly_detectors/farequote/model_snapshots/1491948163
resp = client.ml.delete_model_snapshot(
    job_id="farequote",
    snapshot_id="1491948163",
)
const response = await client.ml.deleteModelSnapshot({
  job_id: "farequote",
  snapshot_id: 1491948163,
});
response = client.ml.delete_model_snapshot(
  job_id: "farequote",
  snapshot_id: "1491948163"
)
$resp = $client->ml()->deleteModelSnapshot([
    "job_id" => "farequote",
    "snapshot_id" => "1491948163",
]);
curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ml/anomaly_detectors/farequote/model_snapshots/1491948163"
client.ml().deleteModelSnapshot(d -> d
    .jobId("farequote")
    .snapshotId("1491948163")
);
Response examples (200)
A successful response when deleting an existing model snapshot.
{
  "acknowledged": true
}




































































































Machine learning data frame analytics










































































Create part of a trained model definition Generally available; Added in 8.0.0

PUT /_ml/trained_models/{model_id}/definition/{part}

Required authorization

  • Cluster privileges: manage_ml

Path parameters

  • model_id string Required

    The unique identifier of the trained model.

  • part number Required

    The definition part number. When the definition is loaded for inference the definition parts are streamed in the order of their part number. The first part must be 0 and the final part must be total_parts - 1.

application/json

Body Required

  • definition string Required

    The definition part for the model. Must be a base64 encoded string.

  • total_definition_length number Required

    The total uncompressed definition length in bytes. Not base64 encoded.

  • total_parts number Required

    The total number of parts that will be uploaded. Must be greater than 0.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • acknowledged boolean Required

      For a successful response, this value is always true. On failure, an exception is returned instead.

PUT /_ml/trained_models/{model_id}/definition/{part}
PUT _ml/trained_models/elastic__distilbert-base-uncased-finetuned-conll03-english/definition/0
{
    "definition": "...",
    "total_definition_length": 265632637,
    "total_parts": 64
}
resp = client.ml.put_trained_model_definition_part(
    model_id="elastic__distilbert-base-uncased-finetuned-conll03-english",
    part="0",
    definition="...",
    total_definition_length=265632637,
    total_parts=64,
)
const response = await client.ml.putTrainedModelDefinitionPart({
  model_id: "elastic__distilbert-base-uncased-finetuned-conll03-english",
  part: 0,
  definition: "...",
  total_definition_length: 265632637,
  total_parts: 64,
});
response = client.ml.put_trained_model_definition_part(
  model_id: "elastic__distilbert-base-uncased-finetuned-conll03-english",
  part: "0",
  body: {
    "definition": "...",
    "total_definition_length": 265632637,
    "total_parts": 64
  }
)
$resp = $client->ml()->putTrainedModelDefinitionPart([
    "model_id" => "elastic__distilbert-base-uncased-finetuned-conll03-english",
    "part" => "0",
    "body" => [
        "definition" => "...",
        "total_definition_length" => 265632637,
        "total_parts" => 64,
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"definition":"...","total_definition_length":265632637,"total_parts":64}' "$ELASTICSEARCH_URL/_ml/trained_models/elastic__distilbert-base-uncased-finetuned-conll03-english/definition/0"
Request example
An example body for a `PUT _ml/trained_models/elastic__distilbert-base-uncased-finetuned-conll03-english/definition/0` request.
{
    "definition": "...",
    "total_definition_length": 265632637,
    "total_parts": 64
}




Start a trained model deployment Generally available; Added in 8.0.0

POST /_ml/trained_models/{model_id}/deployment/_start

It allocates the model to every machine learning node.

Required authorization

  • Cluster privileges: manage_ml

Path parameters

  • model_id string Required

    The unique identifier of the trained model. Currently, only PyTorch models are supported.

Query parameters

  • cache_size number | string

    The inference cache size (in memory outside the JVM heap) per node for the model. The default value is the same size as the model_size_bytes. To disable the cache, 0b can be provided.

  • deployment_id string Generally available; Added in 8.8.0

    A unique identifier for the deployment of the model.

  • number_of_allocations number

    The number of model allocations on each node where the model is deployed. All allocations on a node share the same copy of the model in memory but use a separate set of threads to evaluate the model. Increasing this value generally increases the throughput. If this setting is greater than the number of hardware threads it will automatically be changed to a value less than the number of hardware threads. If adaptive_allocations is enabled, do not set this value, because it’s automatically set.

  • priority string

    The deployment priority.

    Values are normal or low.

  • queue_capacity number

    Specifies the number of inference requests that are allowed in the queue. After the number of requests exceeds this value, new requests are rejected with a 429 error.

  • threads_per_allocation number

    Sets the number of threads used by each model allocation during inference. This generally increases the inference speed. The inference process is a compute-bound process; any number greater than the number of available hardware threads on the machine does not increase the inference speed. If this setting is greater than the number of hardware threads it will automatically be changed to a value less than the number of hardware threads.

  • timeout string

    Specifies the amount of time to wait for the model to deploy.

    Values are -1 or 0.

  • wait_for string

    Specifies the allocation status to wait for before returning.

    Supported values include:

    • started: The trained model is started on at least one node.
    • starting: Trained model deployment is starting but it is not yet deployed on any nodes.
    • fully_allocated: Trained model deployment has started on all valid nodes.

    Values are started, starting, or fully_allocated.

application/json

Body

  • adaptive_allocations object
    Hide adaptive_allocations attributes Show adaptive_allocations attributes object
    • enabled boolean Required

      If true, adaptive_allocations is enabled

    • min_number_of_allocations number

      Specifies the minimum number of allocations to scale to. If set, it must be greater than or equal to 0. If not defined, the deployment scales to 0.

    • max_number_of_allocations number

      Specifies the maximum number of allocations to scale to. If set, it must be greater than or equal to min_number_of_allocations.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • assignment object Required
      Hide assignment attributes Show assignment attributes object
      • adaptive_allocations object | string | null

        One of:
        Hide attributes Show attributes
        • enabled boolean Required

          If true, adaptive_allocations is enabled

        • min_number_of_allocations number

          Specifies the minimum number of allocations to scale to. If set, it must be greater than or equal to 0. If not defined, the deployment scales to 0.

        • max_number_of_allocations number

          Specifies the maximum number of allocations to scale to. If set, it must be greater than or equal to min_number_of_allocations.

      • assignment_state string Required

        Values are started, starting, stopping, or failed.

      • max_assigned_allocations number
      • reason string
      • routing_table object Required

        The allocation state for each node.

        Hide routing_table attribute Show routing_table attribute object
        • * object Additional properties
          Hide * attributes Show * attributes object
          • reason string

            The reason for the current state. It is usually populated only when the routing_state is failed.

          • routing_state string Required

            Values are failed, started, starting, stopped, or stopping.

          • current_allocations number Required

            Current number of allocations.

          • target_allocations number Required

            Target number of allocations.

      • 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:
      • task_parameters object Required
        Hide task_parameters attributes Show task_parameters attributes object
POST /_ml/trained_models/{model_id}/deployment/_start
POST _ml/trained_models/elastic__distilbert-base-uncased-finetuned-conll03-english/deployment/_start?wait_for=started&timeout=1m
resp = client.ml.start_trained_model_deployment(
    model_id="elastic__distilbert-base-uncased-finetuned-conll03-english",
    wait_for="started",
    timeout="1m",
)
const response = await client.ml.startTrainedModelDeployment({
  model_id: "elastic__distilbert-base-uncased-finetuned-conll03-english",
  wait_for: "started",
  timeout: "1m",
});
response = client.ml.start_trained_model_deployment(
  model_id: "elastic__distilbert-base-uncased-finetuned-conll03-english",
  wait_for: "started",
  timeout: "1m"
)
$resp = $client->ml()->startTrainedModelDeployment([
    "model_id" => "elastic__distilbert-base-uncased-finetuned-conll03-english",
    "wait_for" => "started",
    "timeout" => "1m",
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ml/trained_models/elastic__distilbert-base-uncased-finetuned-conll03-english/deployment/_start?wait_for=started&timeout=1m"
client.ml().startTrainedModelDeployment(s -> s
    .modelId("elastic__distilbert-base-uncased-finetuned-conll03-english")
    .timeout(t -> t
        .offset(1)
    )
    .waitFor(DeploymentAllocationState.Started)
);





































Node lifecycle






























Create or update a query ruleset Generally available; Added in 8.10.0

PUT /_query_rules/{ruleset_id}

There is a limit of 100 rules per ruleset. This limit can be increased by using the xpack.applications.rules.max_rules_per_ruleset cluster setting.

IMPORTANT: Due to limitations within pinned queries, you can only select documents using ids or docs, but cannot use both in single rule. It is advised to use one or the other in query rulesets, to avoid errors. Additionally, pinned queries have a maximum limit of 100 pinned hits. If multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.

Required authorization

  • Cluster privileges: manage_search_query_rules
External documentation

Path parameters

  • ruleset_id string Required

    The unique identifier of the query ruleset to be created or updated.

application/json

Body Required

  • rules object | array[object] Required

    One of:
    Hide attributes Show attributes
    • rule_id string Required
    • type string Required

      Values are pinned or exclude.

    • criteria object | array[object] Required

      The criteria that must be met for the rule to be applied. If multiple criteria are specified for a rule, all criteria must be met for the rule to be applied.

      One of:
      Hide attributes Show attributes
      • type string Required

        Values are global, exact, exact_fuzzy, fuzzy, prefix, suffix, contains, lt, lte, gt, gte, or always.

      • metadata string

        The metadata field to match against. This metadata will be used to match against match_criteria sent in the rule. It is required for all criteria types except always.

      • values array[object]

        The values to match against the metadata field. Only one value must match for the criteria to be met. It is required for all criteria types except always.

    • actions object Required
      Hide actions attributes Show actions attributes object
      • ids array[string]

        The unique document IDs of the documents to apply the rule to. Only one of ids or docs may be specified and at least one must be specified.

      • docs array[object]

        The documents to apply the rule to. Only one of ids or docs may be specified and at least one must be specified. There is a maximum value of 100 documents in a rule. You can specify the following attributes for each document:

        • _index: The index of the document to pin.
        • _id: The unique document ID.
        Hide docs attributes Show docs attributes object
        • _id string Required
        • _index string Required
    • priority number

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • result string Required

      Values are created, updated, deleted, not_found, or noop.

PUT _query_rules/my-ruleset
{
    "rules": [
        {
            "rule_id": "my-rule1",
            "type": "pinned",
            "criteria": [
                {
                    "type": "contains",
                    "metadata": "user_query",
                    "values": [ "pugs", "puggles" ]
                },
                {
                    "type": "exact",
                    "metadata": "user_country",
                    "values": [ "us" ]
                }
            ],
            "actions": {
                "ids": [
                    "id1",
                    "id2"
                ]
            }
        },
        {
            "rule_id": "my-rule2",
            "type": "pinned",
            "criteria": [
                {
                    "type": "fuzzy",
                    "metadata": "user_query",
                    "values": [ "rescue dogs" ]
                }
            ],
            "actions": {
                "docs": [
                    {
                        "_index": "index1",
                        "_id": "id3"
                    },
                    {
                        "_index": "index2",
                        "_id": "id4"
                    }
                ]
            }
        }
    ]
}
resp = client.query_rules.put_ruleset(
    ruleset_id="my-ruleset",
    rules=[
        {
            "rule_id": "my-rule1",
            "type": "pinned",
            "criteria": [
                {
                    "type": "contains",
                    "metadata": "user_query",
                    "values": [
                        "pugs",
                        "puggles"
                    ]
                },
                {
                    "type": "exact",
                    "metadata": "user_country",
                    "values": [
                        "us"
                    ]
                }
            ],
            "actions": {
                "ids": [
                    "id1",
                    "id2"
                ]
            }
        },
        {
            "rule_id": "my-rule2",
            "type": "pinned",
            "criteria": [
                {
                    "type": "fuzzy",
                    "metadata": "user_query",
                    "values": [
                        "rescue dogs"
                    ]
                }
            ],
            "actions": {
                "docs": [
                    {
                        "_index": "index1",
                        "_id": "id3"
                    },
                    {
                        "_index": "index2",
                        "_id": "id4"
                    }
                ]
            }
        }
    ],
)
const response = await client.queryRules.putRuleset({
  ruleset_id: "my-ruleset",
  rules: [
    {
      rule_id: "my-rule1",
      type: "pinned",
      criteria: [
        {
          type: "contains",
          metadata: "user_query",
          values: ["pugs", "puggles"],
        },
        {
          type: "exact",
          metadata: "user_country",
          values: ["us"],
        },
      ],
      actions: {
        ids: ["id1", "id2"],
      },
    },
    {
      rule_id: "my-rule2",
      type: "pinned",
      criteria: [
        {
          type: "fuzzy",
          metadata: "user_query",
          values: ["rescue dogs"],
        },
      ],
      actions: {
        docs: [
          {
            _index: "index1",
            _id: "id3",
          },
          {
            _index: "index2",
            _id: "id4",
          },
        ],
      },
    },
  ],
});
response = client.query_rules.put_ruleset(
  ruleset_id: "my-ruleset",
  body: {
    "rules": [
      {
        "rule_id": "my-rule1",
        "type": "pinned",
        "criteria": [
          {
            "type": "contains",
            "metadata": "user_query",
            "values": [
              "pugs",
              "puggles"
            ]
          },
          {
            "type": "exact",
            "metadata": "user_country",
            "values": [
              "us"
            ]
          }
        ],
        "actions": {
          "ids": [
            "id1",
            "id2"
          ]
        }
      },
      {
        "rule_id": "my-rule2",
        "type": "pinned",
        "criteria": [
          {
            "type": "fuzzy",
            "metadata": "user_query",
            "values": [
              "rescue dogs"
            ]
          }
        ],
        "actions": {
          "docs": [
            {
              "_index": "index1",
              "_id": "id3"
            },
            {
              "_index": "index2",
              "_id": "id4"
            }
          ]
        }
      }
    ]
  }
)
$resp = $client->queryRules()->putRuleset([
    "ruleset_id" => "my-ruleset",
    "body" => [
        "rules" => array(
            [
                "rule_id" => "my-rule1",
                "type" => "pinned",
                "criteria" => array(
                    [
                        "type" => "contains",
                        "metadata" => "user_query",
                        "values" => array(
                            "pugs",
                            "puggles",
                        ),
                    ],
                    [
                        "type" => "exact",
                        "metadata" => "user_country",
                        "values" => array(
                            "us",
                        ),
                    ],
                ),
                "actions" => [
                    "ids" => array(
                        "id1",
                        "id2",
                    ),
                ],
            ],
            [
                "rule_id" => "my-rule2",
                "type" => "pinned",
                "criteria" => array(
                    [
                        "type" => "fuzzy",
                        "metadata" => "user_query",
                        "values" => array(
                            "rescue dogs",
                        ),
                    ],
                ),
                "actions" => [
                    "docs" => array(
                        [
                            "_index" => "index1",
                            "_id" => "id3",
                        ],
                        [
                            "_index" => "index2",
                            "_id" => "id4",
                        ],
                    ),
                ],
            ],
        ),
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"rules":[{"rule_id":"my-rule1","type":"pinned","criteria":[{"type":"contains","metadata":"user_query","values":["pugs","puggles"]},{"type":"exact","metadata":"user_country","values":["us"]}],"actions":{"ids":["id1","id2"]}},{"rule_id":"my-rule2","type":"pinned","criteria":[{"type":"fuzzy","metadata":"user_query","values":["rescue dogs"]}],"actions":{"docs":[{"_index":"index1","_id":"id3"},{"_index":"index2","_id":"id4"}]}}]}' "$ELASTICSEARCH_URL/_query_rules/my-ruleset"
client.queryRules().putRuleset(p -> p
    .rules(List.of(QueryRule.queryRuleOf(q -> q
            .ruleId("my-rule1")
            .type(QueryRuleType.Pinned)
            .criteria(List.of(QueryRuleCriteria.of(qu -> qu
                    .type(QueryRuleCriteriaType.Contains)
                    .metadata("user_query")
                    .values(List.of(JsonData.fromJson("\"pugs\""),JsonData.fromJson("\"puggles\"")))),QueryRuleCriteria.of(qu -> qu
                    .type(QueryRuleCriteriaType.Exact)
                    .metadata("user_country")
                    .values(JsonData.fromJson("\"us\"")))))
            .actions(a -> a
                .ids(List.of("id1","id2"))
            )),QueryRule.queryRuleOf(q -> q
            .ruleId("my-rule2")
            .type(QueryRuleType.Pinned)
            .criteria(c -> c
                .type(QueryRuleCriteriaType.Fuzzy)
                .metadata("user_query")
                .values(JsonData.fromJson("\"rescue dogs\""))
            )
            .actions(a -> a
                .docs(List.of(PinnedDoc.of(pi -> pi
                        .id("id3")
                        .index("index1")),PinnedDoc.of(pi -> pi
                        .id("id4")
                        .index("index2"))))
            ))))
    .rulesetId("my-ruleset")
);
Request example
Run `PUT _query_rules/my-ruleset` to create a new query ruleset. Two rules are associated with `my-ruleset`. `my-rule1` will pin documents with IDs `id1` and `id2` when `user_query` contains `pugs` or `puggles` and `user_country` exactly matches `us`. `my-rule2` will exclude documents from different specified indices with IDs `id3` and `id4` when the `query_string` fuzzily matches `rescue dogs`.
{
    "rules": [
        {
            "rule_id": "my-rule1",
            "type": "pinned",
            "criteria": [
                {
                    "type": "contains",
                    "metadata": "user_query",
                    "values": [ "pugs", "puggles" ]
                },
                {
                    "type": "exact",
                    "metadata": "user_country",
                    "values": [ "us" ]
                }
            ],
            "actions": {
                "ids": [
                    "id1",
                    "id2"
                ]
            }
        },
        {
            "rule_id": "my-rule2",
            "type": "pinned",
            "criteria": [
                {
                    "type": "fuzzy",
                    "metadata": "user_query",
                    "values": [ "rescue dogs" ]
                }
            ],
            "actions": {
                "docs": [
                    {
                        "_index": "index1",
                        "_id": "id3"
                    },
                    {
                        "_index": "index2",
                        "_id": "id4"
                    }
                ]
            }
        }
    ]
}

Delete a query ruleset Generally available; Added in 8.10.0

DELETE /_query_rules/{ruleset_id}

Remove a query ruleset and its associated data. This is a destructive action that is not recoverable.

Required authorization

  • Cluster privileges: manage_search_query_rules

Path parameters

  • ruleset_id string Required

    The unique identifier of the query ruleset to delete

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 /_query_rules/{ruleset_id}
DELETE _query_rules/my-ruleset/
resp = client.query_rules.delete_ruleset(
    ruleset_id="my-ruleset",
)
const response = await client.queryRules.deleteRuleset({
  ruleset_id: "my-ruleset",
});
response = client.query_rules.delete_ruleset(
  ruleset_id: "my-ruleset"
)
$resp = $client->queryRules()->deleteRuleset([
    "ruleset_id" => "my-ruleset",
]);
curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_query_rules/my-ruleset/"
client.queryRules().deleteRuleset(d -> d
    .rulesetId("my-ruleset")
);

Get all query rulesets Generally available; Added in 8.10.0

GET /_query_rules

Get summarized information about the query rulesets.

Required authorization

  • Cluster privileges: manage_search_query_rules

Query parameters

  • from number

    The offset from the first result to fetch.

  • size number

    The maximum number of results to retrieve.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • count number Required
    • results array[object] Required
      Hide results attributes Show results attributes object
      • ruleset_id string Required
      • rule_total_count number Required

        The number of rules associated with the ruleset.

      • rule_criteria_types_counts object Required

        A map of criteria type (for example, exact) to the number of rules of that type.

        NOTE: The counts in rule_criteria_types_counts may be larger than the value of rule_total_count because a rule may have multiple criteria.

        Hide rule_criteria_types_counts attribute Show rule_criteria_types_counts attribute object
        • * number Additional properties
      • rule_type_counts object Required

        A map of rule type (for example, pinned) to the number of rules of that type.

        Hide rule_type_counts attribute Show rule_type_counts attribute object
        • * number Additional properties
GET _query_rules/?from=0&size=3
resp = client.query_rules.list_rulesets(
    from="0",
    size="3",
)
const response = await client.queryRules.listRulesets({
  from: 0,
  size: 3,
});
response = client.query_rules.list_rulesets(
  from: "0",
  size: "3"
)
$resp = $client->queryRules()->listRulesets([
    "from" => "0",
    "size" => "3",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_query_rules/?from=0&size=3"
client.queryRules().listRulesets(l -> l
    .from(0)
    .size(3)
);
Response examples (200)
A successful response from `GET _query_rules/?from=0&size=3`.
{
    "count": 3,
    "results": [
        {
            "ruleset_id": "ruleset-1",
            "rule_total_count": 1,
            "rule_criteria_types_counts": {
                "exact": 1
            }
        },
        {
            "ruleset_id": "ruleset-2",
            "rule_total_count": 2,
            "rule_criteria_types_counts": {
                "exact": 1,
                "fuzzy": 1
            }
        },
        {
            "ruleset_id": "ruleset-3",
            "rule_total_count": 3,
            "rule_criteria_types_counts": {
                "exact": 1,
                "fuzzy": 2
            }
        }
    ]
}




Rollup













Get the rollup job capabilities Deprecated Technical preview; Added in 6.3.0

GET /_rollup/data/{id}

All methods and paths for this operation:

GET /_rollup/data

GET /_rollup/data/{id}

Get the capabilities of any rollup jobs that have been configured for a specific index or index pattern.

This API is useful because a rollup job is often configured to rollup only a subset of fields from the source index. Furthermore, only certain aggregations can be configured for various fields, leading to a limited subset of functionality depending on that configuration. This API enables you to inspect an index and determine:

  1. Does this index have associated rollup data somewhere in the cluster?
  2. If yes to the first question, what fields were rolled up, what aggregations can be performed, and where does the data live?

Required authorization

  • Cluster privileges: monitor_rollup

Path parameters

  • id string Required

    Index, indices or index-pattern to return rollup capabilities for. _all may be used to fetch rollup capabilities from all jobs.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • * object Additional properties
      Hide * attribute Show * attribute object
      • rollup_jobs array[object] Required

        There can be multiple, independent jobs configured for a single index or index pattern. Each of these jobs may have different configurations, so the API returns a list of all the various configurations available.

        Hide rollup_jobs attributes Show rollup_jobs attributes object
        • fields object Required
          Hide fields attribute Show fields attribute object
          • * array[object] Additional properties
        • index_pattern string Required
        • job_id string Required
        • rollup_index string Required
GET _rollup/data/sensor-*
resp = client.rollup.get_rollup_caps(
    id="sensor-*",
)
const response = await client.rollup.getRollupCaps({
  id: "sensor-*",
});
response = client.rollup.get_rollup_caps(
  id: "sensor-*"
)
$resp = $client->rollup()->getRollupCaps([
    "id" => "sensor-*",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_rollup/data/sensor-*"
client.rollup().getRollupCaps(g -> g
    .id("sensor-*")
);
Response examples (200)
A successful response from `GET _rollup/data/sensor-*` for a rollup job that targets the index pattern `sensor-*`. The response contains the rollup job ID, the index that holds the rolled data, and the index pattern that the job was targeting. It also shows a list of fields that contain data eligible for rollup searches. For example, you can use a `min`, `max`, or `sum` aggregation on the `temperature` field, but only a `date_histogram` on `timestamp`.
{
  "sensor-*" : {
    "rollup_jobs" : [
      {
        "job_id" : "sensor",
        "rollup_index" : "sensor_rollup",
        "index_pattern" : "sensor-*",
        "fields" : {
          "node" : [
            {
              "agg" : "terms"
            }
          ],
          "temperature" : [
            {
              "agg" : "min"
            },
            {
              "agg" : "max"
            },
            {
              "agg" : "sum"
            }
          ],
          "timestamp" : [
            {
              "agg" : "date_histogram",
              "time_zone" : "UTC",
              "fixed_interval" : "1h",
              "delay": "7d"
            }
          ],
          "voltage" : [
            {
              "agg" : "avg"
            }
          ]
        }
      }
    ]
  }
}




Search rolled-up data Deprecated Technical preview; Added in 6.3.0

POST /{index}/_rollup_search

All methods and paths for this operation:

GET /{index}/_rollup_search

POST /{index}/_rollup_search

The rollup search endpoint is needed because, internally, rolled-up documents utilize a different document structure than the original data. It rewrites standard Query DSL into a format that matches the rollup documents then takes the response and rewrites it back to what a client would expect given the original query.

The request body supports a subset of features from the regular search API. The following functionality is not available:

size: Because rollups work on pre-aggregated data, no search hits can be returned and so size must be set to zero or omitted entirely. highlighter, suggestors, post_filter, profile, explain: These are similarly disallowed.

Searching both historical rollup and non-rollup data

The rollup search API has the capability to search across both "live" non-rollup data and the aggregated rollup data. This is done by simply adding the live indices to the URI. For example:

GET sensor-1,sensor_rollup/_rollup_search
{
  "size": 0,
  "aggregations": {
     "max_temperature": {
      "max": {
        "field": "temperature"
      }
    }
  }
}

The rollup search endpoint does two things when the search runs:

  • The original request is sent to the non-rollup index unaltered.
  • A rewritten version of the original request is sent to the rollup index.

When the two responses are received, the endpoint rewrites the rollup response and merges the two together. During the merging process, if there is any overlap in buckets between the two responses, the buckets from the non-rollup index are used.

Path parameters

  • index string | array[string] Required

    A comma-separated list of data streams and indices used to limit the request. This parameter has the following rules:

    • At least one data stream, index, or wildcard expression must be specified. This target can include a rollup or non-rollup index. For data streams, the stream's backing indices can only serve as non-rollup indices. Omitting the parameter or using _all are not permitted.
    • Multiple non-rollup indices may be specified.
    • Only one rollup index may be specified. If more than one are supplied, an exception occurs.
    • Wildcard expressions (*) may be used. If they match more than one rollup index, an exception occurs. However, you can use an expression to match multiple non-rollup indices or data streams.

Query parameters

  • rest_total_hits_as_int boolean

    Indicates whether hits.total should be rendered as an integer or an object in the rest search response

  • typed_keys boolean

    Specify whether aggregation and suggester names should be prefixed by their respective types in the response

application/json

Body Required

  • aggregations object

    Specifies aggregations.

    External documentation
  • query object

    An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

    External documentation
  • size number

    Must be zero if set, as rollups work on pre-aggregated data.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • took number Required
    • timed_out boolean Required
    • terminated_early boolean
    • _shards object Required
      Hide _shards attributes Show _shards attributes object
      • failed number Required
      • successful number Required
      • total number Required
      • failures array[object]
        Hide failures attributes Show failures attributes object
        • index string
        • node string
        • reason object Required

          Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

          Hide reason attributes Show reason attributes object
          • type string Required

            The type of error

          • reason string | null

            A human-readable explanation of the error, in English.

          • stack_trace string

            The server stack trace. Present only if the error_trace=true parameter was sent with the request.

          • caused_by object

            Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

          • root_cause array[object]

            Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

            Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

          • suppressed array[object]

            Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

            Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

        • shard number Required
        • status string
      • skipped number
    • hits object Required
      Hide hits attributes Show hits attributes object
      • total object | number

        Total hit count information, present only if track_total_hits wasn't false in the search request.

        One of:
        Hide attributes Show attributes
        • relation string Required

          Values are eq or gte.

        • value number Required
      • hits array[object] Required
        Hide hits attributes Show hits attributes object
        • _index string Required
        • _id string
        • _score number | string | null

        • _explanation object
          Hide _explanation attributes Show _explanation attributes object
          • description string Required
          • details array[object] Required
          • value number Required
        • fields object
          Hide fields attribute Show fields attribute object
          • * object Additional properties
        • highlight object
          Hide highlight attribute Show highlight attribute object
          • * array[string] Additional properties
        • inner_hits object
          Hide inner_hits attribute Show inner_hits attribute object
          • * object Additional properties
            Hide * attribute Show * attribute object
            • hits object Required
        • matched_queries array[string] | object

          One of:
        • _nested object
          Hide _nested attributes Show _nested attributes object
          • field string Required

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • offset number Required
          • _nested object
        • _ignored array[string]
        • ignored_field_values object
          Hide ignored_field_values attribute Show ignored_field_values attribute object
          • * array[number | string | boolean | null | object] Additional properties

            A field value.

        • _shard string
        • _node string
        • _routing string
        • _source object
        • _rank number
        • _seq_no number
        • _primary_term number
        • _version number
        • sort array[number | string | boolean | null | object]

          A field value.

      • max_score number | string | null

    • aggregations object
GET /sensor_rollup/_rollup_search
{
  "size": 0,
  "aggregations": {
    "max_temperature": {
      "max": {
        "field": "temperature"
      }
    }
  }
}
resp = client.rollup.rollup_search(
    index="sensor_rollup",
    size=0,
    aggregations={
        "max_temperature": {
            "max": {
                "field": "temperature"
            }
        }
    },
)
const response = await client.rollup.rollupSearch({
  index: "sensor_rollup",
  size: 0,
  aggregations: {
    max_temperature: {
      max: {
        field: "temperature",
      },
    },
  },
});
response = client.rollup.rollup_search(
  index: "sensor_rollup",
  body: {
    "size": 0,
    "aggregations": {
      "max_temperature": {
        "max": {
          "field": "temperature"
        }
      }
    }
  }
)
$resp = $client->rollup()->rollupSearch([
    "index" => "sensor_rollup",
    "body" => [
        "size" => 0,
        "aggregations" => [
            "max_temperature" => [
                "max" => [
                    "field" => "temperature",
                ],
            ],
        ],
    ],
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"size":0,"aggregations":{"max_temperature":{"max":{"field":"temperature"}}}}' "$ELASTICSEARCH_URL/sensor_rollup/_rollup_search"
client.rollup().rollupSearch(r -> r
    .aggregations("max_temperature", a -> a
        .max(m -> m
            .field("temperature")
        )
    )
    .index("sensor_rollup")
    .size(0)
);
Request example
Search rolled up data stored in `sensor_rollup` with `GET /sensor_rollup/_rollup_search`
{
  "size": 0,
  "aggregations": {
    "max_temperature": {
      "max": {
        "field": "temperature"
      }
    }
  }
}
Response examples (200)
An abbreviated response from `GET /sensor_rollup/_rollup_search` with a `max` aggregation on a `temperature` field. The response provides some metadata about the request (`took`, `_shards`), the search hits (which is always empty for rollup searches), and the aggregation response.
{
  "took" : 102,
  "timed_out" : false,
  "terminated_early" : false,
  "_shards" : {} ,
  "hits" : {
    "total" : {
        "value": 0,
        "relation": "eq"
    },
    "max_score" : 0.0,
    "hits" : [ ]
  },
  "aggregations" : {
    "max_temperature" : {
      "value" : 202.0
    }
  }
}








Script

Use the script support APIs to get a list of supported script contexts and languages. Use the stored script APIs to manage stored scripts and search templates.

External documentation








Get script contexts Generally available

GET /_script_context

Get a list of supported script contexts and their methods.

Required authorization

  • Cluster privileges: manage

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • contexts array[object] Required
      Hide contexts attributes Show contexts attributes object
      • methods array[object] Required
        Hide methods attributes Show methods attributes object
        • name string Required
        • return_type string Required
        • params array[object] Required
      • name string Required
GET _script_context
resp = client.get_script_context()
const response = await client.getScriptContext();
response = client.get_script_context
$resp = $client->getScriptContext();
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_script_context"
client.getScriptContext();








Run a script Technical preview; Added in 6.3.0

POST /_scripts/painless/_execute

All methods and paths for this operation:

GET /_scripts/painless/_execute

POST /_scripts/painless/_execute

Runs a script and returns a result. Use this API to build and test scripts, such as when defining a script for a runtime field. This API requires very few dependencies and is especially useful if you don't have permissions to write documents on a cluster.

The API uses several contexts, which control how scripts are run, what variables are available at runtime, and what the return type is.

Each context requires a script, but additional parameters depend on the context you're using for that script.

application/json

Body

  • context string

    Values are painless_test, filter, score, boolean_field, date_field, double_field, geo_point_field, ip_field, keyword_field, long_field, or composite_field.

  • context_setup object
    Hide context_setup attributes Show context_setup attributes object
    • document object Required

      Document that's temporarily indexed in-memory and accessible from the script.

    • index string Required
    • query object

      An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

      External documentation
  • script object
    Hide script attributes Show script attributes object
    • source string

      The script source.

    • 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:

      Values are painless, expression, mustache, or java.

    • options object
      Hide options attribute Show options attribute object
      • * string Additional properties

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • result object Required
POST /_scripts/painless/_execute
POST /_scripts/painless/_execute
{
  "script": {
    "source": "params.count / params.total",
    "params": {
      "count": 100.0,
      "total": 1000.0
    }
  }
}
resp = client.scripts_painless_execute(
    script={
        "source": "params.count / params.total",
        "params": {
            "count": 100,
            "total": 1000
        }
    },
)
const response = await client.scriptsPainlessExecute({
  script: {
    source: "params.count / params.total",
    params: {
      count: 100,
      total: 1000,
    },
  },
});
response = client.scripts_painless_execute(
  body: {
    "script": {
      "source": "params.count / params.total",
      "params": {
        "count": 100,
        "total": 1000
      }
    }
  }
)
$resp = $client->scriptsPainlessExecute([
    "body" => [
        "script" => [
            "source" => "params.count / params.total",
            "params" => [
                "count" => 100,
                "total" => 1000,
            ],
        ],
    ],
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"script":{"source":"params.count / params.total","params":{"count":100,"total":1000}}}' "$ELASTICSEARCH_URL/_scripts/painless/_execute"
client.scriptsPainlessExecute(s -> s
    .script(sc -> sc
        .source(so -> so
            .scriptString("params.count / params.total")
        )
        .params(Map.of("total", JsonData.fromJson("1000"),"count", JsonData.fromJson("100")))
    )
);
Run `POST /_scripts/painless/_execute`. The `painless_test` context is the default context. It runs scripts without additional parameters. The only variable that is available is `params`, which can be used to access user defined values. The result of the script is always converted to a string.
{
  "script": {
    "source": "params.count / params.total",
    "params": {
      "count": 100.0,
      "total": 1000.0
    }
  }
}
Run `POST /_scripts/painless/_execute` with a `filter` context. It treats scripts as if they were run inside a script query. For testing purposes, a document must be provided so that it will be temporarily indexed in-memory and is accessible from the script. More precisely, the `_source`, stored fields, and doc values of such a document are available to the script being tested.
{
  "script": {
    "source": "doc['field'].value.length() <= params.max_length",
    "params": {
      "max_length": 4
    }
  },
  "context": "filter",
  "context_setup": {
    "index": "my-index-000001",
    "document": {
      "field": "four"
    }
  }
}
Run `POST /_scripts/painless/_execute` with a `score` context. It treats scripts as if they were run inside a `script_score` function in a `function_score` query.
{
  "script": {
    "source": "doc['rank'].value / params.max_rank",
    "params": {
      "max_rank": 5.0
    }
  },
  "context": "score",
  "context_setup": {
    "index": "my-index-000001",
    "document": {
      "rank": 4
    }
  }
}
Response examples (200)
A successful response from `POST /_scripts/painless/_execute` with a `painless_test` context.
{
  "result": "0.1"
}
A successful response from `POST /_scripts/painless/_execute` with a `filter` context.
{
  "result": true
}
A successful response from `POST /_scripts/painless/_execute` with a `score` context.
{
  "result": 0.8
}























































































































Mount a snapshot Generally available; Added in 7.10.0

POST /_snapshot/{repository}/{snapshot}/_mount

Mount a snapshot as a searchable snapshot index. Do not use this API for snapshots managed by index lifecycle management (ILM). Manually mounting ILM-managed snapshots can interfere with ILM processes.

Required authorization

  • Index privileges: manage
  • Cluster privileges: manage

Path parameters

  • repository string Required

    The name of the repository containing the snapshot of the index to mount.

  • snapshot string Required

    The name of the snapshot of the index to mount.

Query parameters

  • master_timeout string

    The period to wait for the master node. If the master node is not available before the timeout expires, the request fails and returns an error. To indicate that the request should never timeout, set it to -1.

    Values are -1 or 0.

  • wait_for_completion boolean

    If true, the request blocks until the operation is complete.

  • storage string

    The mount option for the searchable snapshot index.

application/json

Body Required

  • index string Required
  • renamed_index string
  • index_settings object

    The settings that should be added to the index when it is mounted.

    Hide index_settings attribute Show index_settings attribute object
    • * object Additional properties
  • ignore_index_settings array[string]

    The names of settings that should be removed from the index when it is mounted.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • snapshot object Required
      Hide snapshot attributes Show snapshot attributes object
      • snapshot string Required
      • indices string | array[string] Required
      • shards object Required
        Hide shards attributes Show shards attributes object
        • failed number Required
        • successful number Required
        • total number Required
        • failures array[object]
          Hide failures attributes Show failures attributes object
          • index string
          • node string
          • reason object Required

            Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

            Hide reason attributes Show reason attributes object
            • type string Required

              The type of error

            • reason
            • stack_trace string

              The server stack trace. Present only if the error_trace=true parameter was sent with the request.

            • caused_by object

              Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

            • root_cause array[object]
            • suppressed array[object]
          • shard number Required
          • status string
        • skipped number
POST /_snapshot/{repository}/{snapshot}/_mount
POST /_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true
{
  "index": "my_docs",
  "renamed_index": "docs",
  "index_settings": {
    "index.number_of_replicas": 0
  },
  "ignore_index_settings": [ "index.refresh_interval" ]
}
resp = client.searchable_snapshots.mount(
    repository="my_repository",
    snapshot="my_snapshot",
    wait_for_completion=True,
    index="my_docs",
    renamed_index="docs",
    index_settings={
        "index.number_of_replicas": 0
    },
    ignore_index_settings=[
        "index.refresh_interval"
    ],
)
const response = await client.searchableSnapshots.mount({
  repository: "my_repository",
  snapshot: "my_snapshot",
  wait_for_completion: "true",
  index: "my_docs",
  renamed_index: "docs",
  index_settings: {
    "index.number_of_replicas": 0,
  },
  ignore_index_settings: ["index.refresh_interval"],
});
response = client.searchable_snapshots.mount(
  repository: "my_repository",
  snapshot: "my_snapshot",
  wait_for_completion: "true",
  body: {
    "index": "my_docs",
    "renamed_index": "docs",
    "index_settings": {
      "index.number_of_replicas": 0
    },
    "ignore_index_settings": [
      "index.refresh_interval"
    ]
  }
)
$resp = $client->searchableSnapshots()->mount([
    "repository" => "my_repository",
    "snapshot" => "my_snapshot",
    "wait_for_completion" => "true",
    "body" => [
        "index" => "my_docs",
        "renamed_index" => "docs",
        "index_settings" => [
            "index.number_of_replicas" => 0,
        ],
        "ignore_index_settings" => array(
            "index.refresh_interval",
        ),
    ],
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"index":"my_docs","renamed_index":"docs","index_settings":{"index.number_of_replicas":0},"ignore_index_settings":["index.refresh_interval"]}' "$ELASTICSEARCH_URL/_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true"
client.searchableSnapshots().mount(m -> m
    .ignoreIndexSettings("index.refresh_interval")
    .index("my_docs")
    .indexSettings("index.number_of_replicas", JsonData.fromJson("0"))
    .renamedIndex("docs")
    .repository("my_repository")
    .snapshot("my_snapshot")
    .waitForCompletion(true)
);
Request example
Run `POST /_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true` to mount the index `my_docs` from an existing snapshot named `my_snapshot` stored in `my_repository` as a new index `docs`.
{
  "index": "my_docs",
  "renamed_index": "docs",
  "index_settings": {
    "index.number_of_replicas": 0
  },
  "ignore_index_settings": [ "index.refresh_interval" ]
}

















































































Delete application privileges Generally available; Added in 6.4.0

DELETE /_security/privilege/{application}/{name}

To use this API, you must have one of the following privileges:

  • The manage_security cluster privilege (or a greater privilege such as all).
  • The "Manage Application Privileges" global privilege for the application being referenced in the request.

Required authorization

  • Cluster privileges: manage_security
External documentation

Path parameters

  • application string Required

    The name of the application. Application privileges are always associated with exactly one application.

  • name string | array[string] Required

    The name of the privilege.

Query parameters

  • refresh string

    If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

    Values are true, false, or wait_for.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • * object Additional properties
      Hide * attribute Show * attribute object
      • * object Additional properties
        Hide * attribute Show * attribute object
        • found boolean Required
DELETE /_security/privilege/{application}/{name}
DELETE /_security/privilege/myapp/read
resp = client.security.delete_privileges(
    application="myapp",
    name="read",
)
const response = await client.security.deletePrivileges({
  application: "myapp",
  name: "read",
});
response = client.security.delete_privileges(
  application: "myapp",
  name: "read"
)
$resp = $client->security()->deletePrivileges([
    "application" => "myapp",
    "name" => "read",
]);
curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_security/privilege/myapp/read"
client.security().deletePrivileges(d -> d
    .application("myapp")
    .name("read")
);
Response examples (200)
A successful response from `DELETE /_security/privilege/myapp/read`. If the privilege is successfully deleted, `found` is set to `true`.
{
  "myapp": {
    "read": {
      "found" : true
    }
  }
}




















Delete role mappings Generally available; Added in 5.5.0

DELETE /_security/role_mapping/{name}

Role mappings define which roles are assigned to each user. The role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The delete role mappings API cannot remove role mappings that are defined in role mapping files.

Required authorization

  • Cluster privileges: manage_security
External documentation

Path parameters

  • name string Required

    The distinct name that identifies the role mapping. The name is used solely as an identifier to facilitate interaction via the API; it does not affect the behavior of the mapping in any way.

Query parameters

  • refresh string

    If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

    Values are true, false, or wait_for.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • found boolean Required

      If the mapping is successfully deleted, found is true. Otherwise, found is false.

DELETE /_security/role_mapping/{name}
DELETE /_security/role_mapping/mapping1
resp = client.security.delete_role_mapping(
    name="mapping1",
)
const response = await client.security.deleteRoleMapping({
  name: "mapping1",
});
response = client.security.delete_role_mapping(
  name: "mapping1"
)
$resp = $client->security()->deleteRoleMapping([
    "name" => "mapping1",
]);
curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_security/role_mapping/mapping1"
client.security().deleteRoleMapping(d -> d
    .name("mapping1")
);
Response examples (200)
A successful response from `DELETE /_security/role_mapping/mapping1`. If the mapping is successfully deleted, `found` is `true`.
{
  "found" : true
}




























Enroll Kibana Generally available; Added in 8.0.0

GET /_security/enroll/kibana

Enable a Kibana instance to configure itself for communication with a secured Elasticsearch cluster.

NOTE: This API is currently intended for internal use only by Kibana. Kibana uses this API internally to configure itself for communications with an Elasticsearch cluster that already has security features enabled.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • token object Required
      Hide token attributes Show token attributes object
      • name string Required

        The name of the bearer token for the elastic/kibana service account.

      • value string Required

        The value of the bearer token for the elastic/kibana service account. Use this value to authenticate the service account with Elasticsearch.

    • http_ca string Required

      The CA certificate used to sign the node certificates that Elasticsearch uses for TLS on the HTTP layer. The certificate is returned as a Base64 encoded string of the ASN.1 DER encoding of the certificate.

GET /_security/enroll/kibana
resp = client.security.enroll_kibana()
const response = await client.security.enrollKibana();
response = client.security.enroll_kibana
$resp = $client->security()->enrollKibana();
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_security/enroll/kibana"
client.security().enrollKibana();
Response examples (200)
A successful response from `GET /_security/enroll/kibana`.
{
  "token" : {
    "name" : "enroll-process-token-1629123923000", 
    "value": "AAEAAWVsYXN0aWM...vZmxlZXQtc2VydmVyL3Rva2VuMTo3TFdaSDZ" 
  },
  "http_ca" : "MIIJlAIBAzVoGCSqGSIb3...vsDfsA3UZBAjEPfhubpQysAICAA=", 
}
































Get user privileges Generally available; Added in 6.5.0

GET /_security/user/_privileges

Get the security privileges for the logged in user. All users can use this API, but only to determine their own privileges. To check the privileges of other users, you must use the run as feature. To check whether a user has a specific list of privileges, use the has privileges API.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • applications array[object] Required
      Hide applications attributes Show applications attributes object
      • application string Required

        The name of the application to which this entry applies.

      • privileges array[string] Required

        A list of strings, where each element is the name of an application privilege or action.

      • resources array[string] Required

        A list resources to which the privileges are applied.

    • cluster array[string] Required
    • remote_cluster array[object]

      The subset of cluster level privileges that can be defined for remote clusters.

      Hide remote_cluster attributes Show remote_cluster attributes object
      • clusters string | array[string] Required
      • privileges array[string] Required

        The cluster level privileges that owners of the role have on the remote cluster.

        Values are monitor_enrich or monitor_stats.

    • global array[object] Required
      Hide global attribute Show global attribute object
      • application object Required
        Hide application attribute Show application attribute object
        • manage object Required
          Hide manage attribute Show manage attribute object
          • applications array[string] Required
    • indices array[object] Required
      Hide indices attributes Show indices attributes object
      • field_security array[object]

        The document fields that the owners of the role have read access to.

        External documentation
        Hide field_security attributes Show field_security attributes object
        • except string | array[string]
        • grant string | array[string]
      • names array[string] Required

        A list of indices (or index name patterns) to which the permissions in this entry apply.

      • privileges array[string] Required

        The index level privileges that owners of the role have on the specified indices.

      • query array[string | object]

        Search queries that define the documents the user has access to. A document within the specified indices must match these queries for it to be accessible by the owners of the role.

        While creating or updating a role you can provide either a JSON structure or a string to the API. However, the response provided by Elasticsearch will only be string with a json-as-text content.

        Since this is embedded in IndicesPrivileges, the same structure is used for clarity in both contexts.

        While creating or updating a role you can provide either a JSON structure or a string to the API. However, the response provided by Elasticsearch will only be string with a json-as-text content.

        Since this is embedded in IndicesPrivileges, the same structure is used for clarity in both contexts.

        One of:
      • allow_restricted_indices boolean Required

        Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.

    • remote_indices array[object]
      Hide remote_indices attributes Show remote_indices attributes object
      • field_security array[object]

        The document fields that the owners of the role have read access to.

        External documentation
        Hide field_security attributes Show field_security attributes object
        • except string | array[string]
        • grant string | array[string]
      • names string | array[string] Required

        A list of indices (or index name patterns) to which the permissions in this entry apply.

      • privileges array[string] Required

        The index level privileges that owners of the role have on the specified indices.

      • query array[string | object]

        Search queries that define the documents the user has access to. A document within the specified indices must match these queries for it to be accessible by the owners of the role.

        While creating or updating a role you can provide either a JSON structure or a string to the API. However, the response provided by Elasticsearch will only be string with a json-as-text content.

        Since this is embedded in IndicesPrivileges, the same structure is used for clarity in both contexts.

        While creating or updating a role you can provide either a JSON structure or a string to the API. However, the response provided by Elasticsearch will only be string with a json-as-text content.

        Since this is embedded in IndicesPrivileges, the same structure is used for clarity in both contexts.

        One of:
      • allow_restricted_indices boolean Required

        Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.

      • clusters array[string] Required
    • run_as array[string] Required
GET /_security/user/_privileges
resp = client.security.get_user_privileges()
const response = await client.security.getUserPrivileges();
response = client.security.get_user_privileges
$resp = $client->security()->getUserPrivileges();
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_security/user/_privileges"
client.security().getUserPrivileges(g -> g);
Response examples (200)
A successful response from `GET /_security/user/_privileges`.
{
  "cluster" : [
    "all"
  ],
  "global" : [ ],
  "indices" : [
    {
      "names" : [
        "*"
      ],
      "privileges" : [
        "all"
      ],
      "allow_restricted_indices" : true
    }
  ],
  "applications" : [
    {
      "application" : "*",
      "privileges" : [
        "*"
      ],
      "resources" : [
        "*"
      ]
    }
  ],
  "run_as" : [
    "*"
  ]
}




Grant an API key Generally available; Added in 7.9.0

POST /_security/api_key/grant

Create an API key on behalf of another user. This API is similar to the create API keys API, however it creates the API key for a user that is different than the user that runs the API. The caller must have authentication credentials for the user on whose behalf the API key will be created. It is not possible to use this API to create an API key without that user's credentials. The supported user authentication credential types are:

  • username and password
  • Elasticsearch access tokens
  • JWTs

The user, for whom the authentication credentials is provided, can optionally "run as" (impersonate) another user. In this case, the API key will be created on behalf of the impersonated user.

This API is intended be used by applications that need to create and manage API keys for end users, but cannot guarantee that those users have permission to create API keys on their own behalf. The API keys are created by the Elasticsearch API key service, which is automatically enabled.

A successful grant API key API call returns a JSON structure that contains the API key, its unique id, and its name. If applicable, it also returns expiration information for the API key in milliseconds.

By default, API keys never expire. You can specify expiration information when you create the API keys.

Required authorization

  • Cluster privileges: grant_api_key

Query parameters

  • refresh string

    If 'true', Elasticsearch refreshes the affected shards to make this operation visible to search. If 'wait_for', it waits for a refresh to make this operation visible to search. If 'false', nothing is done with refreshes.

    Values are true, false, or wait_for.

application/json

Body Required

  • api_key object Required
    Hide api_key attributes Show api_key attributes object
    • name string Required
    • expiration string

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

    • role_descriptors object | array[object]

      The role descriptors for this API key. When it is not specified or is an empty array, the API key has a point in time snapshot of permissions of the specified user or access token. If you supply role descriptors, the resultant permissions are an intersection of API keys permissions and the permissions of the user or access token.

      One of:
      Hide attribute Show attribute
      • * object Additional properties
        Hide * attributes Show * attributes object
        • cluster array[string]

          A list of cluster privileges. These privileges define the cluster level actions that API keys are able to execute.

        • indices array[object]

          A list of indices permissions entries.

          Hide indices attributes Show indices attributes object
          • field_security object
          • names array[string] Required

            A list of indices (or index name patterns) to which the permissions in this entry apply.

          • privileges array[string] Required

            The index level privileges that owners of the role have on the specified indices.

          • query
          • allow_restricted_indices boolean Generally available

            Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.

            Default value is false.

        • remote_indices array[object] Generally available; Added in 8.14.0

          A list of indices permissions for remote clusters.

          The subset of index level privileges that can be defined for remote clusters.

          Hide remote_indices attributes Show remote_indices attributes object
          • clusters string | array[string] Required
          • field_security object
          • names array[string] Required

            A list of indices (or index name patterns) to which the permissions in this entry apply.

          • privileges array[string] Required

            The index level privileges that owners of the role have on the specified indices.

          • query
          • allow_restricted_indices boolean Generally available

            Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.

            Default value is false.

        • remote_cluster array[object] Generally available; Added in 8.15.0

          A list of cluster permissions for remote clusters. NOTE: This is limited a subset of the cluster permissions.

          The subset of cluster level privileges that can be defined for remote clusters.

          Hide remote_cluster attributes Show remote_cluster attributes object
          • clusters string | array[string] Required
          • privileges array[string] Required

            The cluster level privileges that owners of the role have on the remote cluster.

            Values are monitor_enrich or monitor_stats.

        • global array[object] | object

          An object defining global privileges. A global privilege is a form of cluster privilege that is request-aware. Support for global privileges is currently limited to the management of application privileges.

          One of:
        • applications array[object]

          A list of application privilege entries

          Hide applications attributes Show applications attributes object
          • application string Required

            The name of the application to which this entry applies.

          • privileges array[string] Required

            A list of strings, where each element is the name of an application privilege or action.

          • resources array[string] Required

            A list resources to which the privileges are applied.

        • metadata object
          Hide metadata attribute Show metadata attribute object
          • * object Additional properties
        • run_as array[string]

          A list of users that the API keys can impersonate. NOTE: In Elastic Cloud Serverless, the run-as feature is disabled. For API compatibility, you can still specify an empty run_as field, but a non-empty list will be rejected.

        • description string

          Optional description of the role descriptor

        • restriction object
          Hide restriction attribute Show restriction attribute object
          • workflows array[string] Required

            A list of workflows to which the API key is restricted. NOTE: In order to use a role restriction, an API key must be created with a single role descriptor.

        • transient_metadata object
          Hide transient_metadata attribute Show transient_metadata attribute object
          • * object Additional properties
    • metadata object
      Hide metadata attribute Show metadata attribute object
      • * object Additional properties
  • grant_type string Required

    Values are access_token or password.

  • access_token string

    The user's access token. If you specify the access_token grant type, this parameter is required. It is not valid with other grant types.

  • username string
  • password string
  • run_as string

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • api_key string Required
    • id string Required
    • name string Required
    • expiration number

      Time unit for milliseconds

    • encoded string Required
POST /_security/api_key/grant
{
  "grant_type": "password",
  "username" : "test_admin",
  "password" : "x-pack-test-password",
  "api_key" : {
    "name": "my-api-key",
    "expiration": "1d",
    "role_descriptors": {
      "role-a": {
        "cluster": ["all"],
        "indices": [
          {
          "names": ["index-a*"],
          "privileges": ["read"]
          }
        ]
      },
      "role-b": {
        "cluster": ["all"],
        "indices": [
          {
          "names": ["index-b*"],
          "privileges": ["all"]
          }
        ]
      }
    },
    "metadata": {
      "application": "my-application",
      "environment": {
        "level": 1,
        "trusted": true,
        "tags": ["dev", "staging"]
      }
    }
  }
}
resp = client.security.grant_api_key(
    grant_type="password",
    username="test_admin",
    password="x-pack-test-password",
    api_key={
        "name": "my-api-key",
        "expiration": "1d",
        "role_descriptors": {
            "role-a": {
                "cluster": [
                    "all"
                ],
                "indices": [
                    {
                        "names": [
                            "index-a*"
                        ],
                        "privileges": [
                            "read"
                        ]
                    }
                ]
            },
            "role-b": {
                "cluster": [
                    "all"
                ],
                "indices": [
                    {
                        "names": [
                            "index-b*"
                        ],
                        "privileges": [
                            "all"
                        ]
                    }
                ]
            }
        },
        "metadata": {
            "application": "my-application",
            "environment": {
                "level": 1,
                "trusted": True,
                "tags": [
                    "dev",
                    "staging"
                ]
            }
        }
    },
)
const response = await client.security.grantApiKey({
  grant_type: "password",
  username: "test_admin",
  password: "x-pack-test-password",
  api_key: {
    name: "my-api-key",
    expiration: "1d",
    role_descriptors: {
      "role-a": {
        cluster: ["all"],
        indices: [
          {
            names: ["index-a*"],
            privileges: ["read"],
          },
        ],
      },
      "role-b": {
        cluster: ["all"],
        indices: [
          {
            names: ["index-b*"],
            privileges: ["all"],
          },
        ],
      },
    },
    metadata: {
      application: "my-application",
      environment: {
        level: 1,
        trusted: true,
        tags: ["dev", "staging"],
      },
    },
  },
});
response = client.security.grant_api_key(
  body: {
    "grant_type": "password",
    "username": "test_admin",
    "password": "x-pack-test-password",
    "api_key": {
      "name": "my-api-key",
      "expiration": "1d",
      "role_descriptors": {
        "role-a": {
          "cluster": [
            "all"
          ],
          "indices": [
            {
              "names": [
                "index-a*"
              ],
              "privileges": [
                "read"
              ]
            }
          ]
        },
        "role-b": {
          "cluster": [
            "all"
          ],
          "indices": [
            {
              "names": [
                "index-b*"
              ],
              "privileges": [
                "all"
              ]
            }
          ]
        }
      },
      "metadata": {
        "application": "my-application",
        "environment": {
          "level": 1,
          "trusted": true,
          "tags": [
            "dev",
            "staging"
          ]
        }
      }
    }
  }
)
$resp = $client->security()->grantApiKey([
    "body" => [
        "grant_type" => "password",
        "username" => "test_admin",
        "password" => "x-pack-test-password",
        "api_key" => [
            "name" => "my-api-key",
            "expiration" => "1d",
            "role_descriptors" => [
                "role-a" => [
                    "cluster" => array(
                        "all",
                    ),
                    "indices" => array(
                        [
                            "names" => array(
                                "index-a*",
                            ),
                            "privileges" => array(
                                "read",
                            ),
                        ],
                    ),
                ],
                "role-b" => [
                    "cluster" => array(
                        "all",
                    ),
                    "indices" => array(
                        [
                            "names" => array(
                                "index-b*",
                            ),
                            "privileges" => array(
                                "all",
                            ),
                        ],
                    ),
                ],
            ],
            "metadata" => [
                "application" => "my-application",
                "environment" => [
                    "level" => 1,
                    "trusted" => true,
                    "tags" => array(
                        "dev",
                        "staging",
                    ),
                ],
            ],
        ],
    ],
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"grant_type":"password","username":"test_admin","password":"x-pack-test-password","api_key":{"name":"my-api-key","expiration":"1d","role_descriptors":{"role-a":{"cluster":["all"],"indices":[{"names":["index-a*"],"privileges":["read"]}]},"role-b":{"cluster":["all"],"indices":[{"names":["index-b*"],"privileges":["all"]}]}},"metadata":{"application":"my-application","environment":{"level":1,"trusted":true,"tags":["dev","staging"]}}}}' "$ELASTICSEARCH_URL/_security/api_key/grant"
client.security().grantApiKey(g -> g
    .apiKey(a -> a
        .name("my-api-key")
        .expiration(e -> e
            .time("1d")
        )
        .roleDescriptors(Map.of("role-b", RoleDescriptor.of(r -> r
                .cluster("all")
                .indices(i -> i
                    .names("index-b*")
                    .privileges("all")
                )),"role-a", RoleDescriptor.of(r -> r
                .cluster("all")
                .indices(i -> i
                    .names("index-a*")
                    .privileges("read")
                ))))
        .metadata(Map.of("environment", JsonData.fromJson("{\"level\":1,\"trusted\":true,\"tags\":[\"dev\",\"staging\"]}"),"application", JsonData.fromJson("\"my-application\"")))
    )
    .grantType(ApiKeyGrantType.Password)
    .password("x-pack-test-password")
    .username("test_admin")
);
Request examples
Run `POST /_security/api_key/grant` to create an API key on behalf of the `test_admin` user.
{
  "grant_type": "password",
  "username" : "test_admin",
  "password" : "x-pack-test-password",
  "api_key" : {
    "name": "my-api-key",
    "expiration": "1d",
    "role_descriptors": {
      "role-a": {
        "cluster": ["all"],
        "indices": [
          {
          "names": ["index-a*"],
          "privileges": ["read"]
          }
        ]
      },
      "role-b": {
        "cluster": ["all"],
        "indices": [
          {
          "names": ["index-b*"],
          "privileges": ["all"]
          }
        ]
      }
    },
    "metadata": {
      "application": "my-application",
      "environment": {
        "level": 1,
        "trusted": true,
        "tags": ["dev", "staging"]
      }
    }
  }
}
Run `POST /_security/api_key/grant`. The user (`test_admin`) whose credentials are provided can "run as" another user (`test_user`). The API key will be granted to the impersonated user (`test_user`).
{
  "grant_type": "password",
  "username" : "test_admin",  
  "password" : "x-pack-test-password",  
  "run_as": "test_user",  
  "api_key" : {
    "name": "another-api-key"
  }
}
















Prepare OpenID connect authentication Generally available

POST /_security/oidc/prepare

Create an oAuth 2.0 authentication request as a URL string based on the configuration of the OpenID Connect authentication realm in Elasticsearch.

The response of this API is a URL pointing to the Authorization Endpoint of the configured OpenID Connect Provider, which can be used to redirect the browser of the user in order to continue the authentication process.

Elasticsearch exposes all the necessary OpenID Connect related functionality with the OpenID Connect APIs. These APIs are used internally by Kibana in order to provide OpenID Connect based authentication, but can also be used by other, custom web applications or other clients.

application/json

Body Required

  • iss string

    In the case of a third party initiated single sign on, this is the issuer identifier for the OP that the RP is to send the authentication request to. It cannot be specified when realm is specified. One of realm or iss is required.

  • login_hint string

    In the case of a third party initiated single sign on, it is a string value that is included in the authentication request as the login_hint parameter. This parameter is not valid when realm is specified.

  • nonce string

    The value used to associate a client session with an ID token and to mitigate replay attacks. If the caller of the API does not provide a value, Elasticsearch will generate one with sufficient entropy and return it in the response.

  • realm string

    The name of the OpenID Connect realm in Elasticsearch the configuration of which should be used in order to generate the authentication request. It cannot be specified when iss is specified. One of realm or iss is required.

  • state string

    The value used to maintain state between the authentication request and the response, typically used as a Cross-Site Request Forgery mitigation. If the caller of the API does not provide a value, Elasticsearch will generate one with sufficient entropy and return it in the response.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • nonce string Required
    • realm string Required
    • redirect string Required

      A URI that points to the authorization endpoint of the OpenID Connect Provider with all the parameters of the authentication request as HTTP GET parameters.

    • state string Required
POST /_security/oidc/prepare
{
  "realm" : "oidc1"
}
resp = client.security.oidc_prepare_authentication(
    realm="oidc1",
)
const response = await client.security.oidcPrepareAuthentication({
  realm: "oidc1",
});
response = client.security.oidc_prepare_authentication(
  body: {
    "realm": "oidc1"
  }
)
$resp = $client->security()->oidcPrepareAuthentication([
    "body" => [
        "realm" => "oidc1",
    ],
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"realm":"oidc1"}' "$ELASTICSEARCH_URL/_security/oidc/prepare"
client.security().oidcPrepareAuthentication(o -> o
    .realm("oidc1")
);
Run `POST /_security/oidc/prepare` to generate an authentication request for the OpenID Connect Realm `oidc1`.
{
  "realm" : "oidc1"
}
Run `POST /_security/oidc/prepare` to generate an authentication request for the OpenID Connect Realm `oidc1`, where the values for the `state` and the `nonce` have been generated by the client.
{
  "realm" : "oidc1",
  "state" : "lGYK0EcSLjqH6pkT5EVZjC6eIW5YCGgywj2sxROO",
  "nonce" : "zOBXLJGUooRrbLbQk5YCcyC8AXw3iloynvluYhZ5"
}
Run `POST /_security/oidc/prepare` to generate an authentication request for a third party initiated single sign on. Specify the issuer that should be used for matching the appropriate OpenID Connect Authentication realm.
{
  "iss" : "http://127.0.0.1:8080",
  "login_hint": "this_is_an_opaque_string"
}
Response examples (200)
A successful response from `POST /_security/oidc/prepare`. It contains the URI pointing to the Authorization Endpoint of the OpenID Connect Provider with all the parameters of the Authentication Request as HTTP GET parameters.
{
  "redirect" : "http://127.0.0.1:8080/c2id-login?scope=openid&response_type=id_token&redirect_uri=https%3A%2F%2Ffanyv88.com%3A443%2Fhttps%2Fmy.fantastic.rp%2Fcb&state=4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I&nonce=WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM&client_id=elasticsearch-rp",
  "state" : "4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
  "nonce" : "WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM",
  "realm" : "oidc1"
}
























Invalidate SAML Generally available; Added in 7.5.0

POST /_security/saml/invalidate

Submit a SAML LogoutRequest message to Elasticsearch for consumption.

NOTE: This API is intended for use by custom web applications other than Kibana. If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.

The logout request comes from the SAML IdP during an IdP initiated Single Logout. The custom web application can use this API to have Elasticsearch process the LogoutRequest. After successful validation of the request, Elasticsearch invalidates the access token and refresh token that corresponds to that specific SAML principal and provides a URL that contains a SAML LogoutResponse message. Thus the user can be redirected back to their IdP.

External documentation
application/json

Body Required

  • acs string

    The Assertion Consumer Service URL that matches the one of the SAML realm in Elasticsearch that should be used. You must specify either this parameter or the realm parameter.

  • query_string string Required

    The query part of the URL that the user was redirected to by the SAML IdP to initiate the Single Logout. This query should include a single parameter named SAMLRequest that contains a SAML logout request that is deflated and Base64 encoded. If the SAML IdP has signed the logout request, the URL should include two extra parameters named SigAlg and Signature that contain the algorithm used for the signature and the signature value itself. In order for Elasticsearch to be able to verify the IdP's signature, the value of the query_string field must be an exact match to the string provided by the browser. The client application must not attempt to parse or process the string in any way.

  • realm string

    The name of the SAML realm in Elasticsearch the configuration. You must specify either this parameter or the acs parameter.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • invalidated number Required

      The number of tokens that were invalidated as part of this logout.

    • realm string Required

      The realm name of the SAML realm in Elasticsearch that authenticated the user.

    • redirect string Required

      A SAML logout response as a parameter so that the user can be redirected back to the SAML IdP.

POST /_security/saml/invalidate
{
  "query_string" : "SAMLRequest=nZFda4MwFIb%2FiuS%2BmviRpqFaClKQdbvo2g12M2KMraCJ9cRR9utnW4Wyi13sMie873MeznJ1aWrnS3VQGR0j4mLkKC1NUeljjA77zYyhVbIE0dR%2By7fmaHq7U%2BdegXWGpAZ%2B%2F4pR32luBFTAtWgUcCv56%2Fp5y30X87Yz1khTIycdgpUW9kY7WdsC9zxoXTvMvWuVV98YyMnSGH2SYE5pwALBIr9QKiwDGpW0oGVUznGeMyJZKFkQ4jBf5HnhUymjIhzCAL3KNFihbYx8TBYzzGaY7EnIyZwHzCWMfiDnbRIftkSjJr%2BFu0e9v%2B0EgOquRiiZjKpiVFp6j50T4WXoyNJ%2FEWC9fdqc1t%2F1%2B2F3aUpjzhPiXpqMz1%2FHSn4A&SigAlg=https%3A%2F%2Ffanyv88.com%3A443%2Fhttp%2Fwww.w3.org%2F2001%2F04%2Fxmldsig-more%23rsa-sha256&Signature=MsAYz2NFdovMG2mXf6TSpu5vlQQyEJAg%2B4KCwBqJTmrb3yGXKUtIgvjqf88eCAK32v3eN8vupjPC8LglYmke1ZnjK0%2FKxzkvSjTVA7mMQe2AQdKbkyC038zzRq%2FYHcjFDE%2Bz0qISwSHZY2NyLePmwU7SexEXnIz37jKC6NMEhus%3D",
  "realm" : "saml1"
}
resp = client.security.saml_invalidate(
    query_string="SAMLRequest=nZFda4MwFIb%2FiuS%2BmviRpqFaClKQdbvo2g12M2KMraCJ9cRR9utnW4Wyi13sMie873MeznJ1aWrnS3VQGR0j4mLkKC1NUeljjA77zYyhVbIE0dR%2By7fmaHq7U%2BdegXWGpAZ%2B%2F4pR32luBFTAtWgUcCv56%2Fp5y30X87Yz1khTIycdgpUW9kY7WdsC9zxoXTvMvWuVV98YyMnSGH2SYE5pwALBIr9QKiwDGpW0oGVUznGeMyJZKFkQ4jBf5HnhUymjIhzCAL3KNFihbYx8TBYzzGaY7EnIyZwHzCWMfiDnbRIftkSjJr%2BFu0e9v%2B0EgOquRiiZjKpiVFp6j50T4WXoyNJ%2FEWC9fdqc1t%2F1%2B2F3aUpjzhPiXpqMz1%2FHSn4A&SigAlg=https%3A%2F%2Ffanyv88.com%3A443%2Fhttp%2Fwww.w3.org%2F2001%2F04%2Fxmldsig-more%23rsa-sha256&Signature=MsAYz2NFdovMG2mXf6TSpu5vlQQyEJAg%2B4KCwBqJTmrb3yGXKUtIgvjqf88eCAK32v3eN8vupjPC8LglYmke1ZnjK0%2FKxzkvSjTVA7mMQe2AQdKbkyC038zzRq%2FYHcjFDE%2Bz0qISwSHZY2NyLePmwU7SexEXnIz37jKC6NMEhus%3D",
    realm="saml1",
)
const response = await client.security.samlInvalidate({
  query_string:
    "SAMLRequest=nZFda4MwFIb%2FiuS%2BmviRpqFaClKQdbvo2g12M2KMraCJ9cRR9utnW4Wyi13sMie873MeznJ1aWrnS3VQGR0j4mLkKC1NUeljjA77zYyhVbIE0dR%2By7fmaHq7U%2BdegXWGpAZ%2B%2F4pR32luBFTAtWgUcCv56%2Fp5y30X87Yz1khTIycdgpUW9kY7WdsC9zxoXTvMvWuVV98YyMnSGH2SYE5pwALBIr9QKiwDGpW0oGVUznGeMyJZKFkQ4jBf5HnhUymjIhzCAL3KNFihbYx8TBYzzGaY7EnIyZwHzCWMfiDnbRIftkSjJr%2BFu0e9v%2B0EgOquRiiZjKpiVFp6j50T4WXoyNJ%2FEWC9fdqc1t%2F1%2B2F3aUpjzhPiXpqMz1%2FHSn4A&SigAlg=https%3A%2F%2Ffanyv88.com%3A443%2Fhttp%2Fwww.w3.org%2F2001%2F04%2Fxmldsig-more%23rsa-sha256&Signature=MsAYz2NFdovMG2mXf6TSpu5vlQQyEJAg%2B4KCwBqJTmrb3yGXKUtIgvjqf88eCAK32v3eN8vupjPC8LglYmke1ZnjK0%2FKxzkvSjTVA7mMQe2AQdKbkyC038zzRq%2FYHcjFDE%2Bz0qISwSHZY2NyLePmwU7SexEXnIz37jKC6NMEhus%3D",
  realm: "saml1",
});
response = client.security.saml_invalidate(
  body: {
    "query_string": "SAMLRequest=nZFda4MwFIb%2FiuS%2BmviRpqFaClKQdbvo2g12M2KMraCJ9cRR9utnW4Wyi13sMie873MeznJ1aWrnS3VQGR0j4mLkKC1NUeljjA77zYyhVbIE0dR%2By7fmaHq7U%2BdegXWGpAZ%2B%2F4pR32luBFTAtWgUcCv56%2Fp5y30X87Yz1khTIycdgpUW9kY7WdsC9zxoXTvMvWuVV98YyMnSGH2SYE5pwALBIr9QKiwDGpW0oGVUznGeMyJZKFkQ4jBf5HnhUymjIhzCAL3KNFihbYx8TBYzzGaY7EnIyZwHzCWMfiDnbRIftkSjJr%2BFu0e9v%2B0EgOquRiiZjKpiVFp6j50T4WXoyNJ%2FEWC9fdqc1t%2F1%2B2F3aUpjzhPiXpqMz1%2FHSn4A&SigAlg=https%3A%2F%2Ffanyv88.com%3A443%2Fhttp%2Fwww.w3.org%2F2001%2F04%2Fxmldsig-more%23rsa-sha256&Signature=MsAYz2NFdovMG2mXf6TSpu5vlQQyEJAg%2B4KCwBqJTmrb3yGXKUtIgvjqf88eCAK32v3eN8vupjPC8LglYmke1ZnjK0%2FKxzkvSjTVA7mMQe2AQdKbkyC038zzRq%2FYHcjFDE%2Bz0qISwSHZY2NyLePmwU7SexEXnIz37jKC6NMEhus%3D",
    "realm": "saml1"
  }
)
$resp = $client->security()->samlInvalidate([
    "body" => [
        "query_string" => "SAMLRequest=nZFda4MwFIb%2FiuS%2BmviRpqFaClKQdbvo2g12M2KMraCJ9cRR9utnW4Wyi13sMie873MeznJ1aWrnS3VQGR0j4mLkKC1NUeljjA77zYyhVbIE0dR%2By7fmaHq7U%2BdegXWGpAZ%2B%2F4pR32luBFTAtWgUcCv56%2Fp5y30X87Yz1khTIycdgpUW9kY7WdsC9zxoXTvMvWuVV98YyMnSGH2SYE5pwALBIr9QKiwDGpW0oGVUznGeMyJZKFkQ4jBf5HnhUymjIhzCAL3KNFihbYx8TBYzzGaY7EnIyZwHzCWMfiDnbRIftkSjJr%2BFu0e9v%2B0EgOquRiiZjKpiVFp6j50T4WXoyNJ%2FEWC9fdqc1t%2F1%2B2F3aUpjzhPiXpqMz1%2FHSn4A&SigAlg=https%3A%2F%2Ffanyv88.com%3A443%2Fhttp%2Fwww.w3.org%2F2001%2F04%2Fxmldsig-more%23rsa-sha256&Signature=MsAYz2NFdovMG2mXf6TSpu5vlQQyEJAg%2B4KCwBqJTmrb3yGXKUtIgvjqf88eCAK32v3eN8vupjPC8LglYmke1ZnjK0%2FKxzkvSjTVA7mMQe2AQdKbkyC038zzRq%2FYHcjFDE%2Bz0qISwSHZY2NyLePmwU7SexEXnIz37jKC6NMEhus%3D",
        "realm" => "saml1",
    ],
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"query_string":"SAMLRequest=nZFda4MwFIb%2FiuS%2BmviRpqFaClKQdbvo2g12M2KMraCJ9cRR9utnW4Wyi13sMie873MeznJ1aWrnS3VQGR0j4mLkKC1NUeljjA77zYyhVbIE0dR%2By7fmaHq7U%2BdegXWGpAZ%2B%2F4pR32luBFTAtWgUcCv56%2Fp5y30X87Yz1khTIycdgpUW9kY7WdsC9zxoXTvMvWuVV98YyMnSGH2SYE5pwALBIr9QKiwDGpW0oGVUznGeMyJZKFkQ4jBf5HnhUymjIhzCAL3KNFihbYx8TBYzzGaY7EnIyZwHzCWMfiDnbRIftkSjJr%2BFu0e9v%2B0EgOquRiiZjKpiVFp6j50T4WXoyNJ%2FEWC9fdqc1t%2F1%2B2F3aUpjzhPiXpqMz1%2FHSn4A&SigAlg=https%3A%2F%2Ffanyv88.com%3A443%2Fhttp%2Fwww.w3.org%2F2001%2F04%2Fxmldsig-more%23rsa-sha256&Signature=MsAYz2NFdovMG2mXf6TSpu5vlQQyEJAg%2B4KCwBqJTmrb3yGXKUtIgvjqf88eCAK32v3eN8vupjPC8LglYmke1ZnjK0%2FKxzkvSjTVA7mMQe2AQdKbkyC038zzRq%2FYHcjFDE%2Bz0qISwSHZY2NyLePmwU7SexEXnIz37jKC6NMEhus%3D","realm":"saml1"}' "$ELASTICSEARCH_URL/_security/saml/invalidate"
client.security().samlInvalidate(s -> s
    .queryString("SAMLRequest=nZFda4MwFIb%2FiuS%2BmviRpqFaClKQdbvo2g12M2KMraCJ9cRR9utnW4Wyi13sMie873MeznJ1aWrnS3VQGR0j4mLkKC1NUeljjA77zYyhVbIE0dR%2By7fmaHq7U%2BdegXWGpAZ%2B%2F4pR32luBFTAtWgUcCv56%2Fp5y30X87Yz1khTIycdgpUW9kY7WdsC9zxoXTvMvWuVV98YyMnSGH2SYE5pwALBIr9QKiwDGpW0oGVUznGeMyJZKFkQ4jBf5HnhUymjIhzCAL3KNFihbYx8TBYzzGaY7EnIyZwHzCWMfiDnbRIftkSjJr%2BFu0e9v%2B0EgOquRiiZjKpiVFp6j50T4WXoyNJ%2FEWC9fdqc1t%2F1%2B2F3aUpjzhPiXpqMz1%2FHSn4A&SigAlg=https%3A%2F%2Ffanyv88.com%3A443%2Fhttp%2Fwww.w3.org%2F2001%2F04%2Fxmldsig-more%23rsa-sha256&Signature=MsAYz2NFdovMG2mXf6TSpu5vlQQyEJAg%2B4KCwBqJTmrb3yGXKUtIgvjqf88eCAK32v3eN8vupjPC8LglYmke1ZnjK0%2FKxzkvSjTVA7mMQe2AQdKbkyC038zzRq%2FYHcjFDE%2Bz0qISwSHZY2NyLePmwU7SexEXnIz37jKC6NMEhus%3D")
    .realm("saml1")
);
Request example
Run `POST /_security/saml/invalidate` to invalidate all the tokens for realm `saml1` pertaining to the user that is identified in the SAML Logout Request.
{
  "query_string" : "SAMLRequest=nZFda4MwFIb%2FiuS%2BmviRpqFaClKQdbvo2g12M2KMraCJ9cRR9utnW4Wyi13sMie873MeznJ1aWrnS3VQGR0j4mLkKC1NUeljjA77zYyhVbIE0dR%2By7fmaHq7U%2BdegXWGpAZ%2B%2F4pR32luBFTAtWgUcCv56%2Fp5y30X87Yz1khTIycdgpUW9kY7WdsC9zxoXTvMvWuVV98YyMnSGH2SYE5pwALBIr9QKiwDGpW0oGVUznGeMyJZKFkQ4jBf5HnhUymjIhzCAL3KNFihbYx8TBYzzGaY7EnIyZwHzCWMfiDnbRIftkSjJr%2BFu0e9v%2B0EgOquRiiZjKpiVFp6j50T4WXoyNJ%2FEWC9fdqc1t%2F1%2B2F3aUpjzhPiXpqMz1%2FHSn4A&SigAlg=https%3A%2F%2Ffanyv88.com%3A443%2Fhttp%2Fwww.w3.org%2F2001%2F04%2Fxmldsig-more%23rsa-sha256&Signature=MsAYz2NFdovMG2mXf6TSpu5vlQQyEJAg%2B4KCwBqJTmrb3yGXKUtIgvjqf88eCAK32v3eN8vupjPC8LglYmke1ZnjK0%2FKxzkvSjTVA7mMQe2AQdKbkyC038zzRq%2FYHcjFDE%2Bz0qISwSHZY2NyLePmwU7SexEXnIz37jKC6NMEhus%3D",
  "realm" : "saml1"
}
Response examples (200)
A successful response from `POST /_security/saml/invalidate`.
{
  "redirect" : "https://my-idp.org/logout/SAMLResponse=....",
  "invalidated" : 2,
  "realm" : "saml1"
}









































































Get the snapshot status Generally available; Added in 7.8.0

GET /_snapshot/{repository}/{snapshot}/_status

All methods and paths for this operation:

GET /_snapshot/_status

GET /_snapshot/{repository}/_status
GET /_snapshot/{repository}/{snapshot}/_status

Get a detailed description of the current state for each shard participating in the snapshot. Note that this API should be used only to obtain detailed shard-level information for ongoing snapshots. If this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.

WARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive. The API requires a read from the repository for each shard in each snapshot. For example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards).

Depending on the latency of your storage, such requests can take an extremely long time to return results. These requests can also tax machine resources and, when using cloud storage, incur high processing costs.

Required authorization

  • Cluster privileges: monitor_snapshot

Path parameters

  • repository string Required

    A repository name

  • snapshot string | array[string] Required

    A comma-separated list of snapshot names

Query parameters

  • ignore_unavailable boolean

    Whether to ignore unavailable snapshots, defaults to false which means a SnapshotMissingException is thrown

  • master_timeout string

    Explicit operation timeout for connection to master node

    Values are -1 or 0.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • snapshots array[object] Required
      Hide snapshots attributes Show snapshots attributes object
      • include_global_state boolean Required
      • indices object Required
        Hide indices attribute Show indices attribute object
        • * object Additional properties
          Hide * attributes Show * attributes object
          • shards object Required
            Hide shards attribute Show shards attribute object
            • * object Additional properties
          • shards_stats object Required
            Hide shards_stats attributes Show shards_stats attributes object
            • done number Required
            • failed number Required
            • finalizing number Required
            • initializing number Required
            • started number Required
            • total number Required
          • stats object Required
            Hide stats attributes Show stats attributes object
            • incremental object Required
            • start_time_in_millis
            • 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.

            • time_in_millis
            • total object Required
      • repository string Required
      • shards_stats object Required
        Hide shards_stats attributes Show shards_stats attributes object
        • done number Required
        • failed number Required
        • finalizing number Required
        • initializing number Required
        • started number Required
        • total number Required
      • snapshot string Required
      • state string Required
      • stats object Required
        Hide stats attributes Show stats attributes object
        • incremental object Required
          Hide incremental attributes Show incremental attributes object
          • file_count number Required
          • size_in_bytes number Required
        • start_time_in_millis number

          Time unit for milliseconds

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

        • time_in_millis number

          Time unit for milliseconds

        • total object Required
          Hide total attributes Show total attributes object
          • file_count number Required
          • size_in_bytes number Required
      • uuid string Required
GET /_snapshot/{repository}/{snapshot}/_status
GET _snapshot/my_repository/snapshot_2/_status
resp = client.snapshot.status(
    repository="my_repository",
    snapshot="snapshot_2",
)
const response = await client.snapshot.status({
  repository: "my_repository",
  snapshot: "snapshot_2",
});
response = client.snapshot.status(
  repository: "my_repository",
  snapshot: "snapshot_2"
)
$resp = $client->snapshot()->status([
    "repository" => "my_repository",
    "snapshot" => "snapshot_2",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_snapshot/my_repository/snapshot_2/_status"
client.snapshot().status(s -> s
    .repository("my_repository")
    .snapshot("snapshot_2")
);
Response examples (200)
A successful response from `GET _snapshot/my_repository/snapshot_2/_status`. The response contains detailed status information for `snapshot_2` in the `my_repository` repository.
{
  "snapshots" : [
    {
      "snapshot" : "snapshot_2",
      "repository" : "my_repository",
      "uuid" : "lNeQD1SvTQCqqJUMQSwmGg",
      "state" : "SUCCESS",
      "include_global_state" : false,
      "shards_stats" : {
        "initializing" : 0,
        "started" : 0,
        "finalizing" : 0,
        "done" : 1,
        "failed" : 0,
        "total" : 1
      },
      "stats" : {
        "incremental" : {
          "file_count" : 3,
          "size_in_bytes" : 5969
        },
        "total" : {
          "file_count" : 4,
          "size_in_bytes" : 6024
        },
        "start_time_in_millis" : 1594829326691,
        "time_in_millis" : 205
      },
      "indices" : {
        "index_1" : {
          "shards_stats" : {
            "initializing" : 0,
            "started" : 0,
            "finalizing" : 0,
            "done" : 1,
            "failed" : 0,
            "total" : 1
          },
          "stats" : {
            "incremental" : {
              "file_count" : 3,
              "size_in_bytes" : 5969
            },
            "total" : {
              "file_count" : 4,
              "size_in_bytes" : 6024
            },
            "start_time_in_millis" : 1594829326896,
            "time_in_millis" : 0
          },
          "shards" : {
            "0" : {
              "stage" : "DONE",
              "stats" : {
                "incremental" : {
                  "file_count" : 3,
                  "size_in_bytes" : 5969
                },
                "total" : {
                  "file_count" : 4,
                  "size_in_bytes" : 6024
                },
                "start_time_in_millis" : 1594829326896,
                "time_in_millis" : 0
              }
            }
          }
        }
      }
    }
  ]
}

Verify a snapshot repository Generally available; Added in 0.0.0

POST /_snapshot/{repository}/_verify

Check for common misconfigurations in a snapshot repository.

Required authorization

  • Cluster privileges: manage
External documentation

Path parameters

  • repository string Required

    A repository name

Query parameters

  • master_timeout string

    Explicit operation timeout for connection to master node

    Values are -1 or 0.

  • timeout string

    Explicit operation timeout

    Values are -1 or 0.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • nodes object Required
      Hide nodes attribute Show nodes attribute object
      • * object Additional properties
        Hide * attribute Show * attribute object
        • name string Required
POST /_snapshot/{repository}/_verify
POST _snapshot/my_unverified_backup/_verify
resp = client.snapshot.verify_repository(
    name="my_unverified_backup",
)
const response = await client.snapshot.verifyRepository({
  name: "my_unverified_backup",
});
response = client.snapshot.verify_repository(
  repository: "my_unverified_backup"
)
$resp = $client->snapshot()->verifyRepository([
    "repository" => "my_unverified_backup",
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_snapshot/my_unverified_backup/_verify"
client.snapshot().verifyRepository(v -> v
    .name("my_unverified_backup")
);





































SQL

Elasticsearch's SQL APIs enable you to run SQL queries on Elasticsearch indices and data streams.

Check out the overview and tutorials for the Elasticsearch SQL features




Delete an async SQL search Generally available; Added in 7.15.0

DELETE /_sql/async/delete/{id}

Delete an async SQL search or a stored synchronous SQL search. If the search is still running, the API cancels it.

If the Elasticsearch security features are enabled, only the following users can use this API to delete a search:

  • Users with the cancel_task cluster privilege.
  • The user who first submitted the search.

Required authorization

  • Cluster privileges: cancel_task

Path parameters

  • id string Required

    The identifier for the search.

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 _sql/async/delete/FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=
resp = client.sql.delete_async(
    id="FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=",
)
const response = await client.sql.deleteAsync({
  id: "FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=",
});
response = client.sql.delete_async(
  id: "FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI="
)
$resp = $client->sql()->deleteAsync([
    "id" => "FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=",
]);
curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_sql/async/delete/FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI="
client.sql().deleteAsync(d -> d
    .id("FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=")
);




Get the async SQL search status Generally available; Added in 7.15.0

GET /_sql/async/status/{id}

Get the current status of an async SQL search or a stored synchronous SQL search.

Required authorization

  • Cluster privileges: monitor

Path parameters

  • id string Required

    The identifier for the search.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • expiration_time_in_millis number

      Time unit for milliseconds

    • id string Required

      The identifier for the search.

    • is_running boolean Required

      If true, the search is still running. If false, the search has finished.

    • is_partial boolean Required

      If true, the response does not contain complete search results. If is_partial is true and is_running is true, the search is still running. If is_partial is true but is_running is false, the results are partial due to a failure or timeout.

    • start_time_in_millis number

      Time unit for milliseconds

    • completion_status number
GET _sql/async/status/FnR0TDhyWUVmUmVtWXRWZER4MXZiNFEad2F5UDk2ZVdTVHV1S0xDUy00SklUdzozMTU=
resp = client.sql.get_async_status(
    id="FnR0TDhyWUVmUmVtWXRWZER4MXZiNFEad2F5UDk2ZVdTVHV1S0xDUy00SklUdzozMTU=",
)
const response = await client.sql.getAsyncStatus({
  id: "FnR0TDhyWUVmUmVtWXRWZER4MXZiNFEad2F5UDk2ZVdTVHV1S0xDUy00SklUdzozMTU=",
});
response = client.sql.get_async_status(
  id: "FnR0TDhyWUVmUmVtWXRWZER4MXZiNFEad2F5UDk2ZVdTVHV1S0xDUy00SklUdzozMTU="
)
$resp = $client->sql()->getAsyncStatus([
    "id" => "FnR0TDhyWUVmUmVtWXRWZER4MXZiNFEad2F5UDk2ZVdTVHV1S0xDUy00SklUdzozMTU=",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_sql/async/status/FnR0TDhyWUVmUmVtWXRWZER4MXZiNFEad2F5UDk2ZVdTVHV1S0xDUy00SklUdzozMTU="
client.sql().getAsyncStatus(g -> g
    .id("FnR0TDhyWUVmUmVtWXRWZER4MXZiNFEad2F5UDk2ZVdTVHV1S0xDUy00SklUdzozMTU=")
);




Translate SQL into Elasticsearch queries Generally available; Added in 6.3.0

GET /_sql/translate

All methods and paths for this operation:

POST /_sql/translate

GET /_sql/translate

Translate an SQL search into a search API request containing Query DSL. It accepts the same request body parameters as the SQL search API, excluding cursor.

Required authorization

  • Index privileges: read
application/json

Body Required

  • fetch_size number

    The maximum number of rows (or entries) to return in one response.

    Default value is 1000.

  • filter object

    An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

    External documentation
  • query string Required

    The SQL query to run.

  • time_zone string

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • aggregations object
    • size number
    • _source boolean | object

      Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.

      One of:
    • fields array[object]

      A reference to a field with formatting instructions on how to return the value

      Hide fields attributes Show 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

        The format in which the values are returned.

      • include_unmapped boolean
    • query object

      An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

      External documentation
    • sort string | object | array[string | object]

      One of:

      Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

POST _sql/translate
{
  "query": "SELECT * FROM library ORDER BY page_count DESC",
  "fetch_size": 10
}
resp = client.sql.translate(
    query="SELECT * FROM library ORDER BY page_count DESC",
    fetch_size=10,
)
const response = await client.sql.translate({
  query: "SELECT * FROM library ORDER BY page_count DESC",
  fetch_size: 10,
});
response = client.sql.translate(
  body: {
    "query": "SELECT * FROM library ORDER BY page_count DESC",
    "fetch_size": 10
  }
)
$resp = $client->sql()->translate([
    "body" => [
        "query" => "SELECT * FROM library ORDER BY page_count DESC",
        "fetch_size" => 10,
    ],
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"query":"SELECT * FROM library ORDER BY page_count DESC","fetch_size":10}' "$ELASTICSEARCH_URL/_sql/translate"
client.sql().translate(t -> t
    .fetchSize(10)
    .query("SELECT * FROM library ORDER BY page_count DESC")
);
Request example
{
  "query": "SELECT * FROM library ORDER BY page_count DESC",
  "fetch_size": 10
}

























Get all synonym sets Generally available; Added in 8.10.0

GET /_synonyms

Get a summary of all defined synonym sets.

Required authorization

  • Cluster privileges: manage_search_synonyms

Query parameters

  • from number

    The starting offset for synonyms sets to retrieve.

  • size number

    The maximum number of synonyms sets to retrieve.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • count number Required

      The total number of synonyms sets defined.

    • results array[object] Required

      The identifier and total number of defined synonym rules for each synonyms set.

      Hide results attributes Show results attributes object
      • synonyms_set string Required
      • count number Required

        Number of synonym rules that the synonym set contains

GET _synonyms
resp = client.synonyms.get_synonyms_sets()
const response = await client.synonyms.getSynonymsSets();
response = client.synonyms.get_synonyms_sets
$resp = $client->synonyms()->getSynonymsSets();
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_synonyms"
client.synonyms().getSynonymsSets(g -> g);
Response examples (200)
A successful response from `GET _synonyms`.
{
  "count": 3,
  "results": [
    {
      "synonyms_set": "ecommerce-synonyms",
      "count": 2
    },
    {
      "synonyms_set": "my-synonyms-set",
      "count": 3
    },
    {
      "synonyms_set": "new-ecommerce-synonyms",
      "count": 1
    }
  ]
}

Task management













Text structure


























Delete a transform Generally available; Added in 7.5.0

DELETE /_transform/{transform_id}

Required authorization

  • Cluster privileges: manage_transform

Path parameters

  • transform_id string Required

    Identifier for the transform.

Query parameters

  • force boolean

    If this value is false, the transform must be stopped before it can be deleted. If true, the transform is deleted regardless of its current state.

  • delete_dest_index boolean

    If this value is true, the destination index is deleted together with the transform. If false, the destination index will not be deleted

  • 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 /_transform/{transform_id}
DELETE _transform/ecommerce_transform
resp = client.transform.delete_transform(
    transform_id="ecommerce_transform",
)
const response = await client.transform.deleteTransform({
  transform_id: "ecommerce_transform",
});
response = client.transform.delete_transform(
  transform_id: "ecommerce_transform"
)
$resp = $client->transform()->deleteTransform([
    "transform_id" => "ecommerce_transform",
]);
curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_transform/ecommerce_transform"
client.transform().deleteTransform(d -> d
    .transformId("ecommerce_transform")
);
Response examples (200)
A successful response when the transform is deleted.
{
  "acknowledged": true
}





































Get usage information Generally available

GET /_xpack/usage

Get information about the features that are currently enabled and available under the current license. The API also provides some usage statistics.

Required authorization

  • Cluster privileges: monitor

Query parameters

  • master_timeout string

    The period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. To indicate that the request should never timeout, set it to -1.

    Values are -1 or 0.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • aggregate_metric object Required
      Hide aggregate_metric attributes Show aggregate_metric attributes object
      • available boolean Required
      • enabled boolean Required
    • analytics object
      Hide analytics attributes Show analytics attributes object
      • available boolean Required
      • enabled boolean Required
      • stats object Required
        Hide stats attributes Show stats attributes object
        • boxplot_usage number Required
        • cumulative_cardinality_usage number Required
        • string_stats_usage number Required
        • top_metrics_usage number Required
        • t_test_usage number Required
        • moving_percentiles_usage number Required
        • normalize_usage number Required
        • rate_usage number Required
        • multi_terms_usage number
    • archive object
      Hide archive attributes Show archive attributes object
      • available boolean Required
      • enabled boolean Required
      • indices_count number Required
    • watcher object
      Hide watcher attributes Show watcher attributes object
      • available boolean Required
      • enabled boolean Required
      • execution object Required
        Hide execution attribute Show execution attribute object
        • actions object Required
          Hide actions attribute Show actions attribute object
          • * object Additional properties
            Hide * attribute Show * attribute object
            • total 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.

      • watch object Required
        Hide watch attributes Show watch attributes object
        • input object Required
          Hide input attribute Show input attribute object
          • * object Additional properties
            Hide * attributes Show * attributes object
            • active number Required
            • total number Required
        • condition object
          Hide condition attribute Show condition attribute object
          • * object Additional properties
            Hide * attributes Show * attributes object
            • active number Required
            • total number Required
        • action object
          Hide action attribute Show action attribute object
          • * object Additional properties
            Hide * attributes Show * attributes object
            • active number Required
            • total number Required
        • trigger object Required
          Hide trigger attributes Show trigger attributes object
          • _all object Required Additional properties
            Hide _all attributes Show _all attributes object
            • active number Required
            • total number Required
      • count object Required Additional properties
        Hide count attributes Show count attributes object
        • active number Required
        • total number Required
    • ccr object
      Hide ccr attributes Show ccr attributes object
      • available boolean Required
      • enabled boolean Required
      • auto_follow_patterns_count number Required
      • follower_indices_count number Required
    • data_frame object
      Hide data_frame attributes Show data_frame attributes object
      • available boolean Required
      • enabled boolean Required
    • data_science object
      Hide data_science attributes Show data_science attributes object
      • available boolean Required
      • enabled boolean Required
    • data_streams object
      Hide data_streams attributes Show data_streams attributes object
      • available boolean Required
      • enabled boolean Required
      • data_streams number Required
      • indices_count number Required
    • data_tiers object
      Hide data_tiers attributes Show data_tiers attributes object
      • available boolean Required
      • enabled boolean Required
      • data_warm object Required
        Hide data_warm attributes Show data_warm attributes object
        • node_count number Required
        • index_count number Required
        • total_shard_count number Required
        • primary_shard_count number Required
        • doc_count number Required
        • total_size_bytes number Required
        • primary_size_bytes number Required
        • primary_shard_size_avg_bytes number Required
        • primary_shard_size_median_bytes number Required
        • primary_shard_size_mad_bytes number Required
      • data_frozen object
        Hide data_frozen attributes Show data_frozen attributes object
        • node_count number Required
        • index_count number Required
        • total_shard_count number Required
        • primary_shard_count number Required
        • doc_count number Required
        • total_size_bytes number Required
        • primary_size_bytes number Required
        • primary_shard_size_avg_bytes number Required
        • primary_shard_size_median_bytes number Required
        • primary_shard_size_mad_bytes number Required
      • data_cold object Required
        Hide data_cold attributes Show data_cold attributes object
        • node_count number Required
        • index_count number Required
        • total_shard_count number Required
        • primary_shard_count number Required
        • doc_count number Required
        • total_size_bytes number Required
        • primary_size_bytes number Required
        • primary_shard_size_avg_bytes number Required
        • primary_shard_size_median_bytes number Required
        • primary_shard_size_mad_bytes number Required
      • data_content object Required
        Hide data_content attributes Show data_content attributes object
        • node_count number Required
        • index_count number Required
        • total_shard_count number Required
        • primary_shard_count number Required
        • doc_count number Required
        • total_size_bytes number Required
        • primary_size_bytes number Required
        • primary_shard_size_avg_bytes number Required
        • primary_shard_size_median_bytes number Required
        • primary_shard_size_mad_bytes number Required
      • data_hot object Required
        Hide data_hot attributes Show data_hot attributes object
        • node_count number Required
        • index_count number Required
        • total_shard_count number Required
        • primary_shard_count number Required
        • doc_count number Required
        • total_size_bytes number Required
        • primary_size_bytes number Required
        • primary_shard_size_avg_bytes number Required
        • primary_shard_size_median_bytes number Required
        • primary_shard_size_mad_bytes number Required
    • enrich object
      Hide enrich attributes Show enrich attributes object
      • available boolean Required
      • enabled boolean Required
    • eql object
      Hide eql attributes Show eql attributes object
      • available boolean Required
      • enabled boolean Required
      • features object Required
        Hide features attributes Show features attributes object
        • join number Required
        • joins object Required
          Hide joins attributes Show joins attributes object
          • join_queries_two number Required
          • join_queries_three number Required
          • join_until number Required
          • join_queries_five_or_more number Required
          • join_queries_four number Required
        • keys object Required
          Hide keys attributes Show keys attributes object
          • join_keys_two number Required
          • join_keys_one number Required
          • join_keys_three number Required
          • join_keys_five_or_more number Required
          • join_keys_four number Required
        • event number Required
        • pipes object Required
          Hide pipes attributes Show pipes attributes object
          • pipe_tail number Required
          • pipe_head number Required
        • sequence number Required
        • sequences object Required
          Hide sequences attributes Show sequences attributes object
          • sequence_queries_three number Required
          • sequence_queries_four number Required
          • sequence_queries_two number Required
          • sequence_until number Required
          • sequence_queries_five_or_more number Required
          • sequence_maxspan number Required
      • queries object Required
        Hide queries attribute Show queries attribute object
        • * object Additional properties
          Hide * attributes Show * attributes object
          • count number
          • failed number
          • paging number
          • total number
    • flattened object
      Hide flattened attributes Show flattened attributes object
      • available boolean Required
      • enabled boolean Required
      • field_count number Required
    • frozen_indices object
      Hide frozen_indices attributes Show frozen_indices attributes object
      • available boolean Required
      • enabled boolean Required
      • indices_count number Required
    • graph object Required
      Hide graph attributes Show graph attributes object
      • available boolean Required
      • enabled boolean Required
    • health_api object
      Hide health_api attributes Show health_api attributes object
      • available boolean Required
      • enabled boolean Required
      • invocations object Required
        Hide invocations attribute Show invocations attribute object
        • total number Required
    • ilm object Required
      Hide ilm attributes Show ilm attributes object
      • policy_count number Required
      • policy_stats array[object] Required
        Hide policy_stats attributes Show policy_stats attributes object
        • indices_managed number Required
        • phases object Required
          Hide phases attributes Show phases attributes object
          • cold object
            Hide cold attributes Show cold attributes object
            • actions array[string] Required
            • min_age
          • delete object
            Hide delete attributes Show delete attributes object
            • actions array[string] Required
            • min_age
          • frozen object
            Hide frozen attributes Show frozen attributes object
            • actions array[string] Required
            • min_age
          • hot object
            Hide hot attributes Show hot attributes object
            • actions array[string] Required
            • min_age
          • warm object
            Hide warm attributes Show warm attributes object
            • actions array[string] Required
            • min_age
    • logstash object Required
      Hide logstash attributes Show logstash attributes object
      • available boolean Required
      • enabled boolean Required
    • ml object
      Hide ml attributes Show ml attributes object
      • available boolean Required
      • enabled boolean Required
      • datafeeds object Required
        Hide datafeeds attribute Show datafeeds attribute object
        • * object Additional properties
          Hide * attribute Show * attribute object
          • count number Required
      • jobs object Required

        Job usage statistics. The _all entry is always present and gathers statistics for all jobs.

        Hide jobs attribute Show jobs attribute object
        • * object Additional properties
          Hide * attributes Show * attributes object
          • count number Required
          • created_by object Required
            Hide created_by attribute Show created_by attribute object
            • * number Additional properties
          • detectors object Required
            Hide detectors attributes Show detectors attributes object
            • avg number Required
            • max number Required
            • min number Required
            • total number Required
          • forecasts object Required
            Hide forecasts attributes Show forecasts attributes object
            • total number Required
            • forecasted_jobs number Required
          • model_size object Required
            Hide model_size attributes Show model_size attributes object
            • avg number Required
            • max number Required
            • min number Required
            • total number Required
      • node_count number Required
      • data_frame_analytics_jobs object Required
        Hide data_frame_analytics_jobs attributes Show data_frame_analytics_jobs attributes object
        • memory_usage object
          Hide memory_usage attribute Show memory_usage attribute object
          • peak_usage_bytes object Required
            Hide peak_usage_bytes attributes Show peak_usage_bytes attributes object
            • avg number Required
            • max number Required
            • min number Required
            • total number Required
        • _all object Required
          Hide _all attribute Show _all attribute object
          • count number Required
        • analysis_counts object
          Hide analysis_counts attributes Show analysis_counts attributes object
          • classification number
          • outlier_detection number
          • regression number
        • stopped object
          Hide stopped attribute Show stopped attribute object
          • count number Required
      • inference object Required
        Hide inference attributes Show inference attributes object
        • ingest_processors object Required
          Hide ingest_processors attribute Show ingest_processors attribute object
          • * object Additional properties
            Hide * attributes Show * attributes object
            • num_docs_processed object Required
            • pipelines object Required
            • num_failures object Required
            • time_ms object Required
        • trained_models object Required
          Hide trained_models attributes Show trained_models attributes object
          • estimated_operations object
            Hide estimated_operations attributes Show estimated_operations attributes object
            • avg number Required
            • max number Required
            • min number Required
            • total number Required
          • estimated_heap_memory_usage_bytes object
            Hide estimated_heap_memory_usage_bytes attributes Show estimated_heap_memory_usage_bytes attributes object
            • avg number Required
            • max number Required
            • min number Required
            • total number Required
          • count object
            Hide count attributes Show count attributes object
            • total number Required
            • prepackaged number Required
            • other number Required
            • pass_through number
            • regression number
            • classification number
            • ner number
            • text_embedding number
          • _all object Required
            Hide _all attribute Show _all attribute object
            • count number Required
          • model_size_bytes object
            Hide model_size_bytes attributes Show model_size_bytes attributes object
            • avg number Required
            • max number Required
            • min number Required
            • total number Required
        • deployments object
          Hide deployments attributes Show deployments attributes object
          • count number Required
          • inference_counts object Required
            Hide inference_counts attributes Show inference_counts attributes object
            • avg number Required
            • max number Required
            • min number Required
            • total number Required
          • model_sizes_bytes object Required
            Hide model_sizes_bytes attributes Show model_sizes_bytes attributes object
            • avg number Required
            • max number Required
            • min number Required
            • total number Required
          • time_ms object Required
            Hide time_ms attribute Show time_ms attribute object
            • avg number Required
    • monitoring object
      Hide monitoring attributes Show monitoring attributes object
      • available boolean Required
      • enabled boolean Required
      • collection_enabled boolean Required
      • enabled_exporters object Required
        Hide enabled_exporters attribute Show enabled_exporters attribute object
        • * number Additional properties
    • rollup object Required
      Hide rollup attributes Show rollup attributes object
      • available boolean Required
      • enabled boolean Required
    • runtime_fields object
      Hide runtime_fields attributes Show runtime_fields attributes object
      • available boolean Required
      • enabled boolean Required
      • field_types array[object] Required
        Hide field_types attributes Show field_types attributes object
        • chars_max number Required
        • chars_total number Required
        • count number Required
        • doc_max number Required
        • doc_total number Required
        • index_count number Required
        • lang array[string] Required
        • lines_max number Required
        • lines_total number Required
        • name string Required

          Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

        • scriptless_count number Required
        • shadowed_count number Required
        • source_max number Required
        • source_total number Required
    • spatial object Required
      Hide spatial attributes Show spatial attributes object
      • available boolean Required
      • enabled boolean Required
    • searchable_snapshots object
      Hide searchable_snapshots attributes Show searchable_snapshots attributes object
      • available boolean Required
      • enabled boolean Required
      • indices_count number Required
      • full_copy_indices_count number
      • shared_cache_indices_count number
    • security object
      Hide security attributes Show security attributes object
      • available boolean Required
      • enabled boolean Required
      • api_key_service object Required
        Hide api_key_service attribute Show api_key_service attribute object
        • enabled boolean Required
      • anonymous object Required
        Hide anonymous attribute Show anonymous attribute object
        • enabled boolean Required
      • audit object
        Hide audit attributes Show audit attributes object
        • enabled boolean Required
        • outputs array[string]
      • fips_140 object Required
        Hide fips_140 attribute Show fips_140 attribute object
        • enabled boolean Required
      • ipfilter object Required
        Hide ipfilter attributes Show ipfilter attributes object
        • http boolean Required
        • transport boolean Required
      • realms object Required
      • role_mapping object Required
        Hide role_mapping attribute Show role_mapping attribute object
        • * object Additional properties
          Hide * attributes Show * attributes object
          • enabled number Required
          • size number Required
      • roles object Required
        Hide roles attributes Show roles attributes object
        • native object Required
          Hide native attributes Show native attributes object
          • dls boolean Required
          • fls boolean Required
          • size number Required
        • dls object Required
          Hide dls attribute Show dls attribute object
          • bit_set_cache object Required
            Hide bit_set_cache attributes Show bit_set_cache attributes object
            • count number Required
            • memory
            • memory_in_bytes number Required
        • file object Required
          Hide file attributes Show file attributes object
          • dls boolean Required
          • fls boolean Required
          • size number Required
      • ssl object Required
        Hide ssl attributes Show ssl attributes object
        • http object Required
          Hide http attribute Show http attribute object
          • enabled boolean Required
        • transport object Required
          Hide transport attribute Show transport attribute object
          • enabled boolean Required
      • system_key object
        Hide system_key attribute Show system_key attribute object
        • enabled boolean Required
      • token_service object Required
        Hide token_service attribute Show token_service attribute object
        • enabled boolean Required
      • operator_privileges object Required
        Hide operator_privileges attributes Show operator_privileges attributes object
        • available boolean Required
        • enabled boolean Required
    • slm object
      Hide slm attributes Show slm attributes object
      • available boolean Required
      • enabled boolean Required
      • policy_count number
      • policy_stats object
        Hide policy_stats attributes Show policy_stats attributes object
        • retention_deletion_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.

        • Time unit for milliseconds

        • retention_failed number
        • retention_runs number
        • retention_timed_out number
        • policy string
        • total_snapshots_deleted number
        • total_snapshot_deletion_failures number
        • total_snapshots_failed number
        • total_snapshots_taken number
    • sql object
      Hide sql attributes Show sql attributes object
      • available boolean Required
      • enabled boolean Required
      • features object Required
        Hide features attribute Show features attribute object
        • * number Additional properties
      • queries object Required
        Hide queries attribute Show queries attribute object
        • * object Additional properties
          Hide * attributes Show * attributes object
          • count number
          • failed number
          • paging number
          • total number
    • transform object Required
      Hide transform attributes Show transform attributes object
      • available boolean Required
      • enabled boolean Required
    • vectors object
      Hide vectors attributes Show vectors attributes object
      • available boolean Required
      • enabled boolean Required
      • dense_vector_dims_avg_count number Required
      • dense_vector_fields_count number Required
      • sparse_vector_fields_count number
    • voting_only object Required
      Hide voting_only attributes Show voting_only attributes object
      • available boolean Required
      • enabled boolean Required
GET /_xpack/usage
resp = client.xpack.usage()
const response = await client.xpack.usage();
response = client.xpack.usage
$resp = $client->xpack()->usage();
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_xpack/usage"
client.xpack().usage(u -> u);
Response examples (200)
An abbreviated response from `GET /_xpack/usage`.
{
  "security" : {
    "available" : true,
    "enabled" : true
  },
  "monitoring" : {
    "available" : true,
    "enabled" : true,
    "collection_enabled" : false,
    "enabled_exporters" : {
      "local" : 1
    }
  },
  "watcher" : {
      "available" : true,
      "enabled" : true,
      "execution" : {
        "actions" : {
          "_all" : {
            "total" : 0,
            "total_time_in_ms" : 0
          }
        }
      },
    "watch" : {
      "input" : {
        "_all" : {
          "total" : 0,
          "active" : 0
        }
      },
      "trigger" : {
        "_all" : {
          "total" : 0,
          "active" : 0
        }
      }
    },
    "count" : {
      "total" : 0,
      "active" : 0
    }
  },
  "graph" : {
    "available" : true,
    "enabled" : true
  },
  "ml" : {
    "available" : true,
    "enabled" : true,
    "jobs" : {
      "_all" : {
        "count" : 0,
        "detectors" : { },
        "created_by" : { },
        "model_size" : { },
        "forecasts" : {
          "total" : 0,
          "forecasted_jobs" : 0
        }
      }
    },
    "datafeeds" : {
      "_all" : {
        "count" : 0
      }
    },
    "data_frame_analytics_jobs" : {
      "_all" : {
        "count" : 0
      },
      "analysis_counts": { },
      "memory_usage": {
        "peak_usage_bytes": {
          "min": 0.0,
          "max": 0.0,
          "avg": 0.0,
          "total": 0.0
        }
      }
    },
    "inference" : {
      "ingest_processors" : {
        "_all" : {
          "num_docs_processed" : {
            "max" : 0,
            "sum" : 0,
            "min" : 0
          },
          "pipelines" : {
            "count" : 0
          },
          "num_failures" : {
            "max" : 0,
            "sum" : 0,
            "min" : 0
          },
          "time_ms" : {
            "max" : 0,
            "sum" : 0,
            "min" : 0
          }
        }
      },
      "trained_models" : {
        "_all" : {
          "count": 1
        },
        "count": {
          "total": 1,
          "prepackaged": 1,
          "other": 0
        },
        "model_size_bytes": {
          "min": 0.0,
          "max": 0.0,
          "avg": 0.0,
          "total": 0.0
        },
        "estimated_operations": {
          "min": 0.0,
          "max": 0.0,
          "avg": 0.0,
          "total": 0.0
        }
      },
      "deployments": {
        "count": 0,
        "inference_counts": {
          "total": 0.0,
          "min": 0.0,
          "avg": 0.0,
          "max": 0.0
        },
        "stats_by_model": [],
        "model_sizes_bytes": {
          "total": 0.0,
          "min": 0.0,
          "avg": 0.0,
          "max": 0.0
        },
        "time_ms": {
          "avg": 0.0
        }
      }
    },
    "node_count" : 1,
    "memory": {
      anomaly_detectors_memory_bytes: 0,
      data_frame_analytics_memory_bytes: 0,
      pytorch_inference_memory_bytes: 0,
      total_used_memory_bytes: 0
    }
  },
  "inference": {
    "available" : true,
    "enabled" : true,
    "models" : [ ]
  },
  "logstash" : {
    "available" : true,
    "enabled" : true
  },
  "eql" : {
    "available" : true,
    "enabled" : true
  },
  "esql" : {
    "available" : true,
    "enabled" : true,
    "features" : {
      "eval" : 0,
      "stats" : 0,
      "dissect": 0,
      "grok" : 0,
      "limit" : 0,
      "where" : 0,
      "sort" : 0,
      "drop" : 0,
      "show" : 0,
      "rename" : 0,
      "mv_expand" : 0,
      "keep" : 0,
      "enrich" : 0,
      "from" : 0,
      "row" : 0
    },
    "queries" : {
      "rest" : {
        "total" : 0,
        "failed" : 0
      },
      "kibana" : {
        "total" : 0,
        "failed" : 0
      },
      "_all" : {
        "total" : 0,
        "failed" : 0
    }
  }
  },
  "sql" : {
    "available" : true,
    "enabled" : true,
    "features" : {
      "having" : 0,
      "subselect" : 0,
      "limit" : 0,
      "orderby" : 0,
      "where" : 0,
      "join" : 0,
      "groupby" : 0,
      "command" : 0,
      "local" : 0
    },
    "queries" : {
      "rest" : {
        "total" : 0,
        "paging" : 0,
        "failed" : 0
      },
      "cli" : {
        "total" : 0,
        "paging" : 0,
        "failed" : 0
      },
      "canvas" : {
        "total" : 0,
        "paging" : 0,
        "failed" : 0
      },
      "odbc" : {
        "total" : 0,
        "paging" : 0,
        "failed" : 0
      },
      "jdbc" : {
        "total" : 0,
        "paging" : 0,
        "failed" : 0
      },
      "odbc32" : {
        "total" : 0,
        "paging" : 0,
        "failed" : 0
      },
      "odbc64" : {
        "total" : 0,
        "paging" : 0,
        "failed" : 0
      },
      "_all" : {
        "total" : 0,
        "paging" : 0,
        "failed" : 0
      },
      "translate" : {
        "count" : 0
      }
    }
  },
  "rollup" : {
    "available" : true,
    "enabled" : true
  },
  "ilm" : {
    "policy_count" : 3,
    "policy_stats" : [ ]
  },
  "slm" : {
    "available" : true,
    "enabled" : true
  },
  "ccr" : {
    "available" : true,
    "enabled" : true,
    "follower_indices_count" : 0,
    "auto_follow_patterns_count" : 0
  },
  "transform" : {
    "available" : true,
    "enabled" : true
  },
  "voting_only" : {
    "available" : true,
    "enabled" : true
  },
  "searchable_snapshots" : {
    "available" : true,
    "enabled" : true,
    "indices_count" : 0,
    "full_copy_indices_count" : 0,
    "shared_cache_indices_count" : 0
  },
  "frozen_indices" : {
    "available" : true,
    "enabled" : true,
    "indices_count" : 0
  },
  "spatial" : {
    "available" : true,
    "enabled" : true
  },
  "analytics" : {
    "available" : true,
    "enabled" : true,
    "stats": {
      "boxplot_usage" : 0,
      "top_metrics_usage" : 0,
      "normalize_usage" : 0,
      "cumulative_cardinality_usage" : 0,
      "t_test_usage" : 0,
      "rate_usage" : 0,
      "string_stats_usage" : 0,
      "moving_percentiles_usage" : 0,
      "multi_terms_usage" : 0
    }
  },
  "data_streams" : {
    "available" : true,
    "enabled" : true,
    "data_streams" : 0,
    "indices_count" : 0
  },
  "data_lifecycle" : {
    "available": true,
    "enabled": true,
    "count": 0,
    "default_rollover_used": true,
    "data_retention": {
      "configured_data_streams": 0
    },
    "effective_retention": {
      "retained_data_streams": 0
    },
    "global_retention": {
      "default": {
        "defined": false
      },
      "max": {
        "defined": false
      }
    }
  },
  "data_tiers" : {
    "available" : true,
    "enabled" : true,
    "data_warm" : {
      "node_count" : 0,
      "index_count" : 0,
      "total_shard_count" : 0,
      "primary_shard_count" : 0,
      "doc_count" : 0,
      "total_size_bytes" : 0,
      "primary_size_bytes" : 0,
      "primary_shard_size_avg_bytes" : 0,
      "primary_shard_size_median_bytes" : 0,
      "primary_shard_size_mad_bytes" : 0
    },
    "data_frozen" : {
      "node_count" : 1,
      "index_count" : 0,
      "total_shard_count" : 0,
      "primary_shard_count" : 0,
      "doc_count" : 0,
      "total_size_bytes" : 0,
      "primary_size_bytes" : 0,
      "primary_shard_size_avg_bytes" : 0,
      "primary_shard_size_median_bytes" : 0,
      "primary_shard_size_mad_bytes" : 0
    },
    "data_cold" : {
      "node_count" : 0,
      "index_count" : 0,
      "total_shard_count" : 0,
      "primary_shard_count" : 0,
      "doc_count" : 0,
      "total_size_bytes" : 0,
      "primary_size_bytes" : 0,
      "primary_shard_size_avg_bytes" : 0,
      "primary_shard_size_median_bytes" : 0,
      "primary_shard_size_mad_bytes" : 0
    },
    "data_content" : {
      "node_count" : 0,
      "index_count" : 0,
      "total_shard_count" : 0,
      "primary_shard_count" : 0,
      "doc_count" : 0,
      "total_size_bytes" : 0,
      "primary_size_bytes" : 0,
      "primary_shard_size_avg_bytes" : 0,
      "primary_shard_size_median_bytes" : 0,
      "primary_shard_size_mad_bytes" : 0
    },
    "data_hot" : {
      "node_count" : 0,
      "index_count" : 0,
      "total_shard_count" : 0,
      "primary_shard_count" : 0,
      "doc_count" : 0,
      "total_size_bytes" : 0,
      "primary_size_bytes" : 0,
      "primary_shard_size_avg_bytes" : 0,
      "primary_shard_size_median_bytes" : 0,
      "primary_shard_size_mad_bytes" : 0
    }
  },
  "aggregate_metric" : {
    "available" : true,
    "enabled" : true
  },
  "archive" : {
    "available" : true,
    "enabled" : true,
    "indices_count" : 0
  },
  "health_api" : {
    "available" : true,
    "enabled" : true,
    "invocations": {
      "total": 0
    }
  },
  "remote_clusters": {
    "size": 0,
    "mode": {
      "proxy": 0,
      "sniff": 0
    },
    "security": {
      "cert": 0,
      "api_key": 0
    }
  },
  "enterprise_search" : {
    "available": true,
    "enabled": true,
    "search_applications" : {
      "count": 0
    },
    "analytics_collections": {
      "count": 0
    },
    "query_rulesets": {
      "total_rule_count": 0,
      "total_count": 0,
      "min_rule_count": 0,
      "max_rule_count": 0
    }
  },
  "universal_profiling" : {
    "available" : true,
    "enabled" : true
  },
  "logsdb": {
    "available": true,
    "enabled": false,
    "indices_count": 0,
    "indices_with_synthetic_source": 0,
    "num_docs": 0,
    "size_in_bytes": 0,
    "has_custom_cutoff_date": false
  }
}

Watcher

You can use Watcher to watch for changes or anomalies in your data and perform the necessary actions in response.

Learn more about Watcher








Deactivate a watch Generally available

POST /_watcher/watch/{watch_id}/_deactivate

All methods and paths for this operation:

PUT /_watcher/watch/{watch_id}/_deactivate

POST /_watcher/watch/{watch_id}/_deactivate

A watch can be either active or inactive.

Required authorization

  • Cluster privileges: manage_watcher
External documentation

Path parameters

  • watch_id string Required

    The watch identifier.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • status object Required
      Hide status attributes Show status attributes object
      • actions object Required
        Hide actions attribute Show actions attribute object
        • * object Additional properties
          Hide * attributes Show * attributes object
          • ack object Required
            Hide ack attributes Show ack attributes object
            • state string Required

              Values are awaits_successful_execution, ackable, or acked.

            • timestamp string
          • last_execution object
            Hide last_execution attributes Show last_execution attributes object
            • successful boolean Required
            • timestamp string
            • reason string
          • last_successful_execution object
            Hide last_successful_execution attributes Show last_successful_execution attributes object
            • successful boolean Required
            • timestamp string
            • reason string
          • last_throttle object
            Hide last_throttle attributes Show last_throttle attributes object
            • reason string Required
            • timestamp string
      • state object Required
        Hide state attributes Show state attributes object
        • active boolean Required
        • timestamp 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:
      • version number Required
POST /_watcher/watch/{watch_id}/_deactivate
PUT _watcher/watch/my_watch/_deactivate
resp = client.watcher.deactivate_watch(
    watch_id="my_watch",
)
const response = await client.watcher.deactivateWatch({
  watch_id: "my_watch",
});
response = client.watcher.deactivate_watch(
  watch_id: "my_watch"
)
$resp = $client->watcher()->deactivateWatch([
    "watch_id" => "my_watch",
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_watcher/watch/my_watch/_deactivate"
client.watcher().deactivateWatch(d -> d
    .watchId("my_watch")
);




















Update Watcher index settings Generally available

PUT /_watcher/settings

Update settings for the Watcher internal index (.watches). Only a subset of settings can be modified. This includes index.auto_expand_replicas, index.number_of_replicas, index.routing.allocation.exclude.*, index.routing.allocation.include.* and index.routing.allocation.require.*. Modification of index.routing.allocation.include._tier_preference is an exception and is not allowed as the Watcher shards must always be in the data_content tier.

Required authorization

  • Cluster privileges: manage_watcher

Query parameters

  • master_timeout string

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

    Values are -1 or 0.

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

application/json

Body Required

  • index.auto_expand_replicas string
  • index.number_of_replicas number

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • acknowledged boolean Required
PUT /_watcher/settings
{
  "index.auto_expand_replicas": "0-4"
}
resp = client.watcher.update_settings(
    index.auto_expand_replicas="0-4",
)
const response = await client.watcher.updateSettings({
  "index.auto_expand_replicas": "0-4",
});
response = client.watcher.update_settings(
  body: {
    "index.auto_expand_replicas": "0-4"
  }
)
$resp = $client->watcher()->updateSettings([
    "body" => [
        "index.auto_expand_replicas" => "0-4",
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"index.auto_expand_replicas":"0-4"}' "$ELASTICSEARCH_URL/_watcher/settings"
client.watcher().updateSettings(u -> u
    .indexAutoExpandReplicas("0-4")
);
Request example
{
  "index.auto_expand_replicas": "0-4"
}

Query watches Generally available; Added in 7.11.0

POST /_watcher/_query/watches

All methods and paths for this operation:

GET /_watcher/_query/watches

POST /_watcher/_query/watches

Get all registered watches in a paginated manner and optionally filter watches by a query.

Note that only the _id and metadata.* fields are queryable or sortable.

Required authorization

  • Cluster privileges: monitor_watcher
application/json

Body

  • from number

    The offset from the first result to fetch. It must be non-negative.

    Default value is 0.

  • size number

    The number of hits to return. It must be non-negative.

    Default value is 10.

  • query object

    An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

    External documentation
  • sort string | object | array[string | object]

    One of:

    Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

  • search_after array[number | string | boolean | null | object]

    A field value.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • count number Required

      The total number of watches found.

    • watches array[object] Required

      A list of watches based on the from, size, or search_after request body parameters.

      Hide watches attributes Show watches attributes object
      • _id string Required
      • status object
        Hide status attributes Show status attributes object
        • actions object Required
          Hide actions attribute Show actions attribute object
          • * object Additional properties
            Hide * attributes Show * attributes object
            • ack object Required
            • last_execution object
            • last_successful_execution object
            • last_throttle object
        • last_checked 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:
        • last_met_condition 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:
        • state object Required
          Hide state attributes Show state attributes object
          • active boolean Required
          • timestamp string
        • version number Required
        • execution_state string
      • watch object
        Hide watch attributes Show watch attributes object
        • actions object Required
          Hide actions attribute Show actions attribute object
          • * object Additional properties
            Hide * attributes Show * attributes object
            • action_type string

              Values are email, webhook, index, logging, slack, or pagerduty.

            • condition object
            • foreach string
            • max_iterations number
            • name string
            • throttle_period 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.

            • throttle_period_in_millis
            • transform object
            • index object
            • logging object
            • email
            • pagerduty
            • slack object
            • webhook
        • condition object Required
          Hide condition attributes Show condition attributes object
          • always object
          • array_compare object
            Hide array_compare attribute Show array_compare attribute object
            • * object Additional properties
          • compare object
            Hide compare attribute Show compare attribute object
            • * object Additional properties
          • never object
          • script object
            Hide script attributes Show script attributes object
            • lang string

              Default value is painless.

            • params object
            • source string
            • id string
        • input object Required
          Hide input attributes Show input attributes object
          • chain object
            Hide chain attribute Show chain attribute object
            • inputs array[object] Required
          • http object
            Hide http attributes Show http attributes object
            • extract array[string]
            • request object
            • response_content_type string

              Values are json, yaml, or text.

          • simple object
            Hide simple attribute Show simple attribute object
            • * object Additional properties
        • metadata object
          Hide metadata attribute Show metadata attribute object
          • * object Additional properties
        • status object
          Hide status attributes Show status attributes object
          • actions object Required
            Hide actions attribute Show actions attribute object
            • * object Additional properties
          • last_checked string
          • last_met_condition string
          • state object Required
            Hide state attributes Show state attributes object
            • active boolean Required
            • timestamp
          • version number Required
          • execution_state string
        • throttle_period 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.

        • throttle_period_in_millis number

          Time unit for milliseconds

        • transform object
          Hide transform attributes Show transform attributes object
          • chain array[object]
          • script object
            Hide script attributes Show script attributes object
            • lang string

              Default value is painless.

            • params object
            • source string
            • id string
        • trigger object Required
          Hide trigger attribute Show trigger attribute object
          • schedule object
            Hide schedule attributes Show schedule attributes object
            • timezone string
            • cron string
            • daily object
            • hourly object
            • interval 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.

            • monthly
            • weekly
            • yearly
      • _primary_term number
      • _seq_no number
GET /_watcher/_query/watches
resp = client.watcher.query_watches()
const response = await client.watcher.queryWatches();
response = client.watcher.query_watches
$resp = $client->watcher()->queryWatches();
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_watcher/_query/watches"
client.watcher().queryWatches();
Response examples (200)
A successful response from `GET /_watcher/_query/watches`.
{
  "count": 1,
  "watches": [
      {
          "_id": "my_watch",
          "watch": {
              "trigger": {
                  "schedule": {
                      "hourly": {
                          "minute": [
                              0,
                              5
                          ]
                      }
                  }
              },
              "input": {
                  "simple": {
                      "payload": {
                          "send": "yes"
                      }
                  }
              },
              "condition": {
                  "always": {}
              },
              "actions": {
                  "test_index": {
                      "index": {
                          "index": "test"
                      }
                  }
              }
          },
          "status": {
              "state": {
                  "active": true,
                  "timestamp": "2015-05-26T18:21:08.630Z"
              },
              "actions": {
                  "test_index": {
                      "ack": {
                          "timestamp": "2015-05-26T18:21:08.630Z",
                          "state": "awaits_successful_execution"
                      }
                  }
              },
              "version": -1
          },
          "_seq_no": 0,
          "_primary_term": 1
      }
  ]
}








Stop the watch service Generally available

POST /_watcher/_stop

Stop the Watcher service if it is running.

Required authorization

  • Cluster privileges: manage_watcher

Query parameters

  • master_timeout string

    The period to wait for the master node. If the master node is not available before the timeout expires, the request fails and returns an error. To indicate that the request should never timeout, set it to -1.

    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 _watcher/_stop
resp = client.watcher.stop()
const response = await client.watcher.stop();
response = client.watcher.stop
$resp = $client->watcher()->stop();
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_watcher/_stop"
client.watcher().stop(s -> s);
Response examples (200)
A successful response from `POST _watcher/_stop`.
{
  "acknowledged": true
}