Elasticsearch API

Base URL
http://api.example.com

Elasticsearch provides REST APIs that are used by the UI components and can be called directly to configure and access Elasticsearch features.

Documentation source and versions

This documentation is derived from the main branch of the elasticsearch-specification repository. It is provided under license Attribution-NonCommercial-NoDerivatives 4.0 International. This documentation contains work-in-progress information for future Elastic Stack releases.

Last update on Feb 12, 2025.

This API is provided under license Apache 2.0.

Authentication

The API accepts 3 different authentication methods:

Api key auth (http_api_key)

Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example:

curl -X GET "${ES_URL}/_cat/indices?v=true" \
  -H "Authorization: ApiKey ${API_KEY}"

To get API keys, use the /_security/api_key APIs.

Basic auth (http)

Basic auth tokens are constructed with the Basic keyword, followed by a space, followed by a base64-encoded string of your username:password (separated by a : colon).

Example: send a Authorization: Basic aGVsbG86aGVsbG8= HTTP header with your requests to authenticate with the API.

Bearer auth (http)

Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API. For examples, refer to Token-based authentication services










Delete an autoscaling policy Added in 7.11.0

DELETE /_autoscaling/policy/{name}

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

Path parameters

  • name string Required

    the name of the autoscaling policy

Query parameters

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

  • timeout string

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

Responses

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

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

DELETE /_autoscaling/policy/{name}
curl \
 --request DELETE http://api.example.com/_autoscaling/policy/{name}
Response examples (200)
This may be a response to either `DELETE /_autoscaling/policy/my_autoscaling_policy` or `DELETE /_autoscaling/policy/*`.
{
  "acknowledged": true
}








Create a behavioral analytics collection Technical preview

PUT /_application/analytics/{name}

Path parameters

  • name string Required

    The name of the analytics collection to be created or updated.

Responses

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

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

    • name string Required
PUT /_application/analytics/{name}
curl \
 --request PUT http://api.example.com/_application/analytics/{name}
Response examples (200)
{
  "acknowledged": true,
  "name": "string"
}




Get behavioral analytics collections Technical preview

GET /_application/analytics

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • * object Additional properties

      Additional properties are allowed.

      Hide * attribute Show * attribute object
      • event_data_stream object Required

        Additional properties are allowed.

        Hide event_data_stream attribute Show event_data_stream attribute object
GET /_application/analytics
curl \
 --request GET http://api.example.com/_application/analytics
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"
      }
  }
}

Create a behavioral analytics collection event Technical preview

POST /_application/analytics/{collection_name}/event/{event_type}

Path parameters

  • collection_name string Required

    The name of the behavioral analytics collection.

  • event_type string Required

    The analytics event type.

    Values are page_view, search, or search_click.

Query parameters

  • debug boolean

    Whether the response type has to include more details

application/json

Body Required

object object

Additional properties are allowed.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
POST /_application/analytics/{collection_name}/event/{event_type}
curl \
 --request POST http://api.example.com/_application/analytics/{collection_name}/event/{event_type} \
 --header "Content-Type: application/json" \
 --data '"{\n  \"session\": {\n    \"id\": \"1797ca95-91c9-4e2e-b1bd-9c38e6f386a9\"\n  },\n  \"user\": {\n    \"id\": \"5f26f01a-bbee-4202-9298-81261067abbd\"\n  },\n  \"search\":{\n    \"query\": \"search term\",\n    \"results\": {\n      \"items\": [\n        {\n          \"document\": {\n            \"id\": \"123\",\n            \"index\": \"products\"\n          }\n        }\n      ],\n      \"total_results\": 10\n    },\n    \"sort\": {\n      \"name\": \"relevance\"\n    },\n    \"search_application\": \"website\"\n  },\n  \"document\":{\n    \"id\": \"123\",\n    \"index\": \"products\"\n  }\n}"'
Request example
Run `POST _application/analytics/my_analytics_collection/event/search_click` to send a `search_click` event to an analytics collection called `my_analytics_collection`.
{
  "session": {
    "id": "1797ca95-91c9-4e2e-b1bd-9c38e6f386a9"
  },
  "user": {
    "id": "5f26f01a-bbee-4202-9298-81261067abbd"
  },
  "search":{
    "query": "search term",
    "results": {
      "items": [
        {
          "document": {
            "id": "123",
            "index": "products"
          }
        }
      ],
      "total_results": 10
    },
    "sort": {
      "name": "relevance"
    },
    "search_application": "website"
  },
  "document":{
    "id": "123",
    "index": "products"
  }
}
Response examples (200)
{
  "accepted": true,
  "event": {}
}





Get aliases

GET /_cat/aliases/{name}

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

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

Path parameters

  • name string | array[string] Required

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

Query parameters

  • expand_wildcards string | array[string]

    The type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. It supports comma-separated values, such as open,hidden.

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

Responses

GET /_cat/aliases/{name}
curl \
 --request GET http://api.example.com/_cat/aliases/{name}
Response examples (200)
[
  {
    "alias": "string",
    "index": "string",
    "filter": "string",
    "routing.index": "string",
    "routing.search": "string",
    "is_write_index": "string"
  }
]
















Get a document count

GET /_cat/count

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.

Responses

GET /_cat/count
curl \
 --request GET http://api.example.com/_cat/count
Response examples (200)
[
  {
    "": 42.0,
    "timestamp": "string",
    "count": "string"
  }
]




Get field data cache information

GET /_cat/fielddata

Get the amount of heap memory currently used by the field data cache on every data node 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 nodes stats API.

Query parameters

  • bytes string

    The unit used to display byte values.

    Values are b, kb, mb, gb, tb, or pb.

  • fields string | array[string]

    Comma-separated list of fields used to limit returned information.

Responses

GET /_cat/fielddata
curl \
 --request GET http://api.example.com/_cat/fielddata
Response examples (200)
[
  {
    "id": "string",
    "host": "string",
    "ip": "string",
    "node": "string",
    "field": "string",
    "size": "string"
  }
]

Get field data cache information

GET /_cat/fielddata/{fields}

Get the amount of heap memory currently used by the field data cache on every data node 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 nodes stats API.

Path parameters

  • fields string | array[string] Required

    Comma-separated list of fields used to limit returned information. To retrieve all fields, omit this parameter.

Query parameters

  • bytes string

    The unit used to display byte values.

    Values are b, kb, mb, gb, tb, or pb.

  • fields string | array[string]

    Comma-separated list of fields used to limit returned information.

Responses

GET /_cat/fielddata/{fields}
curl \
 --request GET http://api.example.com/_cat/fielddata/{fields}
Response examples (200)
[
  {
    "id": "string",
    "host": "string",
    "ip": "string",
    "node": "string",
    "field": "string",
    "size": "string"
  }
]

Get the cluster health status

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.

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.

Responses

GET /_cat/health
curl \
 --request GET http://api.example.com/_cat/health
Response examples (200)
[
  {
    "": 42.0,
    "timestamp": "string",
    "cluster": "string",
    "status": "string",
    "node.total": "string",
    "node.data": "string",
    "shards": "string",
    "pri": "string",
    "relo": "string",
    "init": "string",
    "unassign.pri": "string",
    "unassign": "string",
    "pending_tasks": "string",
    "max_task_wait_time": "string",
    "active_shards_percent": "string"
  }
]

Get CAT help

GET /_cat

Get help for the CAT APIs.

Responses

  • 200 application/json

    Additional properties are allowed.

GET /_cat
curl \
 --request GET http://api.example.com/_cat
Response examples (200)
{}
















Get data frame analytics jobs Added in 7.7.0

GET /_cat/ml/data_frame/analytics/{id}

Get configuration and usage information about data frame analytics jobs.

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

Path parameters

  • id string Required

    The ID of the data frame analytics to fetch

Query parameters

  • Whether to ignore if a wildcard expression matches no configs. (This includes _all string or when no configs have been specified)

  • bytes string

    The unit in which to display byte values

    Values are b, kb, mb, gb, tb, or pb.

  • h string | array[string]

    Comma-separated list of column names to display.

  • s string | array[string]

    Comma-separated list of column names or column aliases used to sort the response.

  • time string

    Unit used to display time values.

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

Responses

GET /_cat/ml/data_frame/analytics/{id}
curl \
 --request GET http://api.example.com/_cat/ml/data_frame/analytics/{id}
Response examples (200)
[
  {
    "id": "string",
    "type": "string",
    "create_time": "string",
    "version": "string",
    "source_index": "string",
    "dest_index": "string",
    "description": "string",
    "model_memory_limit": "string",
    "state": "string",
    "failure_reason": "string",
    "progress": "string",
    "assignment_explanation": "string",
    "node.id": "string",
    "node.name": "string",
    "node.ephemeral_id": "string",
    "node.address": "string"
  }
]




















Get trained models Added in 7.7.0

GET /_cat/ml/trained_models/{model_id}

Get configuration and usage information about inference trained models.

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

Path parameters

  • model_id string Required

    A unique identifier for the trained model.

Query parameters

  • Specifies what to do when the request: contains wildcard expressions and there are no models that match; contains the _all string or no identifiers and there are no matches; contains wildcard expressions and there are only partial matches. If true, the API returns an empty array when there are no matches and the subset of results when there are partial matches. If false, the API returns a 404 status code when there are no matches or only partial matches.

  • bytes string

    The unit used to display byte values.

    Values are b, kb, mb, gb, tb, or pb.

  • h string | array[string]

    A comma-separated list of column names to display.

  • s string | array[string]

    A comma-separated list of column names or aliases used to sort the response.

  • from number

    Skips the specified number of transforms.

  • size number

    The maximum number of transforms to display.

  • time string

    Unit used to display time values.

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

Responses

GET /_cat/ml/trained_models/{model_id}
curl \
 --request GET http://api.example.com/_cat/ml/trained_models/{model_id}
Response examples (200)
[
  {
    "id": "string",
    "created_by": "string",
    "": "string",
    "operations": "string",
    "license": "string",
    "version": "string",
    "description": "string",
    "ingest.pipelines": "string",
    "ingest.count": "string",
    "ingest.time": "string",
    "ingest.current": "string",
    "ingest.failed": "string",
    "data_frame.id": "string",
    "data_frame.create_time": "string",
    "data_frame.source_index": "string",
    "data_frame.analysis": "string",
    "type": "string"
  }
]








Get pending task information

GET /_cat/pending_tasks

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

Query parameters

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

  • Period to wait for a connection to the master node.

  • time string

    Unit used to display time values.

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

Responses

GET /_cat/pending_tasks
curl \
 --request GET http://api.example.com/_cat/pending_tasks
Response examples (200)
[
  {
    "insertOrder": "string",
    "timeInQueue": "string",
    "priority": "string",
    "source": "string"
  }
]

Get plugin information

GET /_cat/plugins

Get a list of plugins running on each node of a cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API.

Query parameters

  • Include bootstrap plugins in the response

  • local boolean

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

  • Period to wait for a connection to the master node.

Responses

GET /_cat/plugins
curl \
 --request GET http://api.example.com/_cat/plugins
Response examples (200)
[
  {
    "id": "string",
    "name": "string",
    "component": "string",
    "version": "string",
    "description": "string",
    "type": "string"
  }
]




Get shard recovery information

GET /_cat/recovery/{index}

Get information about ongoing and completed shard recoveries. Shard recovery is the process of initializing a shard copy, such as restoring a primary shard from a snapshot or syncing a replica shard from a primary shard. When a shard recovery completes, the recovered shard is available for search and indexing. For data streams, the API returns information about the stream’s backing indices. 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 index recovery API.

Path parameters

  • index string | array[string] Required

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

Query parameters

  • If true, the response only includes ongoing shard recoveries.

  • bytes string

    The unit used to display byte values.

    Values are b, kb, mb, gb, tb, or pb.

  • detailed boolean

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

  • time string

    Unit used to display time values.

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

Responses

GET /_cat/recovery/{index}
curl \
 --request GET http://api.example.com/_cat/recovery/{index}
Response examples (200)
[
  {
    "index": "string",
    "shard": "string",
    "": "string",
    "time": "string",
    "type": "string",
    "stage": "string",
    "source_host": "string",
    "source_node": "string",
    "target_host": "string",
    "target_node": "string",
    "repository": "string",
    "snapshot": "string",
    "files": "string",
    "files_recovered": "string",
    "files_total": "string",
    "bytes": "string",
    "bytes_recovered": "string",
    "bytes_total": "string",
    "translog_ops": "string",
    "translog_ops_recovered": "string"
  }
]

Get snapshot repository information Added in 2.1.0

GET /_cat/repositories

Get a list of snapshot repositories for a cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get snapshot repository API.

Query parameters

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

  • Period to wait for a connection to the master node.

Responses

GET /_cat/repositories
curl \
 --request GET http://api.example.com/_cat/repositories
Response examples (200)
[
  {
    "id": "string",
    "type": "string"
  }
]

Get segment information

GET /_cat/segments

Get low-level information about the Lucene segments in index shards. For data streams, the API returns information about the backing indices. 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 index segments API.

Query parameters

  • bytes string

    The unit used to display byte values.

    Values are b, kb, mb, gb, tb, or pb.

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

  • Period to wait for a connection to the master node.

Responses

  • Hide response attributes Show response attributes object
    • index string
    • shard string

      The shard name.

    • prirep string

      The shard type: primary or replica.

    • ip string

      The IP address of the node where it lives.

    • id string
    • segment string

      The segment name, which is derived from the segment generation and used internally to create file names in the directory of the shard.

    • The segment generation number. Elasticsearch increments this generation number for each segment written then uses this number to derive the segment name.

    • The number of documents in the segment. This excludes deleted documents and counts any nested documents separately from their parents. It also excludes documents which were indexed recently and do not yet belong to a segment.

    • The number of deleted documents in the segment, which might be higher or lower than the number of delete operations you have performed. This number excludes deletes that were performed recently and do not yet belong to a segment. Deleted documents are cleaned up by the automatic merge process if it makes sense to do so. Also, Elasticsearch creates extra deleted documents to internally track the recent history of operations on a shard.

    • If true, the segment is synced to disk. Segments that are synced can survive a hard reboot. If false, the data from uncommitted segments is also stored in the transaction log so that Elasticsearch is able to replay changes on the next start.

    • If true, the segment is searchable. If false, the segment has most likely been written to disk but needs a refresh to be searchable.

    • version string
    • compound string

      If true, the segment is stored in a compound file. This means Lucene merged all files from the segment in a single file to save file descriptors.

GET /_cat/segments
curl \
 --request GET http://api.example.com/_cat/segments
Response examples (200)
[
  {
    "index": "string",
    "shard": "string",
    "prirep": "string",
    "ip": "string",
    "id": "string",
    "segment": "string",
    "generation": "string",
    "docs.count": "string",
    "docs.deleted": "string",
    "": 42.0,
    "committed": "string",
    "searchable": "string",
    "version": "string",
    "compound": "string"
  }
]




















Get task information Technical preview

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.

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.

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

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

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

Responses

GET /_cat/tasks
curl \
 --request GET http://api.example.com/_cat/tasks
Response examples (200)
[
  {
    "id": "string",
    "action": "string",
    "task_id": "string",
    "parent_task_id": "string",
    "type": "string",
    "start_time": "string",
    "timestamp": "string",
    "running_time_ns": "string",
    "running_time": "string",
    "node_id": "string",
    "ip": "string",
    "port": "string",
    "node": "string",
    "version": "string",
    "x_opaque_id": "string",
    "description": "string"
  }
]








Get thread pool statistics

GET /_cat/thread_pool

Get thread pool statistics for each node in a cluster. Returned information includes all built-in thread pools and custom thread pools. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API.

Query parameters

  • time string

    The unit used to display time values.

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

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

  • Period to wait for a connection to the master node.

Responses

GET /_cat/thread_pool
curl \
 --request GET http://api.example.com/_cat/thread_pool
Response examples (200)
[
  {
    "node_name": "string",
    "node_id": "string",
    "ephemeral_node_id": "string",
    "pid": "string",
    "host": "string",
    "ip": "string",
    "port": "string",
    "name": "string",
    "type": "string",
    "active": "string",
    "pool_size": "string",
    "queue": "string",
    "queue_size": "string",
    "rejected": "string",
    "largest": "string",
    "completed": "string",
    "core": "string",
    "max": "string",
    "size": "string",
    "keep_alive": "string"
  }
]

Get thread pool statistics

GET /_cat/thread_pool/{thread_pool_patterns}

Get thread pool statistics for each node in a cluster. Returned information includes all built-in thread pools and custom thread pools. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API.

Path parameters

  • thread_pool_patterns string | array[string] Required

    A comma-separated list of thread pool names used to limit the request. Accepts wildcard expressions.

Query parameters

  • time string

    The unit used to display time values.

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

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

  • Period to wait for a connection to the master node.

Responses

GET /_cat/thread_pool/{thread_pool_patterns}
curl \
 --request GET http://api.example.com/_cat/thread_pool/{thread_pool_patterns}
Response examples (200)
[
  {
    "node_name": "string",
    "node_id": "string",
    "ephemeral_node_id": "string",
    "pid": "string",
    "host": "string",
    "ip": "string",
    "port": "string",
    "name": "string",
    "type": "string",
    "active": "string",
    "pool_size": "string",
    "queue": "string",
    "queue_size": "string",
    "rejected": "string",
    "largest": "string",
    "completed": "string",
    "core": "string",
    "max": "string",
    "size": "string",
    "keep_alive": "string"
  }
]




Get transform information Added in 7.7.0

GET /_cat/transforms/{transform_id}

Get configuration and usage information about transforms.

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

Path parameters

  • transform_id string Required

    A transform identifier or a wildcard expression. If you do not specify one of these options, the API returns information for all transforms.

Query parameters

  • Specifies what to do when the request: contains wildcard expressions and there are no transforms that match; contains the _all string or no identifiers and there are no matches; contains wildcard expressions and there are only partial matches. If true, it returns an empty transforms array when there are no matches and the subset of results when there are partial matches. If false, the request returns a 404 status code when there are no matches or only partial matches.

  • from number

    Skips the specified number of transforms.

  • h string | array[string]

    Comma-separated list of column names to display.

  • s string | array[string]

    Comma-separated list of column names or column aliases used to sort the response.

  • time string

    The unit used to display time values.

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

  • size number

    The maximum number of transforms to obtain.

Responses

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

      The status of the transform. Returned values include: aborting: The transform is aborting. failed: The transform failed. For more information about the failure, check thereasonfield. indexing: The transform is actively processing data and creating new documents. started: The transform is running but not actively indexing data. stopped: The transform is stopped. stopping`: The transform is stopping.

    • The sequence number for the checkpoint.

    • The number of documents that have been processed from the source index of the transform.

    • checkpoint_progress string | null

      The progress of the next checkpoint that is currently in progress.

    • last_search_time string | null

      The timestamp of the last search in the source indices. This field is shown only if the transform is running.

    • changes_last_detection_time string | null

      The timestamp when changes were last detected in the source indices.

    • The time the transform was created.

    • version string
    • The source indices for the transform.

    • The destination index for the transform.

    • pipeline string

      The unique identifier for the ingest pipeline.

    • The description of the transform.

    • The type of transform: batch or continuous.

    • The interval between checks for changes in the source indices when the transform is running continuously.

    • The initial page size that is used for the composite aggregation for each checkpoint.

    • The number of input documents per second.

    • reason string

      If a transform has a failed state, these details describe the reason for failure.

    • The total number of search operations on the source index for the transform.

    • The total number of search failures.

    • The total amount of search time, in milliseconds.

    • The total number of index operations done by the transform.

    • The total number of indexing failures.

    • The total time spent indexing documents, in milliseconds.

    • The number of documents that have been indexed into the destination index for the transform.

    • The total time spent deleting documents, in milliseconds.

    • The number of documents deleted from the destination index due to the retention policy for the transform.

    • The number of times the transform has been triggered by the scheduler. For example, the scheduler triggers the transform indexer to check for updates or ingest new data at an interval specified in the frequency property.

    • The number of search or bulk index operations processed. Documents are processed in batches instead of individually.

    • The total time spent processing results, in milliseconds.

    • The exponential moving average of the duration of the checkpoint, in milliseconds.

    • The exponential moving average of the number of new documents that have been indexed.

    • The exponential moving average of the number of documents that have been processed.

GET /_cat/transforms/{transform_id}
curl \
 --request GET http://api.example.com/_cat/transforms/{transform_id}
Response examples (200)
A successful response from `GET /_cat/transforms?v=true&format=json`.
[
  {
    "id" : "ecommerce_transform",
    "state" : "started",
    "checkpoint" : "1",
    "documents_processed" : "705",
    "checkpoint_progress" : "100.00",
    "changes_last_detection_time" : null
  }
]




Explain the shard allocations Added in 5.0.0

POST /_cluster/allocation/explain

Get explanations for shard allocations in the cluster. For unassigned shards, it provides an explanation for why the shard is unassigned. For assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node. This API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise.

Query parameters

application/json

Body

  • Specifies the node ID or the name of the node to only explain a shard that is currently located on the specified node.

  • index string
  • primary boolean

    If true, returns explanation for the primary shard for the given shard ID.

  • shard number

    Specifies the ID of the shard that you would like an explanation for.

Responses

POST /_cluster/allocation/explain
curl \
 --request POST http://api.example.com/_cluster/allocation/explain \
 --header "Content-Type: application/json" \
 --data '"{\n  \"index\": \"my-index-000001\",\n  \"shard\": 0,\n  \"primary\": false,\n  \"current_node\": \"my-node\"\n}"'
Request example
Run `GET _cluster/allocation/explain` to get an explanation for a shard's current allocation.
{
  "index": "my-index-000001",
  "shard": 0,
  "primary": false,
  "current_node": "my-node"
}
Response examples (200)
{
  "allocate_explanation": "string",
  "allocation_delay": "string",
  "": 42.0,
  "can_allocate": "yes",
  "can_move_to_other_node": "yes",
  "can_rebalance_cluster": "yes",
  "can_rebalance_cluster_decisions": [
    {
      "decider": "string",
      "decision": "NO",
      "explanation": "string"
    }
  ],
  "can_rebalance_to_other_node": "yes",
  "can_remain_decisions": [
    {
      "decider": "string",
      "decision": "NO",
      "explanation": "string"
    }
  ],
  "can_remain_on_current_node": "yes",
  "cluster_info": {
    "nodes": {
      "additionalProperty1": {
        "node_name": "string",
        "least_available": {
          "path": "string",
          "total_bytes": 42.0,
          "used_bytes": 42.0,
          "free_bytes": 42.0,
          "free_disk_percent": 42.0,
          "used_disk_percent": 42.0
        },
        "most_available": {
          "path": "string",
          "total_bytes": 42.0,
          "used_bytes": 42.0,
          "free_bytes": 42.0,
          "free_disk_percent": 42.0,
          "used_disk_percent": 42.0
        }
      },
      "additionalProperty2": {
        "node_name": "string",
        "least_available": {
          "path": "string",
          "total_bytes": 42.0,
          "used_bytes": 42.0,
          "free_bytes": 42.0,
          "free_disk_percent": 42.0,
          "used_disk_percent": 42.0
        },
        "most_available": {
          "path": "string",
          "total_bytes": 42.0,
          "used_bytes": 42.0,
          "free_bytes": 42.0,
          "free_disk_percent": 42.0,
          "used_disk_percent": 42.0
        }
      }
    },
    "shard_sizes": {
      "additionalProperty1": 42.0,
      "additionalProperty2": 42.0
    },
    "shard_data_set_sizes": {
      "additionalProperty1": "string",
      "additionalProperty2": "string"
    },
    "shard_paths": {
      "additionalProperty1": "string",
      "additionalProperty2": "string"
    },
    "reserved_sizes": [
      {
        "node_id": "string",
        "path": "string",
        "total": 42.0,
        "shards": [
          "string"
        ]
      }
    ]
  },
  "configured_delay": "string",
  "current_node": {
    "id": "string",
    "name": "string",
    "roles": [
      "master"
    ],
    "attributes": {
      "additionalProperty1": "string",
      "additionalProperty2": "string"
    },
    "transport_address": "string",
    "weight_ranking": 42.0
  },
  "current_state": "string",
  "index": "string",
  "move_explanation": "string",
  "node_allocation_decisions": [
    {
      "deciders": [
        {
          "decider": "string",
          "decision": "NO",
          "explanation": "string"
        }
      ],
      "node_attributes": {
        "additionalProperty1": "string",
        "additionalProperty2": "string"
      },
      "node_decision": "yes",
      "node_id": "string",
      "node_name": "string",
      "roles": [
        "master"
      ],
      "store": {
        "allocation_id": "string",
        "found": true,
        "in_sync": true,
        "matching_size_in_bytes": 42.0,
        "matching_sync_id": true,
        "store_exception": "string"
      },
      "transport_address": "string",
      "weight_ranking": 42.0
    }
  ],
  "primary": true,
  "rebalance_explanation": "string",
  "remaining_delay": "string",
  "shard": 42.0,
  "unassigned_info": {
    "": "string",
    "last_allocation_status": "string",
    "reason": "INDEX_CREATED",
    "details": "string",
    "failed_allocation_attempts": 42.0,
    "delayed": true,
    "allocation_status": "string"
  },
  "note": "string"
}
















Get the cluster health status Added in 1.3.0

GET /_cluster/health

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

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

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

Query parameters

  • expand_wildcards string | array[string]

    Whether to expand wildcard expression to concrete indices that are open, closed or both.

  • level string

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

    Values are cluster, indices, or shards.

  • local boolean

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

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

  • timeout string

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

  • wait_for_active_shards number | string

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

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

    Values are immediate, urgent, high, normal, low, or languid.

  • wait_for_nodes string | number

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

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

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

  • One of green, yellow or red. Will wait (until the timeout provided) until the status of the cluster changes to the one provided or better, i.e. green > yellow > red. By default, will not wait for any status.

    Values are green, GREEN, yellow, YELLOW, red, or RED.

Responses

GET /_cluster/health
curl \
 --request GET http://api.example.com/_cluster/health
Response examples (200)
A successful response from `GET _cluster/health`. It is the health status of a quiet single node cluster with a single index with one shard and one replica.
{
  "cluster_name" : "testcluster",
  "status" : "yellow",
  "timed_out" : false,
  "number_of_nodes" : 1,
  "number_of_data_nodes" : 1,
  "active_primary_shards" : 1,
  "active_shards" : 1,
  "relocating_shards" : 0,
  "initializing_shards" : 0,
  "unassigned_shards" : 1,
  "delayed_unassigned_shards": 0,
  "number_of_pending_tasks" : 0,
  "number_of_in_flight_fetch": 0,
  "task_max_waiting_in_queue_millis": 0,
  "active_shards_percent_as_number": 50.0
}








Get the pending cluster tasks

GET /_cluster/pending_tasks

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

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

Query parameters

  • local boolean

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

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

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • tasks array[object] Required
      Hide tasks attributes Show tasks attributes object
      • executing boolean Required

        Indicates whether the pending tasks are currently executing or not.

      • insert_order number Required

        The number that represents when the task has been inserted into the task queue.

      • priority string Required

        The priority of the pending task. The valid priorities in descending priority order are: IMMEDIATE > URGENT > HIGH > NORMAL > LOW > LANGUID.

      • source string Required

        A general description of the cluster task that may include a reason and origin.

      • 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

GET /_cluster/pending_tasks
curl \
 --request GET http://api.example.com/_cluster/pending_tasks
Response examples (200)
{
  "tasks": [
    {
      "executing": true,
      "insert_order": 42.0,
      "priority": "string",
      "source": "string",
      "time_in_queue": "string",
      "": 42.0
    }
  ]
}








Get the cluster state Added in 1.3.0

GET /_cluster/state

Get comprehensive information about the state of the cluster.

The cluster state is an internal data structure which keeps track of a variety of information needed by every node, including the identity and attributes of the other nodes in the cluster; cluster-wide settings; index metadata, including the mapping and settings for each index; the location and status of every shard copy in the cluster.

The elected master node ensures that every node in the cluster has a copy of the same cluster state. This API lets you retrieve a representation of this internal state for debugging or diagnostic purposes. You may need to consult the Elasticsearch source code to determine the precise meaning of the response.

By default the API will route requests to the elected master node since this node is the authoritative source of cluster states. You can also retrieve the cluster state held on the node handling the API request by adding the ?local=true query parameter.

Elasticsearch may need to expend significant effort to compute a response to this API in larger clusters, and the response may comprise a very large quantity of data. If you use this API repeatedly, your cluster may become unstable.

WARNING: The response is a representation of an internal data structure. Its format is not subject to the same compatibility guarantees as other more stable APIs and may change from version to version. Do not query this API using external monitoring tools. Instead, obtain the information you require using other more stable cluster APIs.

Query parameters

  • Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes _all string or when no indices have been specified)

  • expand_wildcards string | array[string]

    Whether to expand wildcard expression to concrete indices that are open, closed or both.

  • Return settings in flat format (default: false)

  • Whether specified concrete indices should be ignored when unavailable (missing or closed)

  • local boolean

    Return local information, do not retrieve the state from master node (default: false)

  • Specify timeout for connection to master

  • Wait for the metadata version to be equal or greater than the specified metadata version

  • The maximum time to wait for wait_for_metadata_version before timing out

Responses

  • 200 application/json

    Additional properties are allowed.

GET /_cluster/state
curl \
 --request GET http://api.example.com/_cluster/state
Response examples (200)
{}












Get cluster statistics Added in 1.3.0

GET /_cluster/stats/nodes/{node_id}

Get basic index metrics (shard numbers, store size, memory usage) and information about the current nodes that form the cluster (number, roles, os, jvm versions, memory usage, cpu and installed plugins).

Path parameters

  • node_id string | array[string] Required

    Comma-separated list of node filters used to limit returned information. Defaults to all nodes in the cluster.

Query parameters

  • Include remote cluster data into the response

  • timeout string

    Period to wait for each node to respond. If a node does not respond before its timeout expires, the response does not include its stats. However, timed out nodes are included in the response’s _nodes.failed property. Defaults to no timeout.

Responses

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

      Additional properties are allowed.

      Hide _nodes attributes Show _nodes attributes object
      • failures array[object]
        Hide failures attributes Show failures attributes object
        • type string Required

          The type of error

        • reason string

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

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

        • Additional properties are allowed.

        • root_cause array[object]

          Additional properties are allowed.

        • suppressed array[object]

          Additional properties are allowed.

      • total number Required

        Total number of nodes selected by the request.

      • successful number Required

        Number of nodes that responded successfully to the request.

      • failed number Required

        Number of nodes that rejected the request or failed to respond. If this value is not 0, a reason for the rejection or failure is included in the response.

    • cluster_name string Required
    • cluster_uuid string Required
    • indices object Required

      Additional properties are allowed.

      Hide indices attributes Show indices attributes object
    • nodes object Required

      Additional properties are allowed.

      Hide nodes attributes Show nodes attributes object
      • count object Required

        Additional properties are allowed.

        Hide count attributes Show count attributes object
      • discovery_types object Required

        Contains statistics about the discovery types used by selected nodes.

        Hide discovery_types attribute Show discovery_types attribute object
        • * number Additional properties
      • fs object Required

        Additional properties are allowed.

        Hide fs attributes Show fs attributes object
        • available_in_bytes number Required

          Total number of bytes available to JVM in file stores across all selected nodes. Depending on operating system or process-level restrictions, this number may be less than nodes.fs.free_in_byes. This is the actual amount of free disk space the selected Elasticsearch nodes can use.

        • free_in_bytes number Required

          Total number of unallocated bytes in file stores across all selected nodes.

        • total_in_bytes number Required

          Total size, in bytes, of all file stores across all selected nodes.

      • indexing_pressure object Required

        Additional properties are allowed.

        Hide indexing_pressure attribute Show indexing_pressure attribute object
      • ingest object Required

        Additional properties are allowed.

        Hide ingest attributes Show ingest attributes object
        • number_of_pipelines number Required
        • processor_stats object Required
          Hide processor_stats attribute Show processor_stats attribute object
          • * object Additional properties

            Additional properties are allowed.

            Hide * attributes Show * attributes object
            • count number Required
            • current number Required
            • failed number Required
            • 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.

      • jvm object Required

        Additional properties are allowed.

        Hide jvm attributes Show jvm attributes object
        • Time unit for milliseconds

        • mem object Required

          Additional properties are allowed.

          Hide mem attributes Show mem attributes object
          • heap_max_in_bytes number Required

            Maximum amount of memory, in bytes, available for use by the heap across all selected nodes.

          • heap_used_in_bytes number Required

            Memory, in bytes, currently in use by the heap across all selected nodes.

        • threads number Required

          Number of active threads in use by JVM across all selected nodes.

        • versions array[object] Required

          Contains statistics about the JVM versions used by selected nodes.

          Hide versions attributes Show versions attributes object
      • network_types object Required

        Additional properties are allowed.

        Hide network_types attributes Show network_types attributes object
        • http_types object Required

          Contains statistics about the HTTP network types used by selected nodes.

          Hide http_types attribute Show http_types attribute object
          • * number Additional properties
        • transport_types object Required

          Contains statistics about the transport network types used by selected nodes.

          Hide transport_types attribute Show transport_types attribute object
          • * number Additional properties
      • os object Required

        Additional properties are allowed.

        Hide os attributes Show os attributes object
        • allocated_processors number Required

          Number of processors used to calculate thread pool size across all selected nodes. This number can be set with the processors setting of a node and defaults to the number of processors reported by the operating system. In both cases, this number will never be larger than 32.

        • architectures array[object]

          Contains statistics about processor architectures (for example, x86_64 or aarch64) used by selected nodes.

          Hide architectures attributes Show architectures attributes object
          • arch string Required

            Name of an architecture used by one or more selected nodes.

          • count number Required

            Number of selected nodes using the architecture.

        • available_processors number Required

          Number of processors available to JVM across all selected nodes.

        • mem object Required

          Additional properties are allowed.

          Hide mem attributes Show mem attributes object
          • Total amount, in bytes, of memory across all selected nodes, but using the value specified using the es.total_memory_bytes system property instead of measured total memory for those nodes where that system property was set.

          • free_in_bytes number Required

            Amount, in bytes, of free physical memory across all selected nodes.

          • free_percent number Required

            Percentage of free physical memory across all selected nodes.

          • total_in_bytes number Required

            Total amount, in bytes, of physical memory across all selected nodes.

          • used_in_bytes number Required

            Amount, in bytes, of physical memory in use across all selected nodes.

          • used_percent number Required

            Percentage of physical memory in use across all selected nodes.

        • names array[object] Required

          Contains statistics about operating systems used by selected nodes.

          Hide names attributes Show names attributes object
          • count number Required

            Number of selected nodes using the operating system.

          • name string Required
        • pretty_names array[object] Required

          Contains statistics about operating systems used by selected nodes.

          Hide pretty_names attributes Show pretty_names attributes object
          • count number Required

            Number of selected nodes using the operating system.

          • pretty_name string Required
      • packaging_types array[object] Required

        Contains statistics about Elasticsearch distributions installed on selected nodes.

        Hide packaging_types attributes Show packaging_types attributes object
        • count number Required

          Number of selected nodes using the distribution flavor and file type.

        • flavor string Required

          Type of Elasticsearch distribution. This is always default.

        • type string Required

          File type (such as tar or zip) used for the distribution package.

      • plugins array[object] Required

        Contains statistics about installed plugins and modules by selected nodes. If no plugins or modules are installed, this array is empty.

        Hide plugins attributes Show plugins attributes object
      • process object Required

        Additional properties are allowed.

        Hide process attributes Show process attributes object
        • cpu object Required

          Additional properties are allowed.

          Hide cpu attribute Show cpu attribute object
          • percent number Required

            Percentage of CPU used across all selected nodes. Returns -1 if not supported.

        • open_file_descriptors object Required

          Additional properties are allowed.

          Hide open_file_descriptors attributes Show open_file_descriptors attributes object
          • avg number Required

            Average number of concurrently open file descriptors. Returns -1 if not supported.

          • max number Required

            Maximum number of concurrently open file descriptors allowed across all selected nodes. Returns -1 if not supported.

          • min number Required

            Minimum number of concurrently open file descriptors across all selected nodes. Returns -1 if not supported.

      • versions array[string] Required

        Array of Elasticsearch versions used on selected nodes.

    • status string Required

      Values are green, GREEN, yellow, YELLOW, red, or RED.

    • timestamp number Required

      Unix timestamp, in milliseconds, for the last time the cluster statistics were refreshed.

GET /_cluster/stats/nodes/{node_id}
curl \
 --request GET http://api.example.com/_cluster/stats/nodes/{node_id}
Response examples (200)
{
  "_nodes": {
    "failures": [
      {
        "type": "string",
        "reason": "string",
        "stack_trace": "string",
        "caused_by": {},
        "root_cause": [
          {}
        ],
        "suppressed": [
          {}
        ]
      }
    ],
    "total": 42.0,
    "successful": 42.0,
    "failed": 42.0
  },
  "cluster_name": "string",
  "cluster_uuid": "string",
  "indices": {
    "analysis": {
      "analyzer_types": [
        {
          "name": "string",
          "count": 42.0,
          "index_count": 42.0,
          "indexed_vector_count": 42.0,
          "indexed_vector_dim_max": 42.0,
          "indexed_vector_dim_min": 42.0,
          "script_count": 42.0
        }
      ],
      "built_in_analyzers": [
        {
          "name": "string",
          "count": 42.0,
          "index_count": 42.0,
          "indexed_vector_count": 42.0,
          "indexed_vector_dim_max": 42.0,
          "indexed_vector_dim_min": 42.0,
          "script_count": 42.0
        }
      ],
      "built_in_char_filters": [
        {
          "name": "string",
          "count": 42.0,
          "index_count": 42.0,
          "indexed_vector_count": 42.0,
          "indexed_vector_dim_max": 42.0,
          "indexed_vector_dim_min": 42.0,
          "script_count": 42.0
        }
      ],
      "built_in_filters": [
        {
          "name": "string",
          "count": 42.0,
          "index_count": 42.0,
          "indexed_vector_count": 42.0,
          "indexed_vector_dim_max": 42.0,
          "indexed_vector_dim_min": 42.0,
          "script_count": 42.0
        }
      ],
      "built_in_tokenizers": [
        {
          "name": "string",
          "count": 42.0,
          "index_count": 42.0,
          "indexed_vector_count": 42.0,
          "indexed_vector_dim_max": 42.0,
          "indexed_vector_dim_min": 42.0,
          "script_count": 42.0
        }
      ],
      "char_filter_types": [
        {
          "name": "string",
          "count": 42.0,
          "index_count": 42.0,
          "indexed_vector_count": 42.0,
          "indexed_vector_dim_max": 42.0,
          "indexed_vector_dim_min": 42.0,
          "script_count": 42.0
        }
      ],
      "filter_types": [
        {
          "name": "string",
          "count": 42.0,
          "index_count": 42.0,
          "indexed_vector_count": 42.0,
          "indexed_vector_dim_max": 42.0,
          "indexed_vector_dim_min": 42.0,
          "script_count": 42.0
        }
      ],
      "tokenizer_types": [
        {
          "name": "string",
          "count": 42.0,
          "index_count": 42.0,
          "indexed_vector_count": 42.0,
          "indexed_vector_dim_max": 42.0,
          "indexed_vector_dim_min": 42.0,
          "script_count": 42.0
        }
      ]
    },
    "completion": {
      "size_in_bytes": 42.0,
      "": 42.0,
      "fields": {
        "additionalProperty1": {
          "size_in_bytes": 42.0
        },
        "additionalProperty2": {
          "size_in_bytes": 42.0
        }
      }
    },
    "count": 42.0,
    "docs": {
      "count": 42.0,
      "deleted": 42.0
    },
    "fielddata": {
      "evictions": 42.0,
      "": 42.0,
      "memory_size_in_bytes": 42.0,
      "fields": {
        "additionalProperty1": {
          "memory_size_in_bytes": 42.0
        },
        "additionalProperty2": {
          "memory_size_in_bytes": 42.0
        }
      }
    },
    "query_cache": {
      "cache_count": 42.0,
      "cache_size": 42.0,
      "evictions": 42.0,
      "hit_count": 42.0,
      "": 42.0,
      "memory_size_in_bytes": 42.0,
      "miss_count": 42.0,
      "total_count": 42.0
    },
    "segments": {
      "count": 42.0,
      "": 42.0,
      "doc_values_memory_in_bytes": 42.0,
      "file_sizes": {
        "additionalProperty1": {
          "description": "string",
          "size_in_bytes": 42.0,
          "min_size_in_bytes": 42.0,
          "max_size_in_bytes": 42.0,
          "average_size_in_bytes": 42.0,
          "count": 42.0
        },
        "additionalProperty2": {
          "description": "string",
          "size_in_bytes": 42.0,
          "min_size_in_bytes": 42.0,
          "max_size_in_bytes": 42.0,
          "average_size_in_bytes": 42.0,
          "count": 42.0
        }
      },
      "fixed_bit_set_memory_in_bytes": 42.0,
      "index_writer_max_memory_in_bytes": 42.0,
      "index_writer_memory_in_bytes": 42.0,
      "max_unsafe_auto_id_timestamp": 42.0,
      "memory_in_bytes": 42.0,
      "norms_memory_in_bytes": 42.0,
      "points_memory_in_bytes": 42.0,
      "stored_fields_memory_in_bytes": 42.0,
      "terms_memory_in_bytes": 42.0,
      "term_vectors_memory_in_bytes": 42.0,
      "version_map_memory_in_bytes": 42.0
    },
    "shards": {
      "index": {
        "primaries": {
          "avg": 42.0,
          "max": 42.0,
          "min": 42.0
        },
        "replication": {
          "avg": 42.0,
          "max": 42.0,
          "min": 42.0
        },
        "shards": {
          "avg": 42.0,
          "max": 42.0,
          "min": 42.0
        }
      },
      "primaries": 42.0,
      "replication": 42.0,
      "total": 42.0
    },
    "store": {
      "": 42.0,
      "size_in_bytes": 42.0,
      "reserved_in_bytes": 42.0,
      "total_data_set_size_in_bytes": 42.0
    },
    "mappings": {
      "field_types": [
        {
          "name": "string",
          "count": 42.0,
          "index_count": 42.0,
          "indexed_vector_count": 42.0,
          "indexed_vector_dim_max": 42.0,
          "indexed_vector_dim_min": 42.0,
          "script_count": 42.0
        }
      ],
      "runtime_field_types": [
        {
          "chars_max": 42.0,
          "chars_total": 42.0,
          "count": 42.0,
          "doc_max": 42.0,
          "doc_total": 42.0,
          "index_count": 42.0,
          "lang": [
            "string"
          ],
          "lines_max": 42.0,
          "lines_total": 42.0,
          "name": "string",
          "scriptless_count": 42.0,
          "shadowed_count": 42.0,
          "source_max": 42.0,
          "source_total": 42.0
        }
      ],
      "total_field_count": 42.0,
      "total_deduplicated_field_count": 42.0,
      "": 42.0,
      "total_deduplicated_mapping_size_in_bytes": 42.0
    },
    "versions": [
      {
        "index_count": 42.0,
        "primary_shard_count": 42.0,
        "total_primary_bytes": 42.0,
        "version": "string"
      }
    ]
  },
  "nodes": {
    "count": {
      "coordinating_only": 42.0,
      "data": 42.0,
      "data_cold": 42.0,
      "data_content": 42.0,
      "data_frozen": 42.0,
      "data_hot": 42.0,
      "data_warm": 42.0,
      "ingest": 42.0,
      "master": 42.0,
      "ml": 42.0,
      "remote_cluster_client": 42.0,
      "total": 42.0,
      "transform": 42.0,
      "voting_only": 42.0
    },
    "discovery_types": {
      "additionalProperty1": 42.0,
      "additionalProperty2": 42.0
    },
    "fs": {
      "available_in_bytes": 42.0,
      "free_in_bytes": 42.0,
      "total_in_bytes": 42.0
    },
    "indexing_pressure": {
      "memory": {
        "current": {
          "all_in_bytes": 42.0,
          "combined_coordinating_and_primary_in_bytes": 42.0,
          "coordinating_in_bytes": 42.0,
          "coordinating_rejections": 42.0,
          "primary_in_bytes": 42.0,
          "primary_rejections": 42.0,
          "replica_in_bytes": 42.0,
          "replica_rejections": 42.0
        },
        "limit_in_bytes": 42.0,
        "total": {
          "all_in_bytes": 42.0,
          "combined_coordinating_and_primary_in_bytes": 42.0,
          "coordinating_in_bytes": 42.0,
          "coordinating_rejections": 42.0,
          "primary_in_bytes": 42.0,
          "primary_rejections": 42.0,
          "replica_in_bytes": 42.0,
          "replica_rejections": 42.0
        }
      }
    },
    "ingest": {
      "number_of_pipelines": 42.0,
      "processor_stats": {
        "additionalProperty1": {
          "count": 42.0,
          "current": 42.0,
          "failed": 42.0,
          "time": "string"
        },
        "additionalProperty2": {
          "count": 42.0,
          "current": 42.0,
          "failed": 42.0,
          "time": "string"
        }
      }
    },
    "jvm": {
      "": 42.0,
      "mem": {
        "heap_max_in_bytes": 42.0,
        "heap_used_in_bytes": 42.0
      },
      "threads": 42.0,
      "versions": [
        {
          "bundled_jdk": true,
          "count": 42.0,
          "using_bundled_jdk": true,
          "version": "string",
          "vm_name": "string",
          "vm_vendor": "string",
          "vm_version": "string"
        }
      ]
    },
    "network_types": {
      "http_types": {
        "additionalProperty1": 42.0,
        "additionalProperty2": 42.0
      },
      "transport_types": {
        "additionalProperty1": 42.0,
        "additionalProperty2": 42.0
      }
    },
    "os": {
      "allocated_processors": 42.0,
      "architectures": [
        {
          "arch": "string",
          "count": 42.0
        }
      ],
      "available_processors": 42.0,
      "mem": {
        "adjusted_total_in_bytes": 42.0,
        "free_in_bytes": 42.0,
        "free_percent": 42.0,
        "total_in_bytes": 42.0,
        "used_in_bytes": 42.0,
        "used_percent": 42.0
      },
      "names": [
        {
          "count": 42.0,
          "name": "string"
        }
      ],
      "pretty_names": [
        {
          "count": 42.0,
          "pretty_name": "string"
        }
      ]
    },
    "packaging_types": [
      {
        "count": 42.0,
        "flavor": "string",
        "type": "string"
      }
    ],
    "plugins": [
      {
        "classname": "string",
        "description": "string",
        "elasticsearch_version": "string",
        "extended_plugins": [
          "string"
        ],
        "has_native_controller": true,
        "java_version": "string",
        "name": "string",
        "version": "string",
        "licensed": true
      }
    ],
    "process": {
      "cpu": {
        "percent": 42.0
      },
      "open_file_descriptors": {
        "avg": 42.0,
        "max": 42.0,
        "min": 42.0
      }
    },
    "versions": [
      "string"
    ]
  },
  "status": "green",
  "timestamp": 42.0
}
















































Get node statistics

GET /_nodes/{node_id}/stats

Get statistics for nodes in a cluster. By default, all stats are returned. You can limit the returned information by using metrics.

Path parameters

  • node_id string | array[string] Required

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

Query parameters

  • completion_fields string | array[string]

    Comma-separated list or wildcard expressions of fields to include in fielddata and suggest statistics.

  • fielddata_fields string | array[string]

    Comma-separated list or wildcard expressions of fields to include in fielddata statistics.

  • fields string | array[string]

    Comma-separated list or wildcard expressions of fields to include in the statistics.

  • groups boolean

    Comma-separated list of search groups to include in the search statistics.

  • If true, the call reports the aggregated disk usage of each one of the Lucene index files (only applies if segment stats are requested).

  • level string

    Indicates whether statistics are aggregated at the cluster, index, or shard level.

    Values are cluster, indices, or shards.

  • timeout string

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

  • types array[string]

    A comma-separated list of document types for the indexing index metric.

  • If true, the response includes information from segments that are not loaded into memory.

Responses

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

      Additional properties are allowed.

      Hide _nodes attributes Show _nodes attributes object
      • failures array[object]
        Hide failures attributes Show failures attributes object
        • type string Required

          The type of error

        • reason string

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

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

        • Additional properties are allowed.

        • root_cause array[object]

          Additional properties are allowed.

        • suppressed array[object]

          Additional properties are allowed.

      • total number Required

        Total number of nodes selected by the request.

      • successful number Required

        Number of nodes that responded successfully to the request.

      • failed number Required

        Number of nodes that rejected the request or failed to respond. If this value is not 0, a reason for the rejection or failure is included in the response.

    • nodes object Required
      Hide nodes attribute Show nodes attribute object
      • * object Additional properties

        Additional properties are allowed.

        Hide * attributes Show * attributes object
        • Statistics about adaptive replica selection.

          Hide adaptive_selection attribute Show adaptive_selection attribute object
          • * object Additional properties

            Additional properties are allowed.

            Hide * attributes Show * attributes object
            • The exponentially weighted moving average queue size of search requests on the keyed node.

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

            • The exponentially weighted moving average response time, in nanoseconds, of search requests on the keyed node.

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

            • The exponentially weighted moving average service time, in nanoseconds, of search requests on the keyed node.

            • The number of outstanding search requests to the keyed node from the node these stats are for.

            • rank string

              The rank of this node; used for shard selection when routing search requests.

        • breakers object

          Statistics about the field data circuit breaker.

          Hide breakers attribute Show breakers attribute object
          • * object Additional properties

            Additional properties are allowed.

            Hide * attributes Show * attributes object
            • Estimated memory used for the operation.

            • Estimated memory used, in bytes, for the operation.

            • Memory limit for the circuit breaker.

            • Memory limit, in bytes, for the circuit breaker.

            • overhead number

              A constant that all estimates for the circuit breaker are multiplied with to calculate a final estimate.

            • tripped number

              Total number of times the circuit breaker has been triggered and prevented an out of memory error.

        • fs object

          Additional properties are allowed.

          Hide fs attributes Show fs attributes object
          • data array[object]

            List of all file stores.

            Additional properties are allowed.

          • Last time the file stores statistics were refreshed. Recorded in milliseconds since the Unix Epoch.

          • total object

            Additional properties are allowed.

            Hide total attributes Show total attributes object
            • Total disk space available to this Java virtual machine on all file stores. Depending on OS or process level restrictions, this might appear less than free. This is the actual amount of free disk space the Elasticsearch node can utilise.

            • Total number of bytes available to this Java virtual machine on all file stores. Depending on OS or process level restrictions, this might appear less than free_in_bytes. This is the actual amount of free disk space the Elasticsearch node can utilise.

            • free string

              Total unallocated disk space in all file stores.

            • Total number of unallocated bytes in all file stores.

            • total string

              Total size of all file stores.

            • Total size of all file stores in bytes.

          • io_stats object

            Additional properties are allowed.

            Hide io_stats attributes Show io_stats attributes object
            • devices array[object]

              Array of disk metrics for each device that is backing an Elasticsearch data path. These disk metrics are probed periodically and averages between the last probe and the current probe are computed.

            • total object

              Additional properties are allowed.

        • host string
        • http object

          Additional properties are allowed.

          Hide http attributes Show http attributes object
          • Current number of open HTTP connections for the node.

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

            Additional properties are allowed.

          • routes object Required Added in 8.12.0

            Detailed HTTP stats broken down by route

            Hide routes attribute Show routes attribute object
            • * object Additional properties

              Additional properties are allowed.

        • ingest object

          Additional properties are allowed.

          Hide ingest attributes Show ingest attributes object
          • Contains statistics about ingest pipelines for the node.

            Hide pipelines attribute Show pipelines attribute object
            • * object Additional properties

              Additional properties are allowed.

          • total object

            Additional properties are allowed.

            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.

        • ip string | array[string]

          IP address and port for the node.

        • jvm object

          Additional properties are allowed.

          Hide jvm attributes Show jvm attributes object
          • Contains statistics about JVM buffer pools for the node.

            Hide buffer_pools attribute Show buffer_pools attribute object
            • * object Additional properties

              Additional properties are allowed.

          • classes object

            Additional properties are allowed.

            Hide classes attributes Show classes attributes object
          • gc object

            Additional properties are allowed.

            Hide gc attribute Show gc attribute object
            • Contains statistics about JVM garbage collectors for the node.

          • mem object

            Additional properties are allowed.

            Hide mem attributes Show mem attributes object
          • threads object

            Additional properties are allowed.

            Hide threads attributes Show threads attributes object
            • count number

              Number of active threads in use by JVM.

            • Highest number of threads used by JVM.

          • Last time JVM statistics were refreshed.

          • uptime string

            Human-readable JVM uptime. Only returned if the human query parameter is true.

          • JVM uptime in milliseconds.

        • name string
        • os object

          Additional properties are allowed.

          Hide os attributes Show os attributes object
          • cpu object

            Additional properties are allowed.

            Hide cpu attributes Show cpu attributes object
            • percent number
            • sys string

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

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

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

          • mem object

            Additional properties are allowed.

          • swap object

            Additional properties are allowed.

            Hide swap attributes Show swap attributes object
          • cgroup object

            Additional properties are allowed.

            Hide cgroup attributes Show cgroup attributes object
            • cpuacct object

              Additional properties are allowed.

            • cpu object

              Additional properties are allowed.

            • memory object

              Additional properties are allowed.

        • process object

          Additional properties are allowed.

          Hide process attributes Show process attributes object
          • cpu object

            Additional properties are allowed.

            Hide cpu attributes Show cpu attributes object
            • percent number
            • sys string

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

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

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

          • mem object

            Additional properties are allowed.

            Hide mem attributes Show mem attributes object
          • Number of opened file descriptors associated with the current or -1 if not supported.

          • Maximum number of file descriptors allowed on the system, or -1 if not supported.

          • Last time the statistics were refreshed. Recorded in milliseconds since the Unix Epoch.

        • roles array[string]
          • @doc_id node-roles

          Values are master, data, data_cold, data_content, data_frozen, data_hot, data_warm, client, ingest, ml, voting_only, transform, remote_cluster_client, or coordinating_only.

        • script object

          Additional properties are allowed.

          Hide script attributes Show script attributes object
          • Total number of times the script cache has evicted old data.

          • Total number of inline script compilations performed by the node.

          • Contains this recent history of script compilations.

            Hide compilations_history attribute Show compilations_history attribute object
            • * number Additional properties
          • Total number of times the script compilation circuit breaker has limited inline script compilations.

          • contexts array[object]

            Additional properties are allowed.

        • Statistics about each thread pool, including current size, queue and rejected tasks.

          Hide thread_pool attribute Show thread_pool attribute object
          • * object Additional properties

            Additional properties are allowed.

            Hide * attributes Show * attributes object
            • active number

              Number of active threads in the thread pool.

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

        • Additional properties are allowed.

          Hide transport attributes Show transport attributes object
          • The distribution of the time spent handling each inbound message on a transport thread, represented as a histogram.

            Additional properties are allowed.

          • The distribution of the time spent sending each outbound transport message on a transport thread, represented as a histogram.

            Additional properties are allowed.

          • rx_count number

            Total number of RX (receive) packets received by the node during internal cluster communication.

          • rx_size string

            Size of RX packets received by the node during internal cluster communication.

          • Size, in bytes, of RX packets received by the node during internal cluster communication.

          • Current number of inbound TCP connections used for internal communication between nodes.

          • tx_count number

            Total number of TX (transmit) packets sent by the node during internal cluster communication.

          • tx_size string

            Size of TX packets sent by the node during internal cluster communication.

          • Size, in bytes, of TX packets sent by the node during internal cluster communication.

          • The cumulative number of outbound transport connections that this node has opened since it started. Each transport connection may comprise multiple TCP connections but is only counted once in this statistic. Transport connections are typically long-lived so this statistic should remain constant in a stable cluster.

        • Contains a list of attributes for the node.

          Hide attributes attribute Show attributes attribute object
          • * string Additional properties
        • Additional properties are allowed.

          Hide discovery attributes Show discovery attributes object
          • Additional properties are allowed.

            Hide cluster_state_queue attributes Show cluster_state_queue attributes object
            • total number

              Total number of cluster states in queue.

            • pending number

              Number of pending cluster states in queue.

            • Number of committed cluster states in queue.

          • Additional properties are allowed.

            Hide published_cluster_states attributes Show published_cluster_states attributes object
          • Contains low-level statistics about how long various activities took during cluster state updates while the node was the elected master. Omitted if the node is not master-eligible. Every field whose name ends in _time within this object is also represented as a raw number of milliseconds in a field whose name ends in _time_millis. The human-readable fields with a _time suffix are only returned if requested with the ?human=true query parameter.

            Hide cluster_state_update attribute Show cluster_state_update attribute object
            • * object Additional properties

              Additional properties are allowed.

          • Additional properties are allowed.

            Hide serialized_cluster_states attributes Show serialized_cluster_states attributes object
            • Additional properties are allowed.

            • diffs object

              Additional properties are allowed.

          • Additional properties are allowed.

            Hide cluster_applier_stats attribute Show cluster_applier_stats attribute object
        • Additional properties are allowed.

          Hide indexing_pressure attribute Show indexing_pressure attribute object
          • memory object

            Additional properties are allowed.

            Hide memory attributes Show memory attributes object
            • Configured memory limit, in bytes, for the indexing requests. Replica requests have an automatic limit that is 1.5x this value.

            • current object

              Additional properties are allowed.

            • total object

              Additional properties are allowed.

        • indices object

          Additional properties are allowed.

          Hide indices attributes Show indices attributes object
GET /_nodes/{node_id}/stats
curl \
 --request GET http://api.example.com/_nodes/{node_id}/stats
Response examples (200)
{
  "_nodes": {
    "failures": [
      {
        "type": "string",
        "reason": "string",
        "stack_trace": "string",
        "caused_by": {},
        "root_cause": [
          {}
        ],
        "suppressed": [
          {}
        ]
      }
    ],
    "total": 42.0,
    "successful": 42.0,
    "failed": 42.0
  },
  "cluster_name": "string",
  "nodes": {
    "additionalProperty1": {
      "adaptive_selection": {
        "additionalProperty1": {
          "avg_queue_size": 42.0,
          "avg_response_time": "string",
          "avg_response_time_ns": 42.0,
          "avg_service_time": "string",
          "avg_service_time_ns": 42.0,
          "outgoing_searches": 42.0,
          "rank": "string"
        },
        "additionalProperty2": {
          "avg_queue_size": 42.0,
          "avg_response_time": "string",
          "avg_response_time_ns": 42.0,
          "avg_service_time": "string",
          "avg_service_time_ns": 42.0,
          "outgoing_searches": 42.0,
          "rank": "string"
        }
      },
      "breakers": {
        "additionalProperty1": {
          "estimated_size": "string",
          "estimated_size_in_bytes": 42.0,
          "limit_size": "string",
          "limit_size_in_bytes": 42.0,
          "overhead": 42.0,
          "tripped": 42.0
        },
        "additionalProperty2": {
          "estimated_size": "string",
          "estimated_size_in_bytes": 42.0,
          "limit_size": "string",
          "limit_size_in_bytes": 42.0,
          "overhead": 42.0,
          "tripped": 42.0
        }
      },
      "fs": {
        "data": [
          {}
        ],
        "timestamp": 42.0,
        "total": {
          "available": "string",
          "available_in_bytes": 42.0,
          "free": "string",
          "free_in_bytes": 42.0,
          "total": "string",
          "total_in_bytes": 42.0
        },
        "io_stats": {
          "devices": [
            {}
          ],
          "total": {}
        }
      },
      "host": "string",
      "http": {
        "current_open": 42.0,
        "total_opened": 42.0,
        "clients": [
          {}
        ],
        "routes": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        }
      },
      "ingest": {
        "pipelines": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "total": {
          "count": 42.0,
          "current": 42.0,
          "failed": 42.0
        }
      },
      "ip": "string",
      "jvm": {
        "buffer_pools": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "classes": {
          "current_loaded_count": 42.0,
          "total_loaded_count": 42.0,
          "total_unloaded_count": 42.0
        },
        "gc": {
          "collectors": {}
        },
        "mem": {
          "heap_used_in_bytes": 42.0,
          "heap_used_percent": 42.0,
          "heap_committed_in_bytes": 42.0,
          "heap_max_in_bytes": 42.0,
          "non_heap_used_in_bytes": 42.0,
          "non_heap_committed_in_bytes": 42.0,
          "pools": {}
        },
        "threads": {
          "count": 42.0,
          "peak_count": 42.0
        },
        "timestamp": 42.0,
        "uptime": "string",
        "uptime_in_millis": 42.0
      },
      "name": "string",
      "os": {
        "cpu": {
          "percent": 42.0,
          "sys": "string",
          "total": "string",
          "user": "string",
          "load_average": {}
        },
        "": {},
        "swap": {
          "adjusted_total_in_bytes": 42.0,
          "resident": "string",
          "resident_in_bytes": 42.0,
          "share": "string",
          "share_in_bytes": 42.0,
          "total_virtual": "string",
          "total_virtual_in_bytes": 42.0,
          "total_in_bytes": 42.0,
          "free_in_bytes": 42.0,
          "used_in_bytes": 42.0
        },
        "cgroup": {
          "cpuacct": {},
          "cpu": {},
          "memory": {}
        },
        "timestamp": 42.0
      },
      "process": {
        "cpu": {
          "percent": 42.0,
          "sys": "string",
          "total": "string",
          "user": "string",
          "load_average": {}
        },
        "mem": {
          "adjusted_total_in_bytes": 42.0,
          "resident": "string",
          "resident_in_bytes": 42.0,
          "share": "string",
          "share_in_bytes": 42.0,
          "total_virtual": "string",
          "total_virtual_in_bytes": 42.0,
          "total_in_bytes": 42.0,
          "free_in_bytes": 42.0,
          "used_in_bytes": 42.0
        },
        "open_file_descriptors": 42.0,
        "max_file_descriptors": 42.0,
        "timestamp": 42.0
      },
      "roles": [
        "master"
      ],
      "script": {
        "cache_evictions": 42.0,
        "compilations": 42.0,
        "compilations_history": {
          "additionalProperty1": 42.0,
          "additionalProperty2": 42.0
        },
        "compilation_limit_triggered": 42.0,
        "contexts": [
          {}
        ]
      },
      "script_cache": {},
      "thread_pool": {
        "additionalProperty1": {
          "active": 42.0,
          "completed": 42.0,
          "largest": 42.0,
          "queue": 42.0,
          "rejected": 42.0,
          "threads": 42.0
        },
        "additionalProperty2": {
          "active": 42.0,
          "completed": 42.0,
          "largest": 42.0,
          "queue": 42.0,
          "rejected": 42.0,
          "threads": 42.0
        }
      },
      "timestamp": 42.0,
      "transport": {
        "inbound_handling_time_histogram": [
          {}
        ],
        "outbound_handling_time_histogram": [
          {}
        ],
        "rx_count": 42.0,
        "rx_size": "string",
        "rx_size_in_bytes": 42.0,
        "server_open": 42.0,
        "tx_count": 42.0,
        "tx_size": "string",
        "tx_size_in_bytes": 42.0,
        "total_outbound_connections": 42.0
      },
      "transport_address": "string",
      "attributes": {
        "additionalProperty1": "string",
        "additionalProperty2": "string"
      },
      "discovery": {
        "cluster_state_queue": {
          "total": 42.0,
          "pending": 42.0,
          "committed": 42.0
        },
        "published_cluster_states": {
          "full_states": 42.0,
          "incompatible_diffs": 42.0,
          "compatible_diffs": 42.0
        },
        "cluster_state_update": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "serialized_cluster_states": {
          "full_states": {},
          "diffs": {}
        },
        "cluster_applier_stats": {
          "recordings": [
            {}
          ]
        }
      },
      "indexing_pressure": {
        "memory": {
          "limit_in_bytes": 42.0,
          "current": {},
          "total": {}
        }
      },
      "indices": {
        "commit": {
          "generation": 42.0,
          "id": "string",
          "num_docs": 42.0,
          "user_data": {}
        },
        "completion": {
          "size_in_bytes": 42.0,
          "fields": {}
        },
        "docs": {
          "count": 42.0,
          "deleted": 42.0
        },
        "fielddata": {
          "evictions": 42.0,
          "memory_size_in_bytes": 42.0,
          "fields": {}
        },
        "flush": {
          "periodic": 42.0,
          "total": 42.0,
          "total_time": "string"
        },
        "get": {
          "current": 42.0,
          "exists_time": "string",
          "exists_total": 42.0,
          "missing_time": "string",
          "missing_total": 42.0,
          "time": "string",
          "total": 42.0
        },
        "indexing": {
          "index_current": 42.0,
          "delete_current": 42.0,
          "delete_time": "string",
          "delete_total": 42.0,
          "is_throttled": true,
          "noop_update_total": 42.0,
          "throttle_time": "string",
          "index_time": "string",
          "index_total": 42.0,
          "index_failed": 42.0,
          "types": {},
          "write_load": 42.0
        },
        "mappings": {
          "total_count": 42.0,
          "total_estimated_overhead_in_bytes": 42.0
        },
        "merges": {
          "current": 42.0,
          "current_docs": 42.0,
          "current_size": "string",
          "current_size_in_bytes": 42.0,
          "total": 42.0,
          "total_auto_throttle": "string",
          "total_auto_throttle_in_bytes": 42.0,
          "total_docs": 42.0,
          "total_size": "string",
          "total_size_in_bytes": 42.0,
          "total_stopped_time": "string",
          "total_throttled_time": "string",
          "total_time": "string"
        },
        "shard_path": {
          "data_path": "string",
          "is_custom_data_path": true,
          "state_path": "string"
        },
        "query_cache": {
          "cache_count": 42.0,
          "cache_size": 42.0,
          "evictions": 42.0,
          "hit_count": 42.0,
          "memory_size_in_bytes": 42.0,
          "miss_count": 42.0,
          "total_count": 42.0
        },
        "recovery": {
          "current_as_source": 42.0,
          "current_as_target": 42.0,
          "throttle_time": "string"
        },
        "refresh": {
          "external_total": 42.0,
          "listeners": 42.0,
          "total": 42.0,
          "total_time": "string"
        },
        "request_cache": {
          "evictions": 42.0,
          "hit_count": 42.0,
          "memory_size": "string",
          "memory_size_in_bytes": 42.0,
          "miss_count": 42.0
        },
        "retention_leases": {
          "primary_term": 42.0,
          "version": 42.0,
          "leases": [
            {}
          ]
        },
        "routing": {
          "node": "string",
          "primary": true,
          "state": "UNASSIGNED"
        },
        "search": {
          "fetch_current": 42.0,
          "fetch_time": "string",
          "fetch_total": 42.0,
          "open_contexts": 42.0,
          "query_current": 42.0,
          "query_time": "string",
          "query_total": 42.0,
          "scroll_current": 42.0,
          "scroll_time": "string",
          "scroll_total": 42.0,
          "suggest_current": 42.0,
          "suggest_time": "string",
          "suggest_total": 42.0,
          "groups": {}
        },
        "segments": {
          "count": 42.0,
          "doc_values_memory_in_bytes": 42.0,
          "file_sizes": {},
          "fixed_bit_set_memory_in_bytes": 42.0,
          "index_writer_max_memory_in_bytes": 42.0,
          "index_writer_memory_in_bytes": 42.0,
          "max_unsafe_auto_id_timestamp": 42.0,
          "memory_in_bytes": 42.0,
          "norms_memory_in_bytes": 42.0,
          "points_memory_in_bytes": 42.0,
          "stored_fields_memory_in_bytes": 42.0,
          "terms_memory_in_bytes": 42.0,
          "term_vectors_memory_in_bytes": 42.0,
          "version_map_memory_in_bytes": 42.0
        },
        "seq_no": {
          "global_checkpoint": 42.0,
          "local_checkpoint": 42.0,
          "max_seq_no": 42.0
        },
        "store": {
          "size_in_bytes": 42.0,
          "reserved_in_bytes": 42.0,
          "total_data_set_size_in_bytes": 42.0
        },
        "translog": {
          "earliest_last_modified_age": 42.0,
          "operations": 42.0,
          "size": "string",
          "size_in_bytes": 42.0,
          "uncommitted_operations": 42.0,
          "uncommitted_size": "string",
          "uncommitted_size_in_bytes": 42.0
        },
        "warmer": {
          "current": 42.0,
          "total": 42.0,
          "total_time": "string"
        },
        "bulk": {
          "total_operations": 42.0,
          "total_time": "string",
          "total_size_in_bytes": 42.0,
          "avg_time": "string",
          "avg_size_in_bytes": 42.0
        },
        "shards": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "shard_stats": {
          "total_count": 42.0
        },
        "additionalProperty1": {
          "primaries": {},
          "shards": {},
          "total": {},
          "uuid": "string",
          "health": "green",
          "status": "open"
        },
        "additionalProperty2": {
          "primaries": {},
          "shards": {},
          "total": {},
          "uuid": "string",
          "health": "green",
          "status": "open"
        }
      }
    },
    "additionalProperty2": {
      "adaptive_selection": {
        "additionalProperty1": {
          "avg_queue_size": 42.0,
          "avg_response_time": "string",
          "avg_response_time_ns": 42.0,
          "avg_service_time": "string",
          "avg_service_time_ns": 42.0,
          "outgoing_searches": 42.0,
          "rank": "string"
        },
        "additionalProperty2": {
          "avg_queue_size": 42.0,
          "avg_response_time": "string",
          "avg_response_time_ns": 42.0,
          "avg_service_time": "string",
          "avg_service_time_ns": 42.0,
          "outgoing_searches": 42.0,
          "rank": "string"
        }
      },
      "breakers": {
        "additionalProperty1": {
          "estimated_size": "string",
          "estimated_size_in_bytes": 42.0,
          "limit_size": "string",
          "limit_size_in_bytes": 42.0,
          "overhead": 42.0,
          "tripped": 42.0
        },
        "additionalProperty2": {
          "estimated_size": "string",
          "estimated_size_in_bytes": 42.0,
          "limit_size": "string",
          "limit_size_in_bytes": 42.0,
          "overhead": 42.0,
          "tripped": 42.0
        }
      },
      "fs": {
        "data": [
          {}
        ],
        "timestamp": 42.0,
        "total": {
          "available": "string",
          "available_in_bytes": 42.0,
          "free": "string",
          "free_in_bytes": 42.0,
          "total": "string",
          "total_in_bytes": 42.0
        },
        "io_stats": {
          "devices": [
            {}
          ],
          "total": {}
        }
      },
      "host": "string",
      "http": {
        "current_open": 42.0,
        "total_opened": 42.0,
        "clients": [
          {}
        ],
        "routes": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        }
      },
      "ingest": {
        "pipelines": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "total": {
          "count": 42.0,
          "current": 42.0,
          "failed": 42.0
        }
      },
      "ip": "string",
      "jvm": {
        "buffer_pools": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "classes": {
          "current_loaded_count": 42.0,
          "total_loaded_count": 42.0,
          "total_unloaded_count": 42.0
        },
        "gc": {
          "collectors": {}
        },
        "mem": {
          "heap_used_in_bytes": 42.0,
          "heap_used_percent": 42.0,
          "heap_committed_in_bytes": 42.0,
          "heap_max_in_bytes": 42.0,
          "non_heap_used_in_bytes": 42.0,
          "non_heap_committed_in_bytes": 42.0,
          "pools": {}
        },
        "threads": {
          "count": 42.0,
          "peak_count": 42.0
        },
        "timestamp": 42.0,
        "uptime": "string",
        "uptime_in_millis": 42.0
      },
      "name": "string",
      "os": {
        "cpu": {
          "percent": 42.0,
          "sys": "string",
          "total": "string",
          "user": "string",
          "load_average": {}
        },
        "": {},
        "swap": {
          "adjusted_total_in_bytes": 42.0,
          "resident": "string",
          "resident_in_bytes": 42.0,
          "share": "string",
          "share_in_bytes": 42.0,
          "total_virtual": "string",
          "total_virtual_in_bytes": 42.0,
          "total_in_bytes": 42.0,
          "free_in_bytes": 42.0,
          "used_in_bytes": 42.0
        },
        "cgroup": {
          "cpuacct": {},
          "cpu": {},
          "memory": {}
        },
        "timestamp": 42.0
      },
      "process": {
        "cpu": {
          "percent": 42.0,
          "sys": "string",
          "total": "string",
          "user": "string",
          "load_average": {}
        },
        "mem": {
          "adjusted_total_in_bytes": 42.0,
          "resident": "string",
          "resident_in_bytes": 42.0,
          "share": "string",
          "share_in_bytes": 42.0,
          "total_virtual": "string",
          "total_virtual_in_bytes": 42.0,
          "total_in_bytes": 42.0,
          "free_in_bytes": 42.0,
          "used_in_bytes": 42.0
        },
        "open_file_descriptors": 42.0,
        "max_file_descriptors": 42.0,
        "timestamp": 42.0
      },
      "roles": [
        "master"
      ],
      "script": {
        "cache_evictions": 42.0,
        "compilations": 42.0,
        "compilations_history": {
          "additionalProperty1": 42.0,
          "additionalProperty2": 42.0
        },
        "compilation_limit_triggered": 42.0,
        "contexts": [
          {}
        ]
      },
      "script_cache": {},
      "thread_pool": {
        "additionalProperty1": {
          "active": 42.0,
          "completed": 42.0,
          "largest": 42.0,
          "queue": 42.0,
          "rejected": 42.0,
          "threads": 42.0
        },
        "additionalProperty2": {
          "active": 42.0,
          "completed": 42.0,
          "largest": 42.0,
          "queue": 42.0,
          "rejected": 42.0,
          "threads": 42.0
        }
      },
      "timestamp": 42.0,
      "transport": {
        "inbound_handling_time_histogram": [
          {}
        ],
        "outbound_handling_time_histogram": [
          {}
        ],
        "rx_count": 42.0,
        "rx_size": "string",
        "rx_size_in_bytes": 42.0,
        "server_open": 42.0,
        "tx_count": 42.0,
        "tx_size": "string",
        "tx_size_in_bytes": 42.0,
        "total_outbound_connections": 42.0
      },
      "transport_address": "string",
      "attributes": {
        "additionalProperty1": "string",
        "additionalProperty2": "string"
      },
      "discovery": {
        "cluster_state_queue": {
          "total": 42.0,
          "pending": 42.0,
          "committed": 42.0
        },
        "published_cluster_states": {
          "full_states": 42.0,
          "incompatible_diffs": 42.0,
          "compatible_diffs": 42.0
        },
        "cluster_state_update": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "serialized_cluster_states": {
          "full_states": {},
          "diffs": {}
        },
        "cluster_applier_stats": {
          "recordings": [
            {}
          ]
        }
      },
      "indexing_pressure": {
        "memory": {
          "limit_in_bytes": 42.0,
          "current": {},
          "total": {}
        }
      },
      "indices": {
        "commit": {
          "generation": 42.0,
          "id": "string",
          "num_docs": 42.0,
          "user_data": {}
        },
        "completion": {
          "size_in_bytes": 42.0,
          "fields": {}
        },
        "docs": {
          "count": 42.0,
          "deleted": 42.0
        },
        "fielddata": {
          "evictions": 42.0,
          "memory_size_in_bytes": 42.0,
          "fields": {}
        },
        "flush": {
          "periodic": 42.0,
          "total": 42.0,
          "total_time": "string"
        },
        "get": {
          "current": 42.0,
          "exists_time": "string",
          "exists_total": 42.0,
          "missing_time": "string",
          "missing_total": 42.0,
          "time": "string",
          "total": 42.0
        },
        "indexing": {
          "index_current": 42.0,
          "delete_current": 42.0,
          "delete_time": "string",
          "delete_total": 42.0,
          "is_throttled": true,
          "noop_update_total": 42.0,
          "throttle_time": "string",
          "index_time": "string",
          "index_total": 42.0,
          "index_failed": 42.0,
          "types": {},
          "write_load": 42.0
        },
        "mappings": {
          "total_count": 42.0,
          "total_estimated_overhead_in_bytes": 42.0
        },
        "merges": {
          "current": 42.0,
          "current_docs": 42.0,
          "current_size": "string",
          "current_size_in_bytes": 42.0,
          "total": 42.0,
          "total_auto_throttle": "string",
          "total_auto_throttle_in_bytes": 42.0,
          "total_docs": 42.0,
          "total_size": "string",
          "total_size_in_bytes": 42.0,
          "total_stopped_time": "string",
          "total_throttled_time": "string",
          "total_time": "string"
        },
        "shard_path": {
          "data_path": "string",
          "is_custom_data_path": true,
          "state_path": "string"
        },
        "query_cache": {
          "cache_count": 42.0,
          "cache_size": 42.0,
          "evictions": 42.0,
          "hit_count": 42.0,
          "memory_size_in_bytes": 42.0,
          "miss_count": 42.0,
          "total_count": 42.0
        },
        "recovery": {
          "current_as_source": 42.0,
          "current_as_target": 42.0,
          "throttle_time": "string"
        },
        "refresh": {
          "external_total": 42.0,
          "listeners": 42.0,
          "total": 42.0,
          "total_time": "string"
        },
        "request_cache": {
          "evictions": 42.0,
          "hit_count": 42.0,
          "memory_size": "string",
          "memory_size_in_bytes": 42.0,
          "miss_count": 42.0
        },
        "retention_leases": {
          "primary_term": 42.0,
          "version": 42.0,
          "leases": [
            {}
          ]
        },
        "routing": {
          "node": "string",
          "primary": true,
          "state": "UNASSIGNED"
        },
        "search": {
          "fetch_current": 42.0,
          "fetch_time": "string",
          "fetch_total": 42.0,
          "open_contexts": 42.0,
          "query_current": 42.0,
          "query_time": "string",
          "query_total": 42.0,
          "scroll_current": 42.0,
          "scroll_time": "string",
          "scroll_total": 42.0,
          "suggest_current": 42.0,
          "suggest_time": "string",
          "suggest_total": 42.0,
          "groups": {}
        },
        "segments": {
          "count": 42.0,
          "doc_values_memory_in_bytes": 42.0,
          "file_sizes": {},
          "fixed_bit_set_memory_in_bytes": 42.0,
          "index_writer_max_memory_in_bytes": 42.0,
          "index_writer_memory_in_bytes": 42.0,
          "max_unsafe_auto_id_timestamp": 42.0,
          "memory_in_bytes": 42.0,
          "norms_memory_in_bytes": 42.0,
          "points_memory_in_bytes": 42.0,
          "stored_fields_memory_in_bytes": 42.0,
          "terms_memory_in_bytes": 42.0,
          "term_vectors_memory_in_bytes": 42.0,
          "version_map_memory_in_bytes": 42.0
        },
        "seq_no": {
          "global_checkpoint": 42.0,
          "local_checkpoint": 42.0,
          "max_seq_no": 42.0
        },
        "store": {
          "size_in_bytes": 42.0,
          "reserved_in_bytes": 42.0,
          "total_data_set_size_in_bytes": 42.0
        },
        "translog": {
          "earliest_last_modified_age": 42.0,
          "operations": 42.0,
          "size": "string",
          "size_in_bytes": 42.0,
          "uncommitted_operations": 42.0,
          "uncommitted_size": "string",
          "uncommitted_size_in_bytes": 42.0
        },
        "warmer": {
          "current": 42.0,
          "total": 42.0,
          "total_time": "string"
        },
        "bulk": {
          "total_operations": 42.0,
          "total_time": "string",
          "total_size_in_bytes": 42.0,
          "avg_time": "string",
          "avg_size_in_bytes": 42.0
        },
        "shards": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "shard_stats": {
          "total_count": 42.0
        },
        "additionalProperty1": {
          "primaries": {},
          "shards": {},
          "total": {},
          "uuid": "string",
          "health": "green",
          "status": "open"
        },
        "additionalProperty2": {
          "primaries": {},
          "shards": {},
          "total": {},
          "uuid": "string",
          "health": "green",
          "status": "open"
        }
      }
    }
  }
}

Get node statistics

GET /_nodes/stats/{metric}

Get statistics for nodes in a cluster. By default, all stats are returned. You can limit the returned information by using metrics.

Path parameters

  • metric string | array[string] Required

    Limit the information returned to the specified metrics

Query parameters

  • completion_fields string | array[string]

    Comma-separated list or wildcard expressions of fields to include in fielddata and suggest statistics.

  • fielddata_fields string | array[string]

    Comma-separated list or wildcard expressions of fields to include in fielddata statistics.

  • fields string | array[string]

    Comma-separated list or wildcard expressions of fields to include in the statistics.

  • groups boolean

    Comma-separated list of search groups to include in the search statistics.

  • If true, the call reports the aggregated disk usage of each one of the Lucene index files (only applies if segment stats are requested).

  • level string

    Indicates whether statistics are aggregated at the cluster, index, or shard level.

    Values are cluster, indices, or shards.

  • timeout string

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

  • types array[string]

    A comma-separated list of document types for the indexing index metric.

  • If true, the response includes information from segments that are not loaded into memory.

Responses

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

      Additional properties are allowed.

      Hide _nodes attributes Show _nodes attributes object
      • failures array[object]
        Hide failures attributes Show failures attributes object
        • type string Required

          The type of error

        • reason string

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

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

        • Additional properties are allowed.

        • root_cause array[object]

          Additional properties are allowed.

        • suppressed array[object]

          Additional properties are allowed.

      • total number Required

        Total number of nodes selected by the request.

      • successful number Required

        Number of nodes that responded successfully to the request.

      • failed number Required

        Number of nodes that rejected the request or failed to respond. If this value is not 0, a reason for the rejection or failure is included in the response.

    • nodes object Required
      Hide nodes attribute Show nodes attribute object
      • * object Additional properties

        Additional properties are allowed.

        Hide * attributes Show * attributes object
        • Statistics about adaptive replica selection.

          Hide adaptive_selection attribute Show adaptive_selection attribute object
          • * object Additional properties

            Additional properties are allowed.

            Hide * attributes Show * attributes object
            • The exponentially weighted moving average queue size of search requests on the keyed node.

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

            • The exponentially weighted moving average response time, in nanoseconds, of search requests on the keyed node.

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

            • The exponentially weighted moving average service time, in nanoseconds, of search requests on the keyed node.

            • The number of outstanding search requests to the keyed node from the node these stats are for.

            • rank string

              The rank of this node; used for shard selection when routing search requests.

        • breakers object

          Statistics about the field data circuit breaker.

          Hide breakers attribute Show breakers attribute object
          • * object Additional properties

            Additional properties are allowed.

            Hide * attributes Show * attributes object
            • Estimated memory used for the operation.

            • Estimated memory used, in bytes, for the operation.

            • Memory limit for the circuit breaker.

            • Memory limit, in bytes, for the circuit breaker.

            • overhead number

              A constant that all estimates for the circuit breaker are multiplied with to calculate a final estimate.

            • tripped number

              Total number of times the circuit breaker has been triggered and prevented an out of memory error.

        • fs object

          Additional properties are allowed.

          Hide fs attributes Show fs attributes object
          • data array[object]

            List of all file stores.

            Additional properties are allowed.

          • Last time the file stores statistics were refreshed. Recorded in milliseconds since the Unix Epoch.

          • total object

            Additional properties are allowed.

            Hide total attributes Show total attributes object
            • Total disk space available to this Java virtual machine on all file stores. Depending on OS or process level restrictions, this might appear less than free. This is the actual amount of free disk space the Elasticsearch node can utilise.

            • Total number of bytes available to this Java virtual machine on all file stores. Depending on OS or process level restrictions, this might appear less than free_in_bytes. This is the actual amount of free disk space the Elasticsearch node can utilise.

            • free string

              Total unallocated disk space in all file stores.

            • Total number of unallocated bytes in all file stores.

            • total string

              Total size of all file stores.

            • Total size of all file stores in bytes.

          • io_stats object

            Additional properties are allowed.

            Hide io_stats attributes Show io_stats attributes object
            • devices array[object]

              Array of disk metrics for each device that is backing an Elasticsearch data path. These disk metrics are probed periodically and averages between the last probe and the current probe are computed.

            • total object

              Additional properties are allowed.

        • host string
        • http object

          Additional properties are allowed.

          Hide http attributes Show http attributes object
          • Current number of open HTTP connections for the node.

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

            Additional properties are allowed.

          • routes object Required Added in 8.12.0

            Detailed HTTP stats broken down by route

            Hide routes attribute Show routes attribute object
            • * object Additional properties

              Additional properties are allowed.

        • ingest object

          Additional properties are allowed.

          Hide ingest attributes Show ingest attributes object
          • Contains statistics about ingest pipelines for the node.

            Hide pipelines attribute Show pipelines attribute object
            • * object Additional properties

              Additional properties are allowed.

          • total object

            Additional properties are allowed.

            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.

        • ip string | array[string]

          IP address and port for the node.

        • jvm object

          Additional properties are allowed.

          Hide jvm attributes Show jvm attributes object
          • Contains statistics about JVM buffer pools for the node.

            Hide buffer_pools attribute Show buffer_pools attribute object
            • * object Additional properties

              Additional properties are allowed.

          • classes object

            Additional properties are allowed.

            Hide classes attributes Show classes attributes object
          • gc object

            Additional properties are allowed.

            Hide gc attribute Show gc attribute object
            • Contains statistics about JVM garbage collectors for the node.

          • mem object

            Additional properties are allowed.

            Hide mem attributes Show mem attributes object
          • threads object

            Additional properties are allowed.

            Hide threads attributes Show threads attributes object
            • count number

              Number of active threads in use by JVM.

            • Highest number of threads used by JVM.

          • Last time JVM statistics were refreshed.

          • uptime string

            Human-readable JVM uptime. Only returned if the human query parameter is true.

          • JVM uptime in milliseconds.

        • name string
        • os object

          Additional properties are allowed.

          Hide os attributes Show os attributes object
          • cpu object

            Additional properties are allowed.

            Hide cpu attributes Show cpu attributes object
            • percent number
            • sys string

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

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

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

          • mem object

            Additional properties are allowed.

          • swap object

            Additional properties are allowed.

            Hide swap attributes Show swap attributes object
          • cgroup object

            Additional properties are allowed.

            Hide cgroup attributes Show cgroup attributes object
            • cpuacct object

              Additional properties are allowed.

            • cpu object

              Additional properties are allowed.

            • memory object

              Additional properties are allowed.

        • process object

          Additional properties are allowed.

          Hide process attributes Show process attributes object
          • cpu object

            Additional properties are allowed.

            Hide cpu attributes Show cpu attributes object
            • percent number
            • sys string

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

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

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

          • mem object

            Additional properties are allowed.

            Hide mem attributes Show mem attributes object
          • Number of opened file descriptors associated with the current or -1 if not supported.

          • Maximum number of file descriptors allowed on the system, or -1 if not supported.

          • Last time the statistics were refreshed. Recorded in milliseconds since the Unix Epoch.

        • roles array[string]
          • @doc_id node-roles

          Values are master, data, data_cold, data_content, data_frozen, data_hot, data_warm, client, ingest, ml, voting_only, transform, remote_cluster_client, or coordinating_only.

        • script object

          Additional properties are allowed.

          Hide script attributes Show script attributes object
          • Total number of times the script cache has evicted old data.

          • Total number of inline script compilations performed by the node.

          • Contains this recent history of script compilations.

            Hide compilations_history attribute Show compilations_history attribute object
            • * number Additional properties
          • Total number of times the script compilation circuit breaker has limited inline script compilations.

          • contexts array[object]

            Additional properties are allowed.

        • Statistics about each thread pool, including current size, queue and rejected tasks.

          Hide thread_pool attribute Show thread_pool attribute object
          • * object Additional properties

            Additional properties are allowed.

            Hide * attributes Show * attributes object
            • active number

              Number of active threads in the thread pool.

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

        • Additional properties are allowed.

          Hide transport attributes Show transport attributes object
          • The distribution of the time spent handling each inbound message on a transport thread, represented as a histogram.

            Additional properties are allowed.

          • The distribution of the time spent sending each outbound transport message on a transport thread, represented as a histogram.

            Additional properties are allowed.

          • rx_count number

            Total number of RX (receive) packets received by the node during internal cluster communication.

          • rx_size string

            Size of RX packets received by the node during internal cluster communication.

          • Size, in bytes, of RX packets received by the node during internal cluster communication.

          • Current number of inbound TCP connections used for internal communication between nodes.

          • tx_count number

            Total number of TX (transmit) packets sent by the node during internal cluster communication.

          • tx_size string

            Size of TX packets sent by the node during internal cluster communication.

          • Size, in bytes, of TX packets sent by the node during internal cluster communication.

          • The cumulative number of outbound transport connections that this node has opened since it started. Each transport connection may comprise multiple TCP connections but is only counted once in this statistic. Transport connections are typically long-lived so this statistic should remain constant in a stable cluster.

        • Contains a list of attributes for the node.

          Hide attributes attribute Show attributes attribute object
          • * string Additional properties
        • Additional properties are allowed.

          Hide discovery attributes Show discovery attributes object
          • Additional properties are allowed.

            Hide cluster_state_queue attributes Show cluster_state_queue attributes object
            • total number

              Total number of cluster states in queue.

            • pending number

              Number of pending cluster states in queue.

            • Number of committed cluster states in queue.

          • Additional properties are allowed.

            Hide published_cluster_states attributes Show published_cluster_states attributes object
          • Contains low-level statistics about how long various activities took during cluster state updates while the node was the elected master. Omitted if the node is not master-eligible. Every field whose name ends in _time within this object is also represented as a raw number of milliseconds in a field whose name ends in _time_millis. The human-readable fields with a _time suffix are only returned if requested with the ?human=true query parameter.

            Hide cluster_state_update attribute Show cluster_state_update attribute object
            • * object Additional properties

              Additional properties are allowed.

          • Additional properties are allowed.

            Hide serialized_cluster_states attributes Show serialized_cluster_states attributes object
            • Additional properties are allowed.

            • diffs object

              Additional properties are allowed.

          • Additional properties are allowed.

            Hide cluster_applier_stats attribute Show cluster_applier_stats attribute object
        • Additional properties are allowed.

          Hide indexing_pressure attribute Show indexing_pressure attribute object
          • memory object

            Additional properties are allowed.

            Hide memory attributes Show memory attributes object
            • Configured memory limit, in bytes, for the indexing requests. Replica requests have an automatic limit that is 1.5x this value.

            • current object

              Additional properties are allowed.

            • total object

              Additional properties are allowed.

        • indices object

          Additional properties are allowed.

          Hide indices attributes Show indices attributes object
GET /_nodes/stats/{metric}
curl \
 --request GET http://api.example.com/_nodes/stats/{metric}
Response examples (200)
{
  "_nodes": {
    "failures": [
      {
        "type": "string",
        "reason": "string",
        "stack_trace": "string",
        "caused_by": {},
        "root_cause": [
          {}
        ],
        "suppressed": [
          {}
        ]
      }
    ],
    "total": 42.0,
    "successful": 42.0,
    "failed": 42.0
  },
  "cluster_name": "string",
  "nodes": {
    "additionalProperty1": {
      "adaptive_selection": {
        "additionalProperty1": {
          "avg_queue_size": 42.0,
          "avg_response_time": "string",
          "avg_response_time_ns": 42.0,
          "avg_service_time": "string",
          "avg_service_time_ns": 42.0,
          "outgoing_searches": 42.0,
          "rank": "string"
        },
        "additionalProperty2": {
          "avg_queue_size": 42.0,
          "avg_response_time": "string",
          "avg_response_time_ns": 42.0,
          "avg_service_time": "string",
          "avg_service_time_ns": 42.0,
          "outgoing_searches": 42.0,
          "rank": "string"
        }
      },
      "breakers": {
        "additionalProperty1": {
          "estimated_size": "string",
          "estimated_size_in_bytes": 42.0,
          "limit_size": "string",
          "limit_size_in_bytes": 42.0,
          "overhead": 42.0,
          "tripped": 42.0
        },
        "additionalProperty2": {
          "estimated_size": "string",
          "estimated_size_in_bytes": 42.0,
          "limit_size": "string",
          "limit_size_in_bytes": 42.0,
          "overhead": 42.0,
          "tripped": 42.0
        }
      },
      "fs": {
        "data": [
          {}
        ],
        "timestamp": 42.0,
        "total": {
          "available": "string",
          "available_in_bytes": 42.0,
          "free": "string",
          "free_in_bytes": 42.0,
          "total": "string",
          "total_in_bytes": 42.0
        },
        "io_stats": {
          "devices": [
            {}
          ],
          "total": {}
        }
      },
      "host": "string",
      "http": {
        "current_open": 42.0,
        "total_opened": 42.0,
        "clients": [
          {}
        ],
        "routes": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        }
      },
      "ingest": {
        "pipelines": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "total": {
          "count": 42.0,
          "current": 42.0,
          "failed": 42.0
        }
      },
      "ip": "string",
      "jvm": {
        "buffer_pools": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "classes": {
          "current_loaded_count": 42.0,
          "total_loaded_count": 42.0,
          "total_unloaded_count": 42.0
        },
        "gc": {
          "collectors": {}
        },
        "mem": {
          "heap_used_in_bytes": 42.0,
          "heap_used_percent": 42.0,
          "heap_committed_in_bytes": 42.0,
          "heap_max_in_bytes": 42.0,
          "non_heap_used_in_bytes": 42.0,
          "non_heap_committed_in_bytes": 42.0,
          "pools": {}
        },
        "threads": {
          "count": 42.0,
          "peak_count": 42.0
        },
        "timestamp": 42.0,
        "uptime": "string",
        "uptime_in_millis": 42.0
      },
      "name": "string",
      "os": {
        "cpu": {
          "percent": 42.0,
          "sys": "string",
          "total": "string",
          "user": "string",
          "load_average": {}
        },
        "": {},
        "swap": {
          "adjusted_total_in_bytes": 42.0,
          "resident": "string",
          "resident_in_bytes": 42.0,
          "share": "string",
          "share_in_bytes": 42.0,
          "total_virtual": "string",
          "total_virtual_in_bytes": 42.0,
          "total_in_bytes": 42.0,
          "free_in_bytes": 42.0,
          "used_in_bytes": 42.0
        },
        "cgroup": {
          "cpuacct": {},
          "cpu": {},
          "memory": {}
        },
        "timestamp": 42.0
      },
      "process": {
        "cpu": {
          "percent": 42.0,
          "sys": "string",
          "total": "string",
          "user": "string",
          "load_average": {}
        },
        "mem": {
          "adjusted_total_in_bytes": 42.0,
          "resident": "string",
          "resident_in_bytes": 42.0,
          "share": "string",
          "share_in_bytes": 42.0,
          "total_virtual": "string",
          "total_virtual_in_bytes": 42.0,
          "total_in_bytes": 42.0,
          "free_in_bytes": 42.0,
          "used_in_bytes": 42.0
        },
        "open_file_descriptors": 42.0,
        "max_file_descriptors": 42.0,
        "timestamp": 42.0
      },
      "roles": [
        "master"
      ],
      "script": {
        "cache_evictions": 42.0,
        "compilations": 42.0,
        "compilations_history": {
          "additionalProperty1": 42.0,
          "additionalProperty2": 42.0
        },
        "compilation_limit_triggered": 42.0,
        "contexts": [
          {}
        ]
      },
      "script_cache": {},
      "thread_pool": {
        "additionalProperty1": {
          "active": 42.0,
          "completed": 42.0,
          "largest": 42.0,
          "queue": 42.0,
          "rejected": 42.0,
          "threads": 42.0
        },
        "additionalProperty2": {
          "active": 42.0,
          "completed": 42.0,
          "largest": 42.0,
          "queue": 42.0,
          "rejected": 42.0,
          "threads": 42.0
        }
      },
      "timestamp": 42.0,
      "transport": {
        "inbound_handling_time_histogram": [
          {}
        ],
        "outbound_handling_time_histogram": [
          {}
        ],
        "rx_count": 42.0,
        "rx_size": "string",
        "rx_size_in_bytes": 42.0,
        "server_open": 42.0,
        "tx_count": 42.0,
        "tx_size": "string",
        "tx_size_in_bytes": 42.0,
        "total_outbound_connections": 42.0
      },
      "transport_address": "string",
      "attributes": {
        "additionalProperty1": "string",
        "additionalProperty2": "string"
      },
      "discovery": {
        "cluster_state_queue": {
          "total": 42.0,
          "pending": 42.0,
          "committed": 42.0
        },
        "published_cluster_states": {
          "full_states": 42.0,
          "incompatible_diffs": 42.0,
          "compatible_diffs": 42.0
        },
        "cluster_state_update": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "serialized_cluster_states": {
          "full_states": {},
          "diffs": {}
        },
        "cluster_applier_stats": {
          "recordings": [
            {}
          ]
        }
      },
      "indexing_pressure": {
        "memory": {
          "limit_in_bytes": 42.0,
          "current": {},
          "total": {}
        }
      },
      "indices": {
        "commit": {
          "generation": 42.0,
          "id": "string",
          "num_docs": 42.0,
          "user_data": {}
        },
        "completion": {
          "size_in_bytes": 42.0,
          "fields": {}
        },
        "docs": {
          "count": 42.0,
          "deleted": 42.0
        },
        "fielddata": {
          "evictions": 42.0,
          "memory_size_in_bytes": 42.0,
          "fields": {}
        },
        "flush": {
          "periodic": 42.0,
          "total": 42.0,
          "total_time": "string"
        },
        "get": {
          "current": 42.0,
          "exists_time": "string",
          "exists_total": 42.0,
          "missing_time": "string",
          "missing_total": 42.0,
          "time": "string",
          "total": 42.0
        },
        "indexing": {
          "index_current": 42.0,
          "delete_current": 42.0,
          "delete_time": "string",
          "delete_total": 42.0,
          "is_throttled": true,
          "noop_update_total": 42.0,
          "throttle_time": "string",
          "index_time": "string",
          "index_total": 42.0,
          "index_failed": 42.0,
          "types": {},
          "write_load": 42.0
        },
        "mappings": {
          "total_count": 42.0,
          "total_estimated_overhead_in_bytes": 42.0
        },
        "merges": {
          "current": 42.0,
          "current_docs": 42.0,
          "current_size": "string",
          "current_size_in_bytes": 42.0,
          "total": 42.0,
          "total_auto_throttle": "string",
          "total_auto_throttle_in_bytes": 42.0,
          "total_docs": 42.0,
          "total_size": "string",
          "total_size_in_bytes": 42.0,
          "total_stopped_time": "string",
          "total_throttled_time": "string",
          "total_time": "string"
        },
        "shard_path": {
          "data_path": "string",
          "is_custom_data_path": true,
          "state_path": "string"
        },
        "query_cache": {
          "cache_count": 42.0,
          "cache_size": 42.0,
          "evictions": 42.0,
          "hit_count": 42.0,
          "memory_size_in_bytes": 42.0,
          "miss_count": 42.0,
          "total_count": 42.0
        },
        "recovery": {
          "current_as_source": 42.0,
          "current_as_target": 42.0,
          "throttle_time": "string"
        },
        "refresh": {
          "external_total": 42.0,
          "listeners": 42.0,
          "total": 42.0,
          "total_time": "string"
        },
        "request_cache": {
          "evictions": 42.0,
          "hit_count": 42.0,
          "memory_size": "string",
          "memory_size_in_bytes": 42.0,
          "miss_count": 42.0
        },
        "retention_leases": {
          "primary_term": 42.0,
          "version": 42.0,
          "leases": [
            {}
          ]
        },
        "routing": {
          "node": "string",
          "primary": true,
          "state": "UNASSIGNED"
        },
        "search": {
          "fetch_current": 42.0,
          "fetch_time": "string",
          "fetch_total": 42.0,
          "open_contexts": 42.0,
          "query_current": 42.0,
          "query_time": "string",
          "query_total": 42.0,
          "scroll_current": 42.0,
          "scroll_time": "string",
          "scroll_total": 42.0,
          "suggest_current": 42.0,
          "suggest_time": "string",
          "suggest_total": 42.0,
          "groups": {}
        },
        "segments": {
          "count": 42.0,
          "doc_values_memory_in_bytes": 42.0,
          "file_sizes": {},
          "fixed_bit_set_memory_in_bytes": 42.0,
          "index_writer_max_memory_in_bytes": 42.0,
          "index_writer_memory_in_bytes": 42.0,
          "max_unsafe_auto_id_timestamp": 42.0,
          "memory_in_bytes": 42.0,
          "norms_memory_in_bytes": 42.0,
          "points_memory_in_bytes": 42.0,
          "stored_fields_memory_in_bytes": 42.0,
          "terms_memory_in_bytes": 42.0,
          "term_vectors_memory_in_bytes": 42.0,
          "version_map_memory_in_bytes": 42.0
        },
        "seq_no": {
          "global_checkpoint": 42.0,
          "local_checkpoint": 42.0,
          "max_seq_no": 42.0
        },
        "store": {
          "size_in_bytes": 42.0,
          "reserved_in_bytes": 42.0,
          "total_data_set_size_in_bytes": 42.0
        },
        "translog": {
          "earliest_last_modified_age": 42.0,
          "operations": 42.0,
          "size": "string",
          "size_in_bytes": 42.0,
          "uncommitted_operations": 42.0,
          "uncommitted_size": "string",
          "uncommitted_size_in_bytes": 42.0
        },
        "warmer": {
          "current": 42.0,
          "total": 42.0,
          "total_time": "string"
        },
        "bulk": {
          "total_operations": 42.0,
          "total_time": "string",
          "total_size_in_bytes": 42.0,
          "avg_time": "string",
          "avg_size_in_bytes": 42.0
        },
        "shards": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "shard_stats": {
          "total_count": 42.0
        },
        "additionalProperty1": {
          "primaries": {},
          "shards": {},
          "total": {},
          "uuid": "string",
          "health": "green",
          "status": "open"
        },
        "additionalProperty2": {
          "primaries": {},
          "shards": {},
          "total": {},
          "uuid": "string",
          "health": "green",
          "status": "open"
        }
      }
    },
    "additionalProperty2": {
      "adaptive_selection": {
        "additionalProperty1": {
          "avg_queue_size": 42.0,
          "avg_response_time": "string",
          "avg_response_time_ns": 42.0,
          "avg_service_time": "string",
          "avg_service_time_ns": 42.0,
          "outgoing_searches": 42.0,
          "rank": "string"
        },
        "additionalProperty2": {
          "avg_queue_size": 42.0,
          "avg_response_time": "string",
          "avg_response_time_ns": 42.0,
          "avg_service_time": "string",
          "avg_service_time_ns": 42.0,
          "outgoing_searches": 42.0,
          "rank": "string"
        }
      },
      "breakers": {
        "additionalProperty1": {
          "estimated_size": "string",
          "estimated_size_in_bytes": 42.0,
          "limit_size": "string",
          "limit_size_in_bytes": 42.0,
          "overhead": 42.0,
          "tripped": 42.0
        },
        "additionalProperty2": {
          "estimated_size": "string",
          "estimated_size_in_bytes": 42.0,
          "limit_size": "string",
          "limit_size_in_bytes": 42.0,
          "overhead": 42.0,
          "tripped": 42.0
        }
      },
      "fs": {
        "data": [
          {}
        ],
        "timestamp": 42.0,
        "total": {
          "available": "string",
          "available_in_bytes": 42.0,
          "free": "string",
          "free_in_bytes": 42.0,
          "total": "string",
          "total_in_bytes": 42.0
        },
        "io_stats": {
          "devices": [
            {}
          ],
          "total": {}
        }
      },
      "host": "string",
      "http": {
        "current_open": 42.0,
        "total_opened": 42.0,
        "clients": [
          {}
        ],
        "routes": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        }
      },
      "ingest": {
        "pipelines": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "total": {
          "count": 42.0,
          "current": 42.0,
          "failed": 42.0
        }
      },
      "ip": "string",
      "jvm": {
        "buffer_pools": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "classes": {
          "current_loaded_count": 42.0,
          "total_loaded_count": 42.0,
          "total_unloaded_count": 42.0
        },
        "gc": {
          "collectors": {}
        },
        "mem": {
          "heap_used_in_bytes": 42.0,
          "heap_used_percent": 42.0,
          "heap_committed_in_bytes": 42.0,
          "heap_max_in_bytes": 42.0,
          "non_heap_used_in_bytes": 42.0,
          "non_heap_committed_in_bytes": 42.0,
          "pools": {}
        },
        "threads": {
          "count": 42.0,
          "peak_count": 42.0
        },
        "timestamp": 42.0,
        "uptime": "string",
        "uptime_in_millis": 42.0
      },
      "name": "string",
      "os": {
        "cpu": {
          "percent": 42.0,
          "sys": "string",
          "total": "string",
          "user": "string",
          "load_average": {}
        },
        "": {},
        "swap": {
          "adjusted_total_in_bytes": 42.0,
          "resident": "string",
          "resident_in_bytes": 42.0,
          "share": "string",
          "share_in_bytes": 42.0,
          "total_virtual": "string",
          "total_virtual_in_bytes": 42.0,
          "total_in_bytes": 42.0,
          "free_in_bytes": 42.0,
          "used_in_bytes": 42.0
        },
        "cgroup": {
          "cpuacct": {},
          "cpu": {},
          "memory": {}
        },
        "timestamp": 42.0
      },
      "process": {
        "cpu": {
          "percent": 42.0,
          "sys": "string",
          "total": "string",
          "user": "string",
          "load_average": {}
        },
        "mem": {
          "adjusted_total_in_bytes": 42.0,
          "resident": "string",
          "resident_in_bytes": 42.0,
          "share": "string",
          "share_in_bytes": 42.0,
          "total_virtual": "string",
          "total_virtual_in_bytes": 42.0,
          "total_in_bytes": 42.0,
          "free_in_bytes": 42.0,
          "used_in_bytes": 42.0
        },
        "open_file_descriptors": 42.0,
        "max_file_descriptors": 42.0,
        "timestamp": 42.0
      },
      "roles": [
        "master"
      ],
      "script": {
        "cache_evictions": 42.0,
        "compilations": 42.0,
        "compilations_history": {
          "additionalProperty1": 42.0,
          "additionalProperty2": 42.0
        },
        "compilation_limit_triggered": 42.0,
        "contexts": [
          {}
        ]
      },
      "script_cache": {},
      "thread_pool": {
        "additionalProperty1": {
          "active": 42.0,
          "completed": 42.0,
          "largest": 42.0,
          "queue": 42.0,
          "rejected": 42.0,
          "threads": 42.0
        },
        "additionalProperty2": {
          "active": 42.0,
          "completed": 42.0,
          "largest": 42.0,
          "queue": 42.0,
          "rejected": 42.0,
          "threads": 42.0
        }
      },
      "timestamp": 42.0,
      "transport": {
        "inbound_handling_time_histogram": [
          {}
        ],
        "outbound_handling_time_histogram": [
          {}
        ],
        "rx_count": 42.0,
        "rx_size": "string",
        "rx_size_in_bytes": 42.0,
        "server_open": 42.0,
        "tx_count": 42.0,
        "tx_size": "string",
        "tx_size_in_bytes": 42.0,
        "total_outbound_connections": 42.0
      },
      "transport_address": "string",
      "attributes": {
        "additionalProperty1": "string",
        "additionalProperty2": "string"
      },
      "discovery": {
        "cluster_state_queue": {
          "total": 42.0,
          "pending": 42.0,
          "committed": 42.0
        },
        "published_cluster_states": {
          "full_states": 42.0,
          "incompatible_diffs": 42.0,
          "compatible_diffs": 42.0
        },
        "cluster_state_update": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "serialized_cluster_states": {
          "full_states": {},
          "diffs": {}
        },
        "cluster_applier_stats": {
          "recordings": [
            {}
          ]
        }
      },
      "indexing_pressure": {
        "memory": {
          "limit_in_bytes": 42.0,
          "current": {},
          "total": {}
        }
      },
      "indices": {
        "commit": {
          "generation": 42.0,
          "id": "string",
          "num_docs": 42.0,
          "user_data": {}
        },
        "completion": {
          "size_in_bytes": 42.0,
          "fields": {}
        },
        "docs": {
          "count": 42.0,
          "deleted": 42.0
        },
        "fielddata": {
          "evictions": 42.0,
          "memory_size_in_bytes": 42.0,
          "fields": {}
        },
        "flush": {
          "periodic": 42.0,
          "total": 42.0,
          "total_time": "string"
        },
        "get": {
          "current": 42.0,
          "exists_time": "string",
          "exists_total": 42.0,
          "missing_time": "string",
          "missing_total": 42.0,
          "time": "string",
          "total": 42.0
        },
        "indexing": {
          "index_current": 42.0,
          "delete_current": 42.0,
          "delete_time": "string",
          "delete_total": 42.0,
          "is_throttled": true,
          "noop_update_total": 42.0,
          "throttle_time": "string",
          "index_time": "string",
          "index_total": 42.0,
          "index_failed": 42.0,
          "types": {},
          "write_load": 42.0
        },
        "mappings": {
          "total_count": 42.0,
          "total_estimated_overhead_in_bytes": 42.0
        },
        "merges": {
          "current": 42.0,
          "current_docs": 42.0,
          "current_size": "string",
          "current_size_in_bytes": 42.0,
          "total": 42.0,
          "total_auto_throttle": "string",
          "total_auto_throttle_in_bytes": 42.0,
          "total_docs": 42.0,
          "total_size": "string",
          "total_size_in_bytes": 42.0,
          "total_stopped_time": "string",
          "total_throttled_time": "string",
          "total_time": "string"
        },
        "shard_path": {
          "data_path": "string",
          "is_custom_data_path": true,
          "state_path": "string"
        },
        "query_cache": {
          "cache_count": 42.0,
          "cache_size": 42.0,
          "evictions": 42.0,
          "hit_count": 42.0,
          "memory_size_in_bytes": 42.0,
          "miss_count": 42.0,
          "total_count": 42.0
        },
        "recovery": {
          "current_as_source": 42.0,
          "current_as_target": 42.0,
          "throttle_time": "string"
        },
        "refresh": {
          "external_total": 42.0,
          "listeners": 42.0,
          "total": 42.0,
          "total_time": "string"
        },
        "request_cache": {
          "evictions": 42.0,
          "hit_count": 42.0,
          "memory_size": "string",
          "memory_size_in_bytes": 42.0,
          "miss_count": 42.0
        },
        "retention_leases": {
          "primary_term": 42.0,
          "version": 42.0,
          "leases": [
            {}
          ]
        },
        "routing": {
          "node": "string",
          "primary": true,
          "state": "UNASSIGNED"
        },
        "search": {
          "fetch_current": 42.0,
          "fetch_time": "string",
          "fetch_total": 42.0,
          "open_contexts": 42.0,
          "query_current": 42.0,
          "query_time": "string",
          "query_total": 42.0,
          "scroll_current": 42.0,
          "scroll_time": "string",
          "scroll_total": 42.0,
          "suggest_current": 42.0,
          "suggest_time": "string",
          "suggest_total": 42.0,
          "groups": {}
        },
        "segments": {
          "count": 42.0,
          "doc_values_memory_in_bytes": 42.0,
          "file_sizes": {},
          "fixed_bit_set_memory_in_bytes": 42.0,
          "index_writer_max_memory_in_bytes": 42.0,
          "index_writer_memory_in_bytes": 42.0,
          "max_unsafe_auto_id_timestamp": 42.0,
          "memory_in_bytes": 42.0,
          "norms_memory_in_bytes": 42.0,
          "points_memory_in_bytes": 42.0,
          "stored_fields_memory_in_bytes": 42.0,
          "terms_memory_in_bytes": 42.0,
          "term_vectors_memory_in_bytes": 42.0,
          "version_map_memory_in_bytes": 42.0
        },
        "seq_no": {
          "global_checkpoint": 42.0,
          "local_checkpoint": 42.0,
          "max_seq_no": 42.0
        },
        "store": {
          "size_in_bytes": 42.0,
          "reserved_in_bytes": 42.0,
          "total_data_set_size_in_bytes": 42.0
        },
        "translog": {
          "earliest_last_modified_age": 42.0,
          "operations": 42.0,
          "size": "string",
          "size_in_bytes": 42.0,
          "uncommitted_operations": 42.0,
          "uncommitted_size": "string",
          "uncommitted_size_in_bytes": 42.0
        },
        "warmer": {
          "current": 42.0,
          "total": 42.0,
          "total_time": "string"
        },
        "bulk": {
          "total_operations": 42.0,
          "total_time": "string",
          "total_size_in_bytes": 42.0,
          "avg_time": "string",
          "avg_size_in_bytes": 42.0
        },
        "shards": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "shard_stats": {
          "total_count": 42.0
        },
        "additionalProperty1": {
          "primaries": {},
          "shards": {},
          "total": {},
          "uuid": "string",
          "health": "green",
          "status": "open"
        },
        "additionalProperty2": {
          "primaries": {},
          "shards": {},
          "total": {},
          "uuid": "string",
          "health": "green",
          "status": "open"
        }
      }
    }
  }
}




Get node statistics

GET /_nodes/stats/{metric}/{index_metric}

Get statistics for nodes in a cluster. By default, all stats are returned. You can limit the returned information by using metrics.

Path parameters

  • metric string | array[string] Required

    Limit the information returned to the specified metrics

  • index_metric string | array[string] Required

    Limit the information returned for indices metric to the specific index metrics. It can be used only if indices (or all) metric is specified.

Query parameters

  • completion_fields string | array[string]

    Comma-separated list or wildcard expressions of fields to include in fielddata and suggest statistics.

  • fielddata_fields string | array[string]

    Comma-separated list or wildcard expressions of fields to include in fielddata statistics.

  • fields string | array[string]

    Comma-separated list or wildcard expressions of fields to include in the statistics.

  • groups boolean

    Comma-separated list of search groups to include in the search statistics.

  • If true, the call reports the aggregated disk usage of each one of the Lucene index files (only applies if segment stats are requested).

  • level string

    Indicates whether statistics are aggregated at the cluster, index, or shard level.

    Values are cluster, indices, or shards.

  • timeout string

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

  • types array[string]

    A comma-separated list of document types for the indexing index metric.

  • If true, the response includes information from segments that are not loaded into memory.

Responses

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

      Additional properties are allowed.

      Hide _nodes attributes Show _nodes attributes object
      • failures array[object]
        Hide failures attributes Show failures attributes object
        • type string Required

          The type of error

        • reason string

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

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

        • Additional properties are allowed.

        • root_cause array[object]

          Additional properties are allowed.

        • suppressed array[object]

          Additional properties are allowed.

      • total number Required

        Total number of nodes selected by the request.

      • successful number Required

        Number of nodes that responded successfully to the request.

      • failed number Required

        Number of nodes that rejected the request or failed to respond. If this value is not 0, a reason for the rejection or failure is included in the response.

    • nodes object Required
      Hide nodes attribute Show nodes attribute object
      • * object Additional properties

        Additional properties are allowed.

        Hide * attributes Show * attributes object
        • Statistics about adaptive replica selection.

          Hide adaptive_selection attribute Show adaptive_selection attribute object
          • * object Additional properties

            Additional properties are allowed.

            Hide * attributes Show * attributes object
            • The exponentially weighted moving average queue size of search requests on the keyed node.

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

            • The exponentially weighted moving average response time, in nanoseconds, of search requests on the keyed node.

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

            • The exponentially weighted moving average service time, in nanoseconds, of search requests on the keyed node.

            • The number of outstanding search requests to the keyed node from the node these stats are for.

            • rank string

              The rank of this node; used for shard selection when routing search requests.

        • breakers object

          Statistics about the field data circuit breaker.

          Hide breakers attribute Show breakers attribute object
          • * object Additional properties

            Additional properties are allowed.

            Hide * attributes Show * attributes object
            • Estimated memory used for the operation.

            • Estimated memory used, in bytes, for the operation.

            • Memory limit for the circuit breaker.

            • Memory limit, in bytes, for the circuit breaker.

            • overhead number

              A constant that all estimates for the circuit breaker are multiplied with to calculate a final estimate.

            • tripped number

              Total number of times the circuit breaker has been triggered and prevented an out of memory error.

        • fs object

          Additional properties are allowed.

          Hide fs attributes Show fs attributes object
          • data array[object]

            List of all file stores.

            Additional properties are allowed.

          • Last time the file stores statistics were refreshed. Recorded in milliseconds since the Unix Epoch.

          • total object

            Additional properties are allowed.

            Hide total attributes Show total attributes object
            • Total disk space available to this Java virtual machine on all file stores. Depending on OS or process level restrictions, this might appear less than free. This is the actual amount of free disk space the Elasticsearch node can utilise.

            • Total number of bytes available to this Java virtual machine on all file stores. Depending on OS or process level restrictions, this might appear less than free_in_bytes. This is the actual amount of free disk space the Elasticsearch node can utilise.

            • free string

              Total unallocated disk space in all file stores.

            • Total number of unallocated bytes in all file stores.

            • total string

              Total size of all file stores.

            • Total size of all file stores in bytes.

          • io_stats object

            Additional properties are allowed.

            Hide io_stats attributes Show io_stats attributes object
            • devices array[object]

              Array of disk metrics for each device that is backing an Elasticsearch data path. These disk metrics are probed periodically and averages between the last probe and the current probe are computed.

            • total object

              Additional properties are allowed.

        • host string
        • http object

          Additional properties are allowed.

          Hide http attributes Show http attributes object
          • Current number of open HTTP connections for the node.

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

            Additional properties are allowed.

          • routes object Required Added in 8.12.0

            Detailed HTTP stats broken down by route

            Hide routes attribute Show routes attribute object
            • * object Additional properties

              Additional properties are allowed.

        • ingest object

          Additional properties are allowed.

          Hide ingest attributes Show ingest attributes object
          • Contains statistics about ingest pipelines for the node.

            Hide pipelines attribute Show pipelines attribute object
            • * object Additional properties

              Additional properties are allowed.

          • total object

            Additional properties are allowed.

            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.

        • ip string | array[string]

          IP address and port for the node.

        • jvm object

          Additional properties are allowed.

          Hide jvm attributes Show jvm attributes object
          • Contains statistics about JVM buffer pools for the node.

            Hide buffer_pools attribute Show buffer_pools attribute object
            • * object Additional properties

              Additional properties are allowed.

          • classes object

            Additional properties are allowed.

            Hide classes attributes Show classes attributes object
          • gc object

            Additional properties are allowed.

            Hide gc attribute Show gc attribute object
            • Contains statistics about JVM garbage collectors for the node.

          • mem object

            Additional properties are allowed.

            Hide mem attributes Show mem attributes object
          • threads object

            Additional properties are allowed.

            Hide threads attributes Show threads attributes object
            • count number

              Number of active threads in use by JVM.

            • Highest number of threads used by JVM.

          • Last time JVM statistics were refreshed.

          • uptime string

            Human-readable JVM uptime. Only returned if the human query parameter is true.

          • JVM uptime in milliseconds.

        • name string
        • os object

          Additional properties are allowed.

          Hide os attributes Show os attributes object
          • cpu object

            Additional properties are allowed.

            Hide cpu attributes Show cpu attributes object
            • percent number
            • sys string

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

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

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

          • mem object

            Additional properties are allowed.

          • swap object

            Additional properties are allowed.

            Hide swap attributes Show swap attributes object
          • cgroup object

            Additional properties are allowed.

            Hide cgroup attributes Show cgroup attributes object
            • cpuacct object

              Additional properties are allowed.

            • cpu object

              Additional properties are allowed.

            • memory object

              Additional properties are allowed.

        • process object

          Additional properties are allowed.

          Hide process attributes Show process attributes object
          • cpu object

            Additional properties are allowed.

            Hide cpu attributes Show cpu attributes object
            • percent number
            • sys string

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

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

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

          • mem object

            Additional properties are allowed.

            Hide mem attributes Show mem attributes object
          • Number of opened file descriptors associated with the current or -1 if not supported.

          • Maximum number of file descriptors allowed on the system, or -1 if not supported.

          • Last time the statistics were refreshed. Recorded in milliseconds since the Unix Epoch.

        • roles array[string]
          • @doc_id node-roles

          Values are master, data, data_cold, data_content, data_frozen, data_hot, data_warm, client, ingest, ml, voting_only, transform, remote_cluster_client, or coordinating_only.

        • script object

          Additional properties are allowed.

          Hide script attributes Show script attributes object
          • Total number of times the script cache has evicted old data.

          • Total number of inline script compilations performed by the node.

          • Contains this recent history of script compilations.

            Hide compilations_history attribute Show compilations_history attribute object
            • * number Additional properties
          • Total number of times the script compilation circuit breaker has limited inline script compilations.

          • contexts array[object]

            Additional properties are allowed.

        • Statistics about each thread pool, including current size, queue and rejected tasks.

          Hide thread_pool attribute Show thread_pool attribute object
          • * object Additional properties

            Additional properties are allowed.

            Hide * attributes Show * attributes object
            • active number

              Number of active threads in the thread pool.

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

        • Additional properties are allowed.

          Hide transport attributes Show transport attributes object
          • The distribution of the time spent handling each inbound message on a transport thread, represented as a histogram.

            Additional properties are allowed.

          • The distribution of the time spent sending each outbound transport message on a transport thread, represented as a histogram.

            Additional properties are allowed.

          • rx_count number

            Total number of RX (receive) packets received by the node during internal cluster communication.

          • rx_size string

            Size of RX packets received by the node during internal cluster communication.

          • Size, in bytes, of RX packets received by the node during internal cluster communication.

          • Current number of inbound TCP connections used for internal communication between nodes.

          • tx_count number

            Total number of TX (transmit) packets sent by the node during internal cluster communication.

          • tx_size string

            Size of TX packets sent by the node during internal cluster communication.

          • Size, in bytes, of TX packets sent by the node during internal cluster communication.

          • The cumulative number of outbound transport connections that this node has opened since it started. Each transport connection may comprise multiple TCP connections but is only counted once in this statistic. Transport connections are typically long-lived so this statistic should remain constant in a stable cluster.

        • Contains a list of attributes for the node.

          Hide attributes attribute Show attributes attribute object
          • * string Additional properties
        • Additional properties are allowed.

          Hide discovery attributes Show discovery attributes object
          • Additional properties are allowed.

            Hide cluster_state_queue attributes Show cluster_state_queue attributes object
            • total number

              Total number of cluster states in queue.

            • pending number

              Number of pending cluster states in queue.

            • Number of committed cluster states in queue.

          • Additional properties are allowed.

            Hide published_cluster_states attributes Show published_cluster_states attributes object
          • Contains low-level statistics about how long various activities took during cluster state updates while the node was the elected master. Omitted if the node is not master-eligible. Every field whose name ends in _time within this object is also represented as a raw number of milliseconds in a field whose name ends in _time_millis. The human-readable fields with a _time suffix are only returned if requested with the ?human=true query parameter.

            Hide cluster_state_update attribute Show cluster_state_update attribute object
            • * object Additional properties

              Additional properties are allowed.

          • Additional properties are allowed.

            Hide serialized_cluster_states attributes Show serialized_cluster_states attributes object
            • Additional properties are allowed.

            • diffs object

              Additional properties are allowed.

          • Additional properties are allowed.

            Hide cluster_applier_stats attribute Show cluster_applier_stats attribute object
        • Additional properties are allowed.

          Hide indexing_pressure attribute Show indexing_pressure attribute object
          • memory object

            Additional properties are allowed.

            Hide memory attributes Show memory attributes object
            • Configured memory limit, in bytes, for the indexing requests. Replica requests have an automatic limit that is 1.5x this value.

            • current object

              Additional properties are allowed.

            • total object

              Additional properties are allowed.

        • indices object

          Additional properties are allowed.

          Hide indices attributes Show indices attributes object
GET /_nodes/stats/{metric}/{index_metric}
curl \
 --request GET http://api.example.com/_nodes/stats/{metric}/{index_metric}
Response examples (200)
{
  "_nodes": {
    "failures": [
      {
        "type": "string",
        "reason": "string",
        "stack_trace": "string",
        "caused_by": {},
        "root_cause": [
          {}
        ],
        "suppressed": [
          {}
        ]
      }
    ],
    "total": 42.0,
    "successful": 42.0,
    "failed": 42.0
  },
  "cluster_name": "string",
  "nodes": {
    "additionalProperty1": {
      "adaptive_selection": {
        "additionalProperty1": {
          "avg_queue_size": 42.0,
          "avg_response_time": "string",
          "avg_response_time_ns": 42.0,
          "avg_service_time": "string",
          "avg_service_time_ns": 42.0,
          "outgoing_searches": 42.0,
          "rank": "string"
        },
        "additionalProperty2": {
          "avg_queue_size": 42.0,
          "avg_response_time": "string",
          "avg_response_time_ns": 42.0,
          "avg_service_time": "string",
          "avg_service_time_ns": 42.0,
          "outgoing_searches": 42.0,
          "rank": "string"
        }
      },
      "breakers": {
        "additionalProperty1": {
          "estimated_size": "string",
          "estimated_size_in_bytes": 42.0,
          "limit_size": "string",
          "limit_size_in_bytes": 42.0,
          "overhead": 42.0,
          "tripped": 42.0
        },
        "additionalProperty2": {
          "estimated_size": "string",
          "estimated_size_in_bytes": 42.0,
          "limit_size": "string",
          "limit_size_in_bytes": 42.0,
          "overhead": 42.0,
          "tripped": 42.0
        }
      },
      "fs": {
        "data": [
          {}
        ],
        "timestamp": 42.0,
        "total": {
          "available": "string",
          "available_in_bytes": 42.0,
          "free": "string",
          "free_in_bytes": 42.0,
          "total": "string",
          "total_in_bytes": 42.0
        },
        "io_stats": {
          "devices": [
            {}
          ],
          "total": {}
        }
      },
      "host": "string",
      "http": {
        "current_open": 42.0,
        "total_opened": 42.0,
        "clients": [
          {}
        ],
        "routes": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        }
      },
      "ingest": {
        "pipelines": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "total": {
          "count": 42.0,
          "current": 42.0,
          "failed": 42.0
        }
      },
      "ip": "string",
      "jvm": {
        "buffer_pools": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "classes": {
          "current_loaded_count": 42.0,
          "total_loaded_count": 42.0,
          "total_unloaded_count": 42.0
        },
        "gc": {
          "collectors": {}
        },
        "mem": {
          "heap_used_in_bytes": 42.0,
          "heap_used_percent": 42.0,
          "heap_committed_in_bytes": 42.0,
          "heap_max_in_bytes": 42.0,
          "non_heap_used_in_bytes": 42.0,
          "non_heap_committed_in_bytes": 42.0,
          "pools": {}
        },
        "threads": {
          "count": 42.0,
          "peak_count": 42.0
        },
        "timestamp": 42.0,
        "uptime": "string",
        "uptime_in_millis": 42.0
      },
      "name": "string",
      "os": {
        "cpu": {
          "percent": 42.0,
          "sys": "string",
          "total": "string",
          "user": "string",
          "load_average": {}
        },
        "": {},
        "swap": {
          "adjusted_total_in_bytes": 42.0,
          "resident": "string",
          "resident_in_bytes": 42.0,
          "share": "string",
          "share_in_bytes": 42.0,
          "total_virtual": "string",
          "total_virtual_in_bytes": 42.0,
          "total_in_bytes": 42.0,
          "free_in_bytes": 42.0,
          "used_in_bytes": 42.0
        },
        "cgroup": {
          "cpuacct": {},
          "cpu": {},
          "memory": {}
        },
        "timestamp": 42.0
      },
      "process": {
        "cpu": {
          "percent": 42.0,
          "sys": "string",
          "total": "string",
          "user": "string",
          "load_average": {}
        },
        "mem": {
          "adjusted_total_in_bytes": 42.0,
          "resident": "string",
          "resident_in_bytes": 42.0,
          "share": "string",
          "share_in_bytes": 42.0,
          "total_virtual": "string",
          "total_virtual_in_bytes": 42.0,
          "total_in_bytes": 42.0,
          "free_in_bytes": 42.0,
          "used_in_bytes": 42.0
        },
        "open_file_descriptors": 42.0,
        "max_file_descriptors": 42.0,
        "timestamp": 42.0
      },
      "roles": [
        "master"
      ],
      "script": {
        "cache_evictions": 42.0,
        "compilations": 42.0,
        "compilations_history": {
          "additionalProperty1": 42.0,
          "additionalProperty2": 42.0
        },
        "compilation_limit_triggered": 42.0,
        "contexts": [
          {}
        ]
      },
      "script_cache": {},
      "thread_pool": {
        "additionalProperty1": {
          "active": 42.0,
          "completed": 42.0,
          "largest": 42.0,
          "queue": 42.0,
          "rejected": 42.0,
          "threads": 42.0
        },
        "additionalProperty2": {
          "active": 42.0,
          "completed": 42.0,
          "largest": 42.0,
          "queue": 42.0,
          "rejected": 42.0,
          "threads": 42.0
        }
      },
      "timestamp": 42.0,
      "transport": {
        "inbound_handling_time_histogram": [
          {}
        ],
        "outbound_handling_time_histogram": [
          {}
        ],
        "rx_count": 42.0,
        "rx_size": "string",
        "rx_size_in_bytes": 42.0,
        "server_open": 42.0,
        "tx_count": 42.0,
        "tx_size": "string",
        "tx_size_in_bytes": 42.0,
        "total_outbound_connections": 42.0
      },
      "transport_address": "string",
      "attributes": {
        "additionalProperty1": "string",
        "additionalProperty2": "string"
      },
      "discovery": {
        "cluster_state_queue": {
          "total": 42.0,
          "pending": 42.0,
          "committed": 42.0
        },
        "published_cluster_states": {
          "full_states": 42.0,
          "incompatible_diffs": 42.0,
          "compatible_diffs": 42.0
        },
        "cluster_state_update": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "serialized_cluster_states": {
          "full_states": {},
          "diffs": {}
        },
        "cluster_applier_stats": {
          "recordings": [
            {}
          ]
        }
      },
      "indexing_pressure": {
        "memory": {
          "limit_in_bytes": 42.0,
          "current": {},
          "total": {}
        }
      },
      "indices": {
        "commit": {
          "generation": 42.0,
          "id": "string",
          "num_docs": 42.0,
          "user_data": {}
        },
        "completion": {
          "size_in_bytes": 42.0,
          "fields": {}
        },
        "docs": {
          "count": 42.0,
          "deleted": 42.0
        },
        "fielddata": {
          "evictions": 42.0,
          "memory_size_in_bytes": 42.0,
          "fields": {}
        },
        "flush": {
          "periodic": 42.0,
          "total": 42.0,
          "total_time": "string"
        },
        "get": {
          "current": 42.0,
          "exists_time": "string",
          "exists_total": 42.0,
          "missing_time": "string",
          "missing_total": 42.0,
          "time": "string",
          "total": 42.0
        },
        "indexing": {
          "index_current": 42.0,
          "delete_current": 42.0,
          "delete_time": "string",
          "delete_total": 42.0,
          "is_throttled": true,
          "noop_update_total": 42.0,
          "throttle_time": "string",
          "index_time": "string",
          "index_total": 42.0,
          "index_failed": 42.0,
          "types": {},
          "write_load": 42.0
        },
        "mappings": {
          "total_count": 42.0,
          "total_estimated_overhead_in_bytes": 42.0
        },
        "merges": {
          "current": 42.0,
          "current_docs": 42.0,
          "current_size": "string",
          "current_size_in_bytes": 42.0,
          "total": 42.0,
          "total_auto_throttle": "string",
          "total_auto_throttle_in_bytes": 42.0,
          "total_docs": 42.0,
          "total_size": "string",
          "total_size_in_bytes": 42.0,
          "total_stopped_time": "string",
          "total_throttled_time": "string",
          "total_time": "string"
        },
        "shard_path": {
          "data_path": "string",
          "is_custom_data_path": true,
          "state_path": "string"
        },
        "query_cache": {
          "cache_count": 42.0,
          "cache_size": 42.0,
          "evictions": 42.0,
          "hit_count": 42.0,
          "memory_size_in_bytes": 42.0,
          "miss_count": 42.0,
          "total_count": 42.0
        },
        "recovery": {
          "current_as_source": 42.0,
          "current_as_target": 42.0,
          "throttle_time": "string"
        },
        "refresh": {
          "external_total": 42.0,
          "listeners": 42.0,
          "total": 42.0,
          "total_time": "string"
        },
        "request_cache": {
          "evictions": 42.0,
          "hit_count": 42.0,
          "memory_size": "string",
          "memory_size_in_bytes": 42.0,
          "miss_count": 42.0
        },
        "retention_leases": {
          "primary_term": 42.0,
          "version": 42.0,
          "leases": [
            {}
          ]
        },
        "routing": {
          "node": "string",
          "primary": true,
          "state": "UNASSIGNED"
        },
        "search": {
          "fetch_current": 42.0,
          "fetch_time": "string",
          "fetch_total": 42.0,
          "open_contexts": 42.0,
          "query_current": 42.0,
          "query_time": "string",
          "query_total": 42.0,
          "scroll_current": 42.0,
          "scroll_time": "string",
          "scroll_total": 42.0,
          "suggest_current": 42.0,
          "suggest_time": "string",
          "suggest_total": 42.0,
          "groups": {}
        },
        "segments": {
          "count": 42.0,
          "doc_values_memory_in_bytes": 42.0,
          "file_sizes": {},
          "fixed_bit_set_memory_in_bytes": 42.0,
          "index_writer_max_memory_in_bytes": 42.0,
          "index_writer_memory_in_bytes": 42.0,
          "max_unsafe_auto_id_timestamp": 42.0,
          "memory_in_bytes": 42.0,
          "norms_memory_in_bytes": 42.0,
          "points_memory_in_bytes": 42.0,
          "stored_fields_memory_in_bytes": 42.0,
          "terms_memory_in_bytes": 42.0,
          "term_vectors_memory_in_bytes": 42.0,
          "version_map_memory_in_bytes": 42.0
        },
        "seq_no": {
          "global_checkpoint": 42.0,
          "local_checkpoint": 42.0,
          "max_seq_no": 42.0
        },
        "store": {
          "size_in_bytes": 42.0,
          "reserved_in_bytes": 42.0,
          "total_data_set_size_in_bytes": 42.0
        },
        "translog": {
          "earliest_last_modified_age": 42.0,
          "operations": 42.0,
          "size": "string",
          "size_in_bytes": 42.0,
          "uncommitted_operations": 42.0,
          "uncommitted_size": "string",
          "uncommitted_size_in_bytes": 42.0
        },
        "warmer": {
          "current": 42.0,
          "total": 42.0,
          "total_time": "string"
        },
        "bulk": {
          "total_operations": 42.0,
          "total_time": "string",
          "total_size_in_bytes": 42.0,
          "avg_time": "string",
          "avg_size_in_bytes": 42.0
        },
        "shards": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "shard_stats": {
          "total_count": 42.0
        },
        "additionalProperty1": {
          "primaries": {},
          "shards": {},
          "total": {},
          "uuid": "string",
          "health": "green",
          "status": "open"
        },
        "additionalProperty2": {
          "primaries": {},
          "shards": {},
          "total": {},
          "uuid": "string",
          "health": "green",
          "status": "open"
        }
      }
    },
    "additionalProperty2": {
      "adaptive_selection": {
        "additionalProperty1": {
          "avg_queue_size": 42.0,
          "avg_response_time": "string",
          "avg_response_time_ns": 42.0,
          "avg_service_time": "string",
          "avg_service_time_ns": 42.0,
          "outgoing_searches": 42.0,
          "rank": "string"
        },
        "additionalProperty2": {
          "avg_queue_size": 42.0,
          "avg_response_time": "string",
          "avg_response_time_ns": 42.0,
          "avg_service_time": "string",
          "avg_service_time_ns": 42.0,
          "outgoing_searches": 42.0,
          "rank": "string"
        }
      },
      "breakers": {
        "additionalProperty1": {
          "estimated_size": "string",
          "estimated_size_in_bytes": 42.0,
          "limit_size": "string",
          "limit_size_in_bytes": 42.0,
          "overhead": 42.0,
          "tripped": 42.0
        },
        "additionalProperty2": {
          "estimated_size": "string",
          "estimated_size_in_bytes": 42.0,
          "limit_size": "string",
          "limit_size_in_bytes": 42.0,
          "overhead": 42.0,
          "tripped": 42.0
        }
      },
      "fs": {
        "data": [
          {}
        ],
        "timestamp": 42.0,
        "total": {
          "available": "string",
          "available_in_bytes": 42.0,
          "free": "string",
          "free_in_bytes": 42.0,
          "total": "string",
          "total_in_bytes": 42.0
        },
        "io_stats": {
          "devices": [
            {}
          ],
          "total": {}
        }
      },
      "host": "string",
      "http": {
        "current_open": 42.0,
        "total_opened": 42.0,
        "clients": [
          {}
        ],
        "routes": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        }
      },
      "ingest": {
        "pipelines": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "total": {
          "count": 42.0,
          "current": 42.0,
          "failed": 42.0
        }
      },
      "ip": "string",
      "jvm": {
        "buffer_pools": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "classes": {
          "current_loaded_count": 42.0,
          "total_loaded_count": 42.0,
          "total_unloaded_count": 42.0
        },
        "gc": {
          "collectors": {}
        },
        "mem": {
          "heap_used_in_bytes": 42.0,
          "heap_used_percent": 42.0,
          "heap_committed_in_bytes": 42.0,
          "heap_max_in_bytes": 42.0,
          "non_heap_used_in_bytes": 42.0,
          "non_heap_committed_in_bytes": 42.0,
          "pools": {}
        },
        "threads": {
          "count": 42.0,
          "peak_count": 42.0
        },
        "timestamp": 42.0,
        "uptime": "string",
        "uptime_in_millis": 42.0
      },
      "name": "string",
      "os": {
        "cpu": {
          "percent": 42.0,
          "sys": "string",
          "total": "string",
          "user": "string",
          "load_average": {}
        },
        "": {},
        "swap": {
          "adjusted_total_in_bytes": 42.0,
          "resident": "string",
          "resident_in_bytes": 42.0,
          "share": "string",
          "share_in_bytes": 42.0,
          "total_virtual": "string",
          "total_virtual_in_bytes": 42.0,
          "total_in_bytes": 42.0,
          "free_in_bytes": 42.0,
          "used_in_bytes": 42.0
        },
        "cgroup": {
          "cpuacct": {},
          "cpu": {},
          "memory": {}
        },
        "timestamp": 42.0
      },
      "process": {
        "cpu": {
          "percent": 42.0,
          "sys": "string",
          "total": "string",
          "user": "string",
          "load_average": {}
        },
        "mem": {
          "adjusted_total_in_bytes": 42.0,
          "resident": "string",
          "resident_in_bytes": 42.0,
          "share": "string",
          "share_in_bytes": 42.0,
          "total_virtual": "string",
          "total_virtual_in_bytes": 42.0,
          "total_in_bytes": 42.0,
          "free_in_bytes": 42.0,
          "used_in_bytes": 42.0
        },
        "open_file_descriptors": 42.0,
        "max_file_descriptors": 42.0,
        "timestamp": 42.0
      },
      "roles": [
        "master"
      ],
      "script": {
        "cache_evictions": 42.0,
        "compilations": 42.0,
        "compilations_history": {
          "additionalProperty1": 42.0,
          "additionalProperty2": 42.0
        },
        "compilation_limit_triggered": 42.0,
        "contexts": [
          {}
        ]
      },
      "script_cache": {},
      "thread_pool": {
        "additionalProperty1": {
          "active": 42.0,
          "completed": 42.0,
          "largest": 42.0,
          "queue": 42.0,
          "rejected": 42.0,
          "threads": 42.0
        },
        "additionalProperty2": {
          "active": 42.0,
          "completed": 42.0,
          "largest": 42.0,
          "queue": 42.0,
          "rejected": 42.0,
          "threads": 42.0
        }
      },
      "timestamp": 42.0,
      "transport": {
        "inbound_handling_time_histogram": [
          {}
        ],
        "outbound_handling_time_histogram": [
          {}
        ],
        "rx_count": 42.0,
        "rx_size": "string",
        "rx_size_in_bytes": 42.0,
        "server_open": 42.0,
        "tx_count": 42.0,
        "tx_size": "string",
        "tx_size_in_bytes": 42.0,
        "total_outbound_connections": 42.0
      },
      "transport_address": "string",
      "attributes": {
        "additionalProperty1": "string",
        "additionalProperty2": "string"
      },
      "discovery": {
        "cluster_state_queue": {
          "total": 42.0,
          "pending": 42.0,
          "committed": 42.0
        },
        "published_cluster_states": {
          "full_states": 42.0,
          "incompatible_diffs": 42.0,
          "compatible_diffs": 42.0
        },
        "cluster_state_update": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "serialized_cluster_states": {
          "full_states": {},
          "diffs": {}
        },
        "cluster_applier_stats": {
          "recordings": [
            {}
          ]
        }
      },
      "indexing_pressure": {
        "memory": {
          "limit_in_bytes": 42.0,
          "current": {},
          "total": {}
        }
      },
      "indices": {
        "commit": {
          "generation": 42.0,
          "id": "string",
          "num_docs": 42.0,
          "user_data": {}
        },
        "completion": {
          "size_in_bytes": 42.0,
          "fields": {}
        },
        "docs": {
          "count": 42.0,
          "deleted": 42.0
        },
        "fielddata": {
          "evictions": 42.0,
          "memory_size_in_bytes": 42.0,
          "fields": {}
        },
        "flush": {
          "periodic": 42.0,
          "total": 42.0,
          "total_time": "string"
        },
        "get": {
          "current": 42.0,
          "exists_time": "string",
          "exists_total": 42.0,
          "missing_time": "string",
          "missing_total": 42.0,
          "time": "string",
          "total": 42.0
        },
        "indexing": {
          "index_current": 42.0,
          "delete_current": 42.0,
          "delete_time": "string",
          "delete_total": 42.0,
          "is_throttled": true,
          "noop_update_total": 42.0,
          "throttle_time": "string",
          "index_time": "string",
          "index_total": 42.0,
          "index_failed": 42.0,
          "types": {},
          "write_load": 42.0
        },
        "mappings": {
          "total_count": 42.0,
          "total_estimated_overhead_in_bytes": 42.0
        },
        "merges": {
          "current": 42.0,
          "current_docs": 42.0,
          "current_size": "string",
          "current_size_in_bytes": 42.0,
          "total": 42.0,
          "total_auto_throttle": "string",
          "total_auto_throttle_in_bytes": 42.0,
          "total_docs": 42.0,
          "total_size": "string",
          "total_size_in_bytes": 42.0,
          "total_stopped_time": "string",
          "total_throttled_time": "string",
          "total_time": "string"
        },
        "shard_path": {
          "data_path": "string",
          "is_custom_data_path": true,
          "state_path": "string"
        },
        "query_cache": {
          "cache_count": 42.0,
          "cache_size": 42.0,
          "evictions": 42.0,
          "hit_count": 42.0,
          "memory_size_in_bytes": 42.0,
          "miss_count": 42.0,
          "total_count": 42.0
        },
        "recovery": {
          "current_as_source": 42.0,
          "current_as_target": 42.0,
          "throttle_time": "string"
        },
        "refresh": {
          "external_total": 42.0,
          "listeners": 42.0,
          "total": 42.0,
          "total_time": "string"
        },
        "request_cache": {
          "evictions": 42.0,
          "hit_count": 42.0,
          "memory_size": "string",
          "memory_size_in_bytes": 42.0,
          "miss_count": 42.0
        },
        "retention_leases": {
          "primary_term": 42.0,
          "version": 42.0,
          "leases": [
            {}
          ]
        },
        "routing": {
          "node": "string",
          "primary": true,
          "state": "UNASSIGNED"
        },
        "search": {
          "fetch_current": 42.0,
          "fetch_time": "string",
          "fetch_total": 42.0,
          "open_contexts": 42.0,
          "query_current": 42.0,
          "query_time": "string",
          "query_total": 42.0,
          "scroll_current": 42.0,
          "scroll_time": "string",
          "scroll_total": 42.0,
          "suggest_current": 42.0,
          "suggest_time": "string",
          "suggest_total": 42.0,
          "groups": {}
        },
        "segments": {
          "count": 42.0,
          "doc_values_memory_in_bytes": 42.0,
          "file_sizes": {},
          "fixed_bit_set_memory_in_bytes": 42.0,
          "index_writer_max_memory_in_bytes": 42.0,
          "index_writer_memory_in_bytes": 42.0,
          "max_unsafe_auto_id_timestamp": 42.0,
          "memory_in_bytes": 42.0,
          "norms_memory_in_bytes": 42.0,
          "points_memory_in_bytes": 42.0,
          "stored_fields_memory_in_bytes": 42.0,
          "terms_memory_in_bytes": 42.0,
          "term_vectors_memory_in_bytes": 42.0,
          "version_map_memory_in_bytes": 42.0
        },
        "seq_no": {
          "global_checkpoint": 42.0,
          "local_checkpoint": 42.0,
          "max_seq_no": 42.0
        },
        "store": {
          "size_in_bytes": 42.0,
          "reserved_in_bytes": 42.0,
          "total_data_set_size_in_bytes": 42.0
        },
        "translog": {
          "earliest_last_modified_age": 42.0,
          "operations": 42.0,
          "size": "string",
          "size_in_bytes": 42.0,
          "uncommitted_operations": 42.0,
          "uncommitted_size": "string",
          "uncommitted_size_in_bytes": 42.0
        },
        "warmer": {
          "current": 42.0,
          "total": 42.0,
          "total_time": "string"
        },
        "bulk": {
          "total_operations": 42.0,
          "total_time": "string",
          "total_size_in_bytes": 42.0,
          "avg_time": "string",
          "avg_size_in_bytes": 42.0
        },
        "shards": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "shard_stats": {
          "total_count": 42.0
        },
        "additionalProperty1": {
          "primaries": {},
          "shards": {},
          "total": {},
          "uuid": "string",
          "health": "green",
          "status": "open"
        },
        "additionalProperty2": {
          "primaries": {},
          "shards": {},
          "total": {},
          "uuid": "string",
          "health": "green",
          "status": "open"
        }
      }
    }
  }
}




Get feature usage information Added in 6.0.0

GET /_nodes/usage

Query parameters

  • timeout string

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

Responses

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

      Additional properties are allowed.

      Hide _nodes attributes Show _nodes attributes object
      • failures array[object]
        Hide failures attributes Show failures attributes object
        • type string Required

          The type of error

        • reason string

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

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

        • Additional properties are allowed.

        • root_cause array[object]

          Additional properties are allowed.

        • suppressed array[object]

          Additional properties are allowed.

      • total number Required

        Total number of nodes selected by the request.

      • successful number Required

        Number of nodes that responded successfully to the request.

      • failed number Required

        Number of nodes that rejected the request or failed to respond. If this value is not 0, a reason for the rejection or failure is included in the response.

    • cluster_name string Required
    • nodes object Required
      Hide nodes attribute Show nodes attribute object
      • * object Additional properties

        Additional properties are allowed.

        Hide * attributes Show * attributes object
        • rest_actions object Required
          Hide rest_actions attribute Show rest_actions attribute object
          • * number Additional properties
        • since number

          Time unit for milliseconds

        • Time unit for milliseconds

        • aggregations object Required
          Hide aggregations attribute Show aggregations attribute object
          • * object Additional properties

            Additional properties are allowed.

GET /_nodes/usage
curl \
 --request GET http://api.example.com/_nodes/usage
Response examples (200)
{
  "_nodes": {
    "failures": [
      {
        "type": "string",
        "reason": "string",
        "stack_trace": "string",
        "caused_by": {},
        "root_cause": [
          {}
        ],
        "suppressed": [
          {}
        ]
      }
    ],
    "total": 42.0,
    "successful": 42.0,
    "failed": 42.0
  },
  "cluster_name": "string",
  "nodes": {
    "additionalProperty1": {
      "rest_actions": {
        "additionalProperty1": 42.0,
        "additionalProperty2": 42.0
      },
      "": 42.0,
      "aggregations": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      }
    },
    "additionalProperty2": {
      "rest_actions": {
        "additionalProperty1": 42.0,
        "additionalProperty2": 42.0
      },
      "": 42.0,
      "aggregations": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      }
    }
  }
}








Get feature usage information Added in 6.0.0

GET /_nodes/{node_id}/usage/{metric}

Path parameters

  • node_id string | array[string] Required

    A comma-separated list of node IDs or names to limit the returned information; use _local to return information from the node you're connecting to, leave empty to get information from all nodes

  • metric string | array[string] Required

    Limits the information returned to the specific metrics. A comma-separated list of the following options: _all, rest_actions.

Query parameters

  • timeout string

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

Responses

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

      Additional properties are allowed.

      Hide _nodes attributes Show _nodes attributes object
      • failures array[object]
        Hide failures attributes Show failures attributes object
        • type string Required

          The type of error

        • reason string

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

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

        • Additional properties are allowed.

        • root_cause array[object]

          Additional properties are allowed.

        • suppressed array[object]

          Additional properties are allowed.

      • total number Required

        Total number of nodes selected by the request.

      • successful number Required

        Number of nodes that responded successfully to the request.

      • failed number Required

        Number of nodes that rejected the request or failed to respond. If this value is not 0, a reason for the rejection or failure is included in the response.

    • cluster_name string Required
    • nodes object Required
      Hide nodes attribute Show nodes attribute object
      • * object Additional properties

        Additional properties are allowed.

        Hide * attributes Show * attributes object
        • rest_actions object Required
          Hide rest_actions attribute Show rest_actions attribute object
          • * number Additional properties
        • since number

          Time unit for milliseconds

        • Time unit for milliseconds

        • aggregations object Required
          Hide aggregations attribute Show aggregations attribute object
          • * object Additional properties

            Additional properties are allowed.

GET /_nodes/{node_id}/usage/{metric}
curl \
 --request GET http://api.example.com/_nodes/{node_id}/usage/{metric}
Response examples (200)
{
  "_nodes": {
    "failures": [
      {
        "type": "string",
        "reason": "string",
        "stack_trace": "string",
        "caused_by": {},
        "root_cause": [
          {}
        ],
        "suppressed": [
          {}
        ]
      }
    ],
    "total": 42.0,
    "successful": 42.0,
    "failed": 42.0
  },
  "cluster_name": "string",
  "nodes": {
    "additionalProperty1": {
      "rest_actions": {
        "additionalProperty1": 42.0,
        "additionalProperty2": 42.0
      },
      "": 42.0,
      "aggregations": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      }
    },
    "additionalProperty2": {
      "rest_actions": {
        "additionalProperty1": 42.0,
        "additionalProperty2": 42.0
      },
      "": 42.0,
      "aggregations": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      }
    }
  }
}








Connector

The connector and sync jobs APIs provide a convenient way to create and manage Elastic connectors and sync jobs in an internal index. Connectors are Elasticsearch integrations for syncing content from third-party data sources, which can be deployed on Elastic Cloud or hosted on your own infrastructure. This API provides an alternative to relying solely on Kibana UI for connector and sync job management. The API comes with a set of validations and assertions to ensure that the state representation in the internal index remains valid. This API requires the manage_connector privilege or, for read-only endpoints, the monitor_connector privilege.

Check in a connector Technical preview

PUT /_connector/{connector_id}/_check_in

Update the last_seen field in the connector and set it to the current timestamp.

Path parameters

  • connector_id string Required

    The unique identifier of the connector to be checked in

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}/_check_in
curl \
 --request PUT http://api.example.com/_connector/{connector_id}/_check_in
Response examples (200)
{
    "result": "updated"
}
















Get all connectors Beta

GET /_connector

Get information about all connectors.

Query parameters

  • from number

    Starting offset (default: 0)

  • size number

    Specifies a max number of results to get

  • index_name string | array[string]

    A comma-separated list of connector index names to fetch connector documents for

  • connector_name string | array[string]

    A comma-separated list of connector names to fetch connector documents for

  • service_type string | array[string]

    A comma-separated list of connector service types to fetch connector documents for

  • A flag to indicate if the desired connector should be fetched, even if it was soft-deleted.

  • query string

    A wildcard query string that filters connectors with matching name, description or index name

Responses

GET /_connector
curl \
 --request GET http://api.example.com/_connector
Response examples (200)
{
  "count": 42.0,
  "results": [
    {
      "api_key_id": "string",
      "api_key_secret_id": "string",
      "configuration": {
        "additionalProperty1": {
          "category": "string",
          "": 42.0,
          "depends_on": [
            {}
          ],
          "display": "textbox",
          "label": "string",
          "options": [
            {}
          ],
          "order": 42.0,
          "placeholder": "string",
          "required": true,
          "sensitive": true,
          "tooltip": "string",
          "type": "str",
          "ui_restrictions": [
            "string"
          ],
          "validations": [
            {}
          ],
          "value": {}
        },
        "additionalProperty2": {
          "category": "string",
          "": 42.0,
          "depends_on": [
            {}
          ],
          "display": "textbox",
          "label": "string",
          "options": [
            {}
          ],
          "order": 42.0,
          "placeholder": "string",
          "required": true,
          "sensitive": true,
          "tooltip": "string",
          "type": "str",
          "ui_restrictions": [
            "string"
          ],
          "validations": [
            {}
          ],
          "value": {}
        }
      },
      "custom_scheduling": {
        "additionalProperty1": {
          "configuration_overrides": {
            "max_crawl_depth": 42.0,
            "sitemap_discovery_disabled": true,
            "domain_allowlist": [
              "string"
            ],
            "sitemap_urls": [
              "string"
            ],
            "seed_urls": [
              "string"
            ]
          },
          "enabled": true,
          "interval": "string",
          "": "string",
          "name": "string"
        },
        "additionalProperty2": {
          "configuration_overrides": {
            "max_crawl_depth": 42.0,
            "sitemap_discovery_disabled": true,
            "domain_allowlist": [
              "string"
            ],
            "sitemap_urls": [
              "string"
            ],
            "seed_urls": [
              "string"
            ]
          },
          "enabled": true,
          "interval": "string",
          "": "string",
          "name": "string"
        }
      },
      "deleted": true,
      "description": "string",
      "error": "string",
      "features": {
        "document_level_security": {
          "enabled": true
        },
        "incremental_sync": {
          "enabled": true
        },
        "native_connector_api_keys": {
          "enabled": true
        },
        "sync_rules": {
          "advanced": {
            "enabled": true
          },
          "basic": {
            "enabled": true
          }
        }
      },
      "filtering": [
        {
          "active": {
            "advanced_snippet": {},
            "rules": [
              {}
            ],
            "validation": {}
          },
          "domain": "string",
          "draft": {
            "advanced_snippet": {},
            "rules": [
              {}
            ],
            "validation": {}
          }
        }
      ],
      "id": "string",
      "index_name": "string",
      "is_native": true,
      "language": "string",
      "last_access_control_sync_error": "string",
      "": "string",
      "last_access_control_sync_status": "canceling",
      "last_deleted_document_count": 42.0,
      "last_indexed_document_count": 42.0,
      "last_sync_error": "string",
      "last_sync_status": "canceling",
      "name": "string",
      "pipeline": {
        "extract_binary_content": true,
        "name": "string",
        "reduce_whitespace": true,
        "run_ml_inference": true
      },
      "scheduling": {
        "access_control": {
          "enabled": true,
          "interval": "string"
        },
        "full": {
          "enabled": true,
          "interval": "string"
        },
        "incremental": {
          "enabled": true,
          "interval": "string"
        }
      },
      "service_type": "string",
      "status": "created",
      "sync_cursor": {},
      "sync_now": true
    }
  ]
}




Create a connector Beta

POST /_connector

Connectors are Elasticsearch integrations that bring content from third-party data sources, which can be deployed on Elastic Cloud or hosted on your own infrastructure. Elastic managed connectors (Native connectors) are a managed service on Elastic Cloud. Self-managed connectors (Connector clients) are self-managed on your infrastructure.

application/json

Body

Responses

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

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

    • id string Required
POST /_connector
curl \
 --request POST http://api.example.com/_connector \
 --header "Content-Type: application/json" \
 --data '{"description":"string","index_name":"string","is_native":true,"language":"string","name":"string","service_type":"string"}'
Request examples
{
  "description": "string",
  "index_name": "string",
  "is_native": true,
  "language": "string",
  "name": "string",
  "service_type": "string"
}
Response examples (200)
{
  "result": "created",
  "id": "string"
}

Cancel a connector sync job Beta

PUT /_connector/_sync_job/{connector_sync_job_id}/_cancel

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

Path parameters

Responses

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

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

PUT /_connector/_sync_job/{connector_sync_job_id}/_cancel
curl \
 --request PUT http://api.example.com/_connector/_sync_job/{connector_sync_job_id}/_cancel
Response examples (200)
{
  "result": "created"
}

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

Responses

  • 200 application/json

    Additional properties are allowed.

PUT /_connector/_sync_job/{connector_sync_job_id}/_check_in
curl \
 --request PUT http://api.example.com/_connector/_sync_job/{connector_sync_job_id}/_check_in
Response examples (200)
{}

Claim a connector sync job Technical preview

PUT /_connector/_sync_job/{connector_sync_job_id}/_claim

This action updates the job status to in_progress and sets the last_seen and started_at timestamps to the current time. Additionally, it can set the sync_cursor property for the sync job.

This API is not intended for direct connector management by users. It supports the implementation of services that utilize the connector protocol to communicate with Elasticsearch.

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

Path parameters

application/json

Body Required

  • The cursor object from the last incremental sync job. This should reference the sync_cursor field in the connector state for which the job runs.

    Additional properties are allowed.

  • worker_hostname string Required

    The host name of the current system that will run the job.

Responses

  • 200 application/json

    Additional properties are allowed.

PUT /_connector/_sync_job/{connector_sync_job_id}/_claim
curl \
 --request PUT http://api.example.com/_connector/_sync_job/{connector_sync_job_id}/_claim \
 --header "Content-Type: application/json" \
 --data '{"sync_cursor":{},"worker_hostname":"string"}'
Request examples
{
  "sync_cursor": {},
  "worker_hostname": "string"
}
Response examples (200)
{}








Set a connector sync job error Technical preview

PUT /_connector/_sync_job/{connector_sync_job_id}/_error

Set the error field for a connector sync job and set its status to error.

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

application/json

Body Required

  • error string Required

    The error for the connector sync job error field.

Responses

  • 200 application/json

    Additional properties are allowed.

PUT /_connector/_sync_job/{connector_sync_job_id}/_error
curl \
 --request PUT http://api.example.com/_connector/_sync_job/{connector_sync_job_id}/_error \
 --header "Content-Type: application/json" \
 --data '"{\n    \"error\": \"some-error\"\n}"'
Request example
{
    "error": "some-error"
}
Response examples (200)
{}




Create a connector sync job Beta

POST /_connector/_sync_job

Create a connector sync job document in the internal index and initialize its counters and timestamps with default values.

application/json

Body Required

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • id string Required
POST /_connector/_sync_job
curl \
 --request POST http://api.example.com/_connector/_sync_job \
 --header "Content-Type: application/json" \
 --data '"{\n  \"id\": \"connector-id\",\n  \"job_type\": \"full\",\n  \"trigger_method\": \"on_demand\"\n}"'
Request example
{
  "id": "connector-id",
  "job_type": "full",
  "trigger_method": "on_demand"
}
Response examples (200)
{
  "id": "string"
}








































Update the connector is_native flag Beta

PUT /_connector/{connector_id}/_native

Path parameters

  • connector_id string Required

    The unique identifier of the connector to be updated

application/json

Body 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}/_native
curl \
 --request PUT http://api.example.com/_connector/{connector_id}/_native \
 --header "Content-Type: application/json" \
 --data '{"is_native":true}'
Request examples
{
  "is_native": true
}
Response examples (200)
{
  "result": "created"
}

Update the connector pipeline Beta

PUT /_connector/{connector_id}/_pipeline

When you create a new connector, the configuration of an ingest pipeline is populated with default settings.

Path parameters

  • connector_id string Required

    The unique identifier of the connector to be updated

application/json

Body 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}/_pipeline
curl \
 --request PUT http://api.example.com/_connector/{connector_id}/_pipeline \
 --header "Content-Type: application/json" \
 --data '"{\n    \"pipeline\": {\n        \"extract_binary_content\": true,\n        \"name\": \"my-connector-pipeline\",\n        \"reduce_whitespace\": true,\n        \"run_ml_inference\": true\n    }\n}"'
Request example
{
    "pipeline": {
        "extract_binary_content": true,
        "name": "my-connector-pipeline",
        "reduce_whitespace": true,
        "run_ml_inference": true
    }
}
Response examples (200)
{
  "result": "updated"
}

Update the connector scheduling Beta

PUT /_connector/{connector_id}/_scheduling

Path parameters

  • connector_id string Required

    The unique identifier of the connector to be updated

application/json

Body Required

  • scheduling object Required

    Additional properties are allowed.

    Hide scheduling attributes Show scheduling attributes object
    • Additional properties are allowed.

      Hide access_control attributes Show access_control attributes object
      • enabled boolean Required
      • interval string Required

        The interval is expressed using the crontab syntax

    • full object

      Additional properties are allowed.

      Hide full attributes Show full attributes object
      • enabled boolean Required
      • interval string Required

        The interval is expressed using the crontab syntax

    • Additional properties are allowed.

      Hide incremental attributes Show incremental attributes object
      • enabled boolean Required
      • interval string Required

        The interval is expressed using the crontab syntax

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}/_scheduling
curl \
 --request PUT http://api.example.com/_connector/{connector_id}/_scheduling \
 --header "Content-Type: application/json" \
 --data '"{\n    \"scheduling\": {\n        \"access_control\": {\n            \"enabled\": true,\n            \"interval\": \"0 10 0 * * ?\"\n        },\n        \"full\": {\n            \"enabled\": true,\n            \"interval\": \"0 20 0 * * ?\"\n        },\n        \"incremental\": {\n            \"enabled\": false,\n            \"interval\": \"0 30 0 * * ?\"\n        }\n    }\n}"'
{
    "scheduling": {
        "access_control": {
            "enabled": true,
            "interval": "0 10 0 * * ?"
        },
        "full": {
            "enabled": true,
            "interval": "0 20 0 * * ?"
        },
        "incremental": {
            "enabled": false,
            "interval": "0 30 0 * * ?"
        }
    }
}
{
    "scheduling": {
        "full": {
            "enabled": true,
            "interval": "0 10 0 * * ?"
        }
    }
}
Response examples (200)
{
  "result": "updated"
}




Update the connector status Technical preview

PUT /_connector/{connector_id}/_status

Path parameters

  • connector_id string Required

    The unique identifier of the connector to be updated

application/json

Body Required

  • status string Required

    Values are created, needs_configuration, configured, connected, or error.

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}/_status
curl \
 --request PUT http://api.example.com/_connector/{connector_id}/_status \
 --header "Content-Type: application/json" \
 --data '"{\n    \"status\": \"needs_configuration\"\n}"'
Request example
{
    "status": "needs_configuration"
}
Response examples (200)
{
  "result": "updated"
}









Delete auto-follow patterns Added in 6.5.0

DELETE /_ccr/auto_follow/{name}

Delete a collection of cross-cluster replication auto-follow patterns.

Path parameters

  • name string Required

    The auto-follow pattern collection to delete.

Query parameters

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

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 /_ccr/auto_follow/{name}
curl \
 --request DELETE http://api.example.com/_ccr/auto_follow/{name}
Response examples (200)
A successful response from `DELETE /_ccr/auto_follow/my_auto_follow_pattern`, which deletes an auto-follow pattern.
{
  "acknowledged" : true
}
















Get auto-follow patterns Added in 6.5.0

GET /_ccr/auto_follow

Get cross-cluster replication auto-follow patterns.

Query parameters

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

Responses

GET /_ccr/auto_follow
curl \
 --request GET http://api.example.com/_ccr/auto_follow
Response examples (200)
A successful response from `GET /_ccr/auto_follow/my_auto_follow_pattern`, which gets auto-follow patterns.
{
  "patterns": [
    {
      "name": "my_auto_follow_pattern",
      "pattern": {
        "active": true,
        "remote_cluster" : "remote_cluster",
        "leader_index_patterns" :
        [
          "leader_index*"
        ],
        "leader_index_exclusion_patterns":
        [
          "leader_index_001"
        ],
        "follow_index_pattern" : "{{leader_index}}-follower"
      }
    }
  ]
}

Pause an auto-follow pattern 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.

Path parameters

  • name string Required

    The name of the auto-follow pattern to pause.

Query parameters

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

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
curl \
 --request POST http://api.example.com/_ccr/auto_follow/{name}/pause
Response examples (200)
A successful response from `POST /_ccr/auto_follow/my_auto_follow_pattern/pause`, which pauses an auto-follow pattern.
{
  "acknowledged" : true
}





















Get data streams Added in 7.9.0

GET /_data_stream/{name}

Get information about one or more data streams.

Path parameters

  • name string | array[string] Required

    Comma-separated list of data stream names used to limit the request. Wildcard (*) expressions are supported. If omitted, all data streams are returned.

Query parameters

  • expand_wildcards string | array[string]

    Type of data stream that wildcard patterns can match. Supports comma-separated values, such as open,hidden.

  • If true, returns all relevant default configurations for the index template.

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

  • verbose boolean

    Whether the maximum timestamp for each data stream should be calculated and returned.

Responses

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

          Additional properties are allowed.

      • If true, the data stream allows custom routing on write request.

      • Additional properties are allowed.

        Hide failure_store attributes Show failure_store attributes object
      • generation number Required

        Current generation for the data stream. This number acts as a cumulative count of the stream’s rollovers, starting at 1.

      • hidden boolean Required

        If true, the data stream is hidden.

      • Values are Index Lifecycle Management, Data stream lifecycle, or Unmanaged.

      • prefer_ilm boolean Required

        Indicates if ILM should take precedence over DSL in case both are configured to managed this data stream.

      • indices array[object] Required

        Array of objects containing information about the data stream’s backing indices. The last item in this array contains information about the stream’s current write index.

        Hide indices attributes Show indices attributes object
      • Additional properties are allowed.

        Hide lifecycle attributes Show lifecycle attributes object
        • 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.

        • Additional properties are allowed.

          Hide downsampling attribute Show downsampling attribute object
          • rounds array[object] Required

            The list of downsampling rounds to execute as part of this downsampling configuration

        • enabled boolean

          If defined, it turns data stream lifecycle on/off (true/false) for this data stream. A data stream lifecycle that's disabled (enabled: false) will have no effect on the data stream.

        • rollover object

          Additional properties are allowed.

          Hide rollover attributes Show rollover attributes object
      • name string Required
      • replicated boolean

        If true, the data stream is created and managed by cross-cluster replication and the local cluster can not write into this data stream or change its mappings.

      • rollover_on_write boolean Required

        If true, the next write to this data stream will trigger a rollover first and the document will be indexed in the new backing index. If the rollover fails the indexing request will fail too.

      • status string Required

        Values are green, GREEN, yellow, YELLOW, red, or RED.

      • system boolean

        If true, the data stream is created and managed by an Elastic stack component and cannot be modified through normal user interaction.

      • template string Required
      • timestamp_field object Required

        Additional properties are allowed.

        Hide timestamp_field attribute Show timestamp_field attribute object
        • name string Required

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

GET /_data_stream/{name}
curl \
 --request GET http://api.example.com/_data_stream/{name}
Response examples (200)
A successful response for retrieving information about a data stream.
{
  "data_streams": [
    {
      "name": "my-data-stream",
      "timestamp_field": {
        "name": "@timestamp"
      },
      "indices": [
        {
          "index_name": ".ds-my-data-stream-2099.03.07-000001",
          "index_uuid": "xCEhwsp8Tey0-FLNFYVwSg",
          "prefer_ilm": true,
          "ilm_policy": "my-lifecycle-policy",
          "managed_by": "Index Lifecycle Management"
        },
        {
          "index_name": ".ds-my-data-stream-2099.03.08-000002",
          "index_uuid": "PA_JquKGSiKcAKBA8DJ5gw",
          "prefer_ilm": true,
          "ilm_policy": "my-lifecycle-policy",
          "managed_by": "Index Lifecycle Management"
        }
      ],
      "generation": 2,
      "_meta": {
        "my-meta-field": "foo"
      },
      "status": "GREEN",
      "next_generation_managed_by": "Index Lifecycle Management",
      "prefer_ilm": true,
      "template": "my-index-template",
      "ilm_policy": "my-lifecycle-policy",
      "hidden": false,
      "system": false,
      "allow_custom_routing": false,
      "replicated": false,
      "rollover_on_write": false
    },
    {
      "name": "my-data-stream-two",
      "timestamp_field": {
        "name": "@timestamp"
      },
      "indices": [
        {
          "index_name": ".ds-my-data-stream-two-2099.03.08-000001",
          "index_uuid": "3liBu2SYS5axasRt6fUIpA",
          "prefer_ilm": true,
          "ilm_policy": "my-lifecycle-policy",
          "managed_by": "Index Lifecycle Management"
        }
      ],
      "generation": 1,
      "_meta": {
        "my-meta-field": "foo"
      },
      "status": "YELLOW",
      "next_generation_managed_by": "Index Lifecycle Management",
      "prefer_ilm": true,
      "template": "my-index-template",
      "ilm_policy": "my-lifecycle-policy",
      "hidden": false,
      "system": false,
      "allow_custom_routing": false,
      "replicated": false,
      "rollover_on_write": false
    }
  ]
}
























Downsample an index Technical preview

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

    Additional properties are allowed.

POST /{index}/_downsample/{target_index}
curl \
 --request POST http://api.example.com/{index}/_downsample/{target_index} \
 --header "Content-Type: application/json" \
 --data '{"fixed_interval":"string"}'
Request examples
{
  "fixed_interval": "string"
}
Response examples (200)
{}








Get data streams Added in 7.9.0

GET /_data_stream

Get information about one or more data streams.

Query parameters

  • expand_wildcards string | array[string]

    Type of data stream that wildcard patterns can match. Supports comma-separated values, such as open,hidden.

  • If true, returns all relevant default configurations for the index template.

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

  • verbose boolean

    Whether the maximum timestamp for each data stream should be calculated and returned.

Responses

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

          Additional properties are allowed.

      • If true, the data stream allows custom routing on write request.

      • Additional properties are allowed.

        Hide failure_store attributes Show failure_store attributes object
      • generation number Required

        Current generation for the data stream. This number acts as a cumulative count of the stream’s rollovers, starting at 1.

      • hidden boolean Required

        If true, the data stream is hidden.

      • Values are Index Lifecycle Management, Data stream lifecycle, or Unmanaged.

      • prefer_ilm boolean Required

        Indicates if ILM should take precedence over DSL in case both are configured to managed this data stream.

      • indices array[object] Required

        Array of objects containing information about the data stream’s backing indices. The last item in this array contains information about the stream’s current write index.

        Hide indices attributes Show indices attributes object
      • Additional properties are allowed.

        Hide lifecycle attributes Show lifecycle attributes object
        • 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.

        • Additional properties are allowed.

          Hide downsampling attribute Show downsampling attribute object
          • rounds array[object] Required

            The list of downsampling rounds to execute as part of this downsampling configuration

        • enabled boolean

          If defined, it turns data stream lifecycle on/off (true/false) for this data stream. A data stream lifecycle that's disabled (enabled: false) will have no effect on the data stream.

        • rollover object

          Additional properties are allowed.

          Hide rollover attributes Show rollover attributes object
      • name string Required
      • replicated boolean

        If true, the data stream is created and managed by cross-cluster replication and the local cluster can not write into this data stream or change its mappings.

      • rollover_on_write boolean Required

        If true, the next write to this data stream will trigger a rollover first and the document will be indexed in the new backing index. If the rollover fails the indexing request will fail too.

      • status string Required

        Values are green, GREEN, yellow, YELLOW, red, or RED.

      • system boolean

        If true, the data stream is created and managed by an Elastic stack component and cannot be modified through normal user interaction.

      • template string Required
      • timestamp_field object Required

        Additional properties are allowed.

        Hide timestamp_field attribute Show timestamp_field attribute object
        • name string Required

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

GET /_data_stream
curl \
 --request GET http://api.example.com/_data_stream
Response examples (200)
A successful response for retrieving information about a data stream.
{
  "data_streams": [
    {
      "name": "my-data-stream",
      "timestamp_field": {
        "name": "@timestamp"
      },
      "indices": [
        {
          "index_name": ".ds-my-data-stream-2099.03.07-000001",
          "index_uuid": "xCEhwsp8Tey0-FLNFYVwSg",
          "prefer_ilm": true,
          "ilm_policy": "my-lifecycle-policy",
          "managed_by": "Index Lifecycle Management"
        },
        {
          "index_name": ".ds-my-data-stream-2099.03.08-000002",
          "index_uuid": "PA_JquKGSiKcAKBA8DJ5gw",
          "prefer_ilm": true,
          "ilm_policy": "my-lifecycle-policy",
          "managed_by": "Index Lifecycle Management"
        }
      ],
      "generation": 2,
      "_meta": {
        "my-meta-field": "foo"
      },
      "status": "GREEN",
      "next_generation_managed_by": "Index Lifecycle Management",
      "prefer_ilm": true,
      "template": "my-index-template",
      "ilm_policy": "my-lifecycle-policy",
      "hidden": false,
      "system": false,
      "allow_custom_routing": false,
      "replicated": false,
      "rollover_on_write": false
    },
    {
      "name": "my-data-stream-two",
      "timestamp_field": {
        "name": "@timestamp"
      },
      "indices": [
        {
          "index_name": ".ds-my-data-stream-two-2099.03.08-000001",
          "index_uuid": "3liBu2SYS5axasRt6fUIpA",
          "prefer_ilm": true,
          "ilm_policy": "my-lifecycle-policy",
          "managed_by": "Index Lifecycle Management"
        }
      ],
      "generation": 1,
      "_meta": {
        "my-meta-field": "foo"
      },
      "status": "YELLOW",
      "next_generation_managed_by": "Index Lifecycle Management",
      "prefer_ilm": true,
      "template": "my-index-template",
      "ilm_policy": "my-lifecycle-policy",
      "hidden": false,
      "system": false,
      "allow_custom_routing": false,
      "replicated": false,
      "rollover_on_write": false
    }
  ]
}








Promote a data stream 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

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

Responses

  • 200 application/json

    Additional properties are allowed.

POST /_data_stream/_promote/{name}
curl \
 --request POST http://api.example.com/_data_stream/_promote/{name}
Response examples (200)
{}

Bulk index or delete documents

PUT /_bulk

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Client suppport for bulk requests

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

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

Submitting bulk requests with cURL

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

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

Optimistic concurrency control

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

Versioning

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

Routing

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

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

Wait for active shards

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

Refresh

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

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

Query parameters

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

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

  • pipeline string

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

  • refresh string

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

    Values are true, false, or wait_for.

  • routing string

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

  • _source boolean | string | array[string]

    Indicates whether to return the _source field (true or false) or contains a list of fields to return.

  • _source_excludes string | array[string]

    A comma-separated list of source fields to exclude from the response. You can also use this parameter to exclude fields from the subset specified in _source_includes query parameter. If the _source parameter is false, this parameter is ignored.

  • _source_includes string | array[string]

    A comma-separated list of source fields to include in the response. If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the _source_excludes query parameter. If the _source parameter is false, this parameter is ignored.

  • timeout string

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

  • wait_for_active_shards number | string

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

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

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

application/json

Body object Required

One of:
  • index object

    Additional properties are allowed.

    Hide index attributes Show index attributes object
    • _id string
    • _index string
    • routing string
    • version number
    • Values are internal, external, external_gte, or force.

    • A map from the full name of fields to the name of dynamic templates. It defaults to an empty map. If a name matches a dynamic template, that template will be applied regardless of other match predicates defined in the template. If a field is already defined in the mapping, then this parameter won't be used.

      Hide dynamic_templates attribute Show dynamic_templates attribute object
      • * string Additional properties
    • pipeline string

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

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

  • create object

    Additional properties are allowed.

    Hide create attributes Show create attributes object
    • _id string
    • _index string
    • routing string
    • version number
    • Values are internal, external, external_gte, or force.

    • A map from the full name of fields to the name of dynamic templates. It defaults to an empty map. If a name matches a dynamic template, that template will be applied regardless of other match predicates defined in the template. If a field is already defined in the mapping, then this parameter won't be used.

      Hide dynamic_templates attribute Show dynamic_templates attribute object
      • * string Additional properties
    • pipeline string

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

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

  • update object

    Additional properties are allowed.

    Hide update attributes Show update attributes object
  • delete object

    Additional properties are allowed.

    Hide delete attributes Show delete attributes object

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • errors boolean Required

      If true, one or more of the operations in the bulk request did not complete successfully.

    • items array[object] Required

      The result of each operation in the bulk request, in the order they were submitted.

      Hide items attribute Show items attribute object
      • * object Additional properties

        Additional properties are allowed.

        Hide * attributes Show * attributes object
        • _id string | null

          The document ID associated with the operation.

        • _index string Required

          The name of the index associated with the operation. If the operation targeted a data stream, this is the backing index into which the document was written.

        • status number Required

          The HTTP status code returned for the operation.

        • Values are not_applicable_or_unknown, used, not_enabled, or failed.

        • error object

          Additional properties are allowed.

          Hide error attributes Show error attributes object
          • type string Required

            The type of error

          • reason string

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

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

          • Additional properties are allowed.

          • root_cause array[object]

            Additional properties are allowed.

          • suppressed array[object]

            Additional properties are allowed.

        • The primary term assigned to the document for the operation. This property is returned only for successful operations.

        • result string

          The result of the operation. Successful values are created, deleted, and updated.

        • _seq_no number
        • _shards object

          Additional properties are allowed.

          Hide _shards attributes Show _shards attributes object
        • _version number
        • get object

          Additional properties are allowed.

          Hide get attributes Show get attributes object
          • fields object
            Hide fields attribute Show fields attribute object
            • * object Additional properties

              Additional properties are allowed.

          • found boolean Required
          • _seq_no number
          • _routing string
          • _source object
            Hide _source attribute Show _source attribute object
            • * object Additional properties

              Additional properties are allowed.

    • took number Required

      The length of time, in milliseconds, it took to process the bulk request.

PUT /_bulk
curl \
 --request PUT http://api.example.com/_bulk \
 --header "Content-Type: application/json" \
 --data '"{ \"index\" : { \"_index\" : \"test\", \"_id\" : \"1\" } }\n{ \"field1\" : \"value1\" }\n{ \"delete\" : { \"_index\" : \"test\", \"_id\" : \"2\" } }\n{ \"create\" : { \"_index\" : \"test\", \"_id\" : \"3\" } }\n{ \"field1\" : \"value3\" }\n{ \"update\" : {\"_id\" : \"1\", \"_index\" : \"test\"} }\n{ \"doc\" : {\"field2\" : \"value2\"} }"'
Run `POST _bulk` to perform multiple operations.
{ "index" : { "_index" : "test", "_id" : "1" } }
{ "field1" : "value1" }
{ "delete" : { "_index" : "test", "_id" : "2" } }
{ "create" : { "_index" : "test", "_id" : "3" } }
{ "field1" : "value3" }
{ "update" : {"_id" : "1", "_index" : "test"} }
{ "doc" : {"field2" : "value2"} }
When you run `POST _bulk` and use the `update` action, you can use `retry_on_conflict` as a field in the action itself (not in the extra payload line) to specify how many times an update should be retried in the case of a version conflict.
{ "update" : {"_id" : "1", "_index" : "index1", "retry_on_conflict" : 3} }
{ "doc" : {"field" : "value"} }
{ "update" : { "_id" : "0", "_index" : "index1", "retry_on_conflict" : 3} }
{ "script" : { "source": "ctx._source.counter += params.param1", "lang" : "painless", "params" : {"param1" : 1}}, "upsert" : {"counter" : 1}}
{ "update" : {"_id" : "2", "_index" : "index1", "retry_on_conflict" : 3} }
{ "doc" : {"field" : "value"}, "doc_as_upsert" : true }
{ "update" : {"_id" : "3", "_index" : "index1", "_source" : true} }
{ "doc" : {"field" : "value"} }
{ "update" : {"_id" : "4", "_index" : "index1"} }
{ "doc" : {"field" : "value"}, "_source": true}
To return only information about failed operations, run `POST /_bulk?filter_path=items.*.error`.
{ "update": {"_id": "5", "_index": "index1"} }
{ "doc": {"my_field": "foo"} }
{ "update": {"_id": "6", "_index": "index1"} }
{ "doc": {"my_field": "foo"} }
{ "create": {"_id": "7", "_index": "index1"} }
{ "my_field": "foo" }
Run `POST /_bulk` to perform a bulk request that consists of index and create actions with the `dynamic_templates` parameter. The bulk request creates two new fields `work_location` and `home_location` with type `geo_point` according to the `dynamic_templates` parameter. However, the `raw_location` field is created using default dynamic mapping rules, as a text field in that case since it is supplied as a string in the JSON document.
{ "index" : { "_index" : "my_index", "_id" : "1", "dynamic_templates": {"work_location": "geo_point"}} }
{ "field" : "value1", "work_location": "41.12,-71.34", "raw_location": "41.12,-71.34"}
{ "create" : { "_index" : "my_index", "_id" : "2", "dynamic_templates": {"home_location": "geo_point"}} }
{ "field" : "value2", "home_location": "41.12,-71.34"}
Response examples (200)
{
   "took": 30,
   "errors": false,
   "items": [
      {
         "index": {
            "_index": "test",
            "_id": "1",
            "_version": 1,
            "result": "created",
            "_shards": {
               "total": 2,
               "successful": 1,
               "failed": 0
            },
            "status": 201,
            "_seq_no" : 0,
            "_primary_term": 1
         }
      },
      {
         "delete": {
            "_index": "test",
            "_id": "2",
            "_version": 1,
            "result": "not_found",
            "_shards": {
               "total": 2,
               "successful": 1,
               "failed": 0
            },
            "status": 404,
            "_seq_no" : 1,
            "_primary_term" : 2
         }
      },
      {
         "create": {
            "_index": "test",
            "_id": "3",
            "_version": 1,
            "result": "created",
            "_shards": {
               "total": 2,
               "successful": 1,
               "failed": 0
            },
            "status": 201,
            "_seq_no" : 2,
            "_primary_term" : 3
         }
      },
      {
         "update": {
            "_index": "test",
            "_id": "1",
            "_version": 2,
            "result": "updated",
            "_shards": {
                "total": 2,
                "successful": 1,
                "failed": 0
            },
            "status": 200,
            "_seq_no" : 3,
            "_primary_term" : 4
         }
      }
   ]
}
If you run `POST /_bulk` with operations that update non-existent documents, the operations cannot complete successfully. The API returns a response with an `errors` property value `true`. The response also includes an error object for any failed operations. The error object contains additional information about the failure, such as the error type and reason.
{
  "took": 486,
  "errors": true,
  "items": [
    {
      "update": {
        "_index": "index1",
        "_id": "5",
        "status": 404,
        "error": {
          "type": "document_missing_exception",
          "reason": "[5]: document missing",
          "index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
          "shard": "0",
          "index": "index1"
        }
      }
    },
    {
      "update": {
        "_index": "index1",
        "_id": "6",
        "status": 404,
        "error": {
          "type": "document_missing_exception",
          "reason": "[6]: document missing",
          "index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
          "shard": "0",
          "index": "index1"
        }
      }
    },
    {
      "create": {
        "_index": "index1",
        "_id": "7",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 2,
          "successful": 1,
          "failed": 0
        },
        "_seq_no": 0,
        "_primary_term": 1,
        "status": 201
      }
    }
  ]
}
An example response from `POST /_bulk?filter_path=items.*.error`, which returns only information about failed operations.
{
  "items": [
    {
      "update": {
        "error": {
          "type": "document_missing_exception",
          "reason": "[5]: document missing",
          "index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
          "shard": "0",
          "index": "index1"
        }
      }
    },
    {
      "update": {
        "error": {
          "type": "document_missing_exception",
          "reason": "[6]: document missing",
          "index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
          "shard": "0",
          "index": "index1"
        }
      }
    }
  ]
}

Bulk index or delete documents

POST /_bulk

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Client suppport for bulk requests

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

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

Submitting bulk requests with cURL

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

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

Optimistic concurrency control

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

Versioning

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

Routing

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

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

Wait for active shards

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

Refresh

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

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

Query parameters

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

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

  • pipeline string

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

  • refresh string

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

    Values are true, false, or wait_for.

  • routing string

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

  • _source boolean | string | array[string]

    Indicates whether to return the _source field (true or false) or contains a list of fields to return.

  • _source_excludes string | array[string]

    A comma-separated list of source fields to exclude from the response. You can also use this parameter to exclude fields from the subset specified in _source_includes query parameter. If the _source parameter is false, this parameter is ignored.

  • _source_includes string | array[string]

    A comma-separated list of source fields to include in the response. If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the _source_excludes query parameter. If the _source parameter is false, this parameter is ignored.

  • timeout string

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

  • wait_for_active_shards number | string

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

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

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

application/json

Body object Required

One of:
  • index object

    Additional properties are allowed.

    Hide index attributes Show index attributes object
    • _id string
    • _index string
    • routing string
    • version number
    • Values are internal, external, external_gte, or force.

    • A map from the full name of fields to the name of dynamic templates. It defaults to an empty map. If a name matches a dynamic template, that template will be applied regardless of other match predicates defined in the template. If a field is already defined in the mapping, then this parameter won't be used.

      Hide dynamic_templates attribute Show dynamic_templates attribute object
      • * string Additional properties
    • pipeline string

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

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

  • create object

    Additional properties are allowed.

    Hide create attributes Show create attributes object
    • _id string
    • _index string
    • routing string
    • version number
    • Values are internal, external, external_gte, or force.

    • A map from the full name of fields to the name of dynamic templates. It defaults to an empty map. If a name matches a dynamic template, that template will be applied regardless of other match predicates defined in the template. If a field is already defined in the mapping, then this parameter won't be used.

      Hide dynamic_templates attribute Show dynamic_templates attribute object
      • * string Additional properties
    • pipeline string

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

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

  • update object

    Additional properties are allowed.

    Hide update attributes Show update attributes object
  • delete object

    Additional properties are allowed.

    Hide delete attributes Show delete attributes object

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • errors boolean Required

      If true, one or more of the operations in the bulk request did not complete successfully.

    • items array[object] Required

      The result of each operation in the bulk request, in the order they were submitted.

      Hide items attribute Show items attribute object
      • * object Additional properties

        Additional properties are allowed.

        Hide * attributes Show * attributes object
        • _id string | null

          The document ID associated with the operation.

        • _index string Required

          The name of the index associated with the operation. If the operation targeted a data stream, this is the backing index into which the document was written.

        • status number Required

          The HTTP status code returned for the operation.

        • Values are not_applicable_or_unknown, used, not_enabled, or failed.

        • error object

          Additional properties are allowed.

          Hide error attributes Show error attributes object
          • type string Required

            The type of error

          • reason string

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

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

          • Additional properties are allowed.

          • root_cause array[object]

            Additional properties are allowed.

          • suppressed array[object]

            Additional properties are allowed.

        • The primary term assigned to the document for the operation. This property is returned only for successful operations.

        • result string

          The result of the operation. Successful values are created, deleted, and updated.

        • _seq_no number
        • _shards object

          Additional properties are allowed.

          Hide _shards attributes Show _shards attributes object
        • _version number
        • get object

          Additional properties are allowed.

          Hide get attributes Show get attributes object
          • fields object
            Hide fields attribute Show fields attribute object
            • * object Additional properties

              Additional properties are allowed.

          • found boolean Required
          • _seq_no number
          • _routing string
          • _source object
            Hide _source attribute Show _source attribute object
            • * object Additional properties

              Additional properties are allowed.

    • took number Required

      The length of time, in milliseconds, it took to process the bulk request.

POST /_bulk
curl \
 --request POST http://api.example.com/_bulk \
 --header "Content-Type: application/json" \
 --data '"{ \"index\" : { \"_index\" : \"test\", \"_id\" : \"1\" } }\n{ \"field1\" : \"value1\" }\n{ \"delete\" : { \"_index\" : \"test\", \"_id\" : \"2\" } }\n{ \"create\" : { \"_index\" : \"test\", \"_id\" : \"3\" } }\n{ \"field1\" : \"value3\" }\n{ \"update\" : {\"_id\" : \"1\", \"_index\" : \"test\"} }\n{ \"doc\" : {\"field2\" : \"value2\"} }"'
Run `POST _bulk` to perform multiple operations.
{ "index" : { "_index" : "test", "_id" : "1" } }
{ "field1" : "value1" }
{ "delete" : { "_index" : "test", "_id" : "2" } }
{ "create" : { "_index" : "test", "_id" : "3" } }
{ "field1" : "value3" }
{ "update" : {"_id" : "1", "_index" : "test"} }
{ "doc" : {"field2" : "value2"} }
When you run `POST _bulk` and use the `update` action, you can use `retry_on_conflict` as a field in the action itself (not in the extra payload line) to specify how many times an update should be retried in the case of a version conflict.
{ "update" : {"_id" : "1", "_index" : "index1", "retry_on_conflict" : 3} }
{ "doc" : {"field" : "value"} }
{ "update" : { "_id" : "0", "_index" : "index1", "retry_on_conflict" : 3} }
{ "script" : { "source": "ctx._source.counter += params.param1", "lang" : "painless", "params" : {"param1" : 1}}, "upsert" : {"counter" : 1}}
{ "update" : {"_id" : "2", "_index" : "index1", "retry_on_conflict" : 3} }
{ "doc" : {"field" : "value"}, "doc_as_upsert" : true }
{ "update" : {"_id" : "3", "_index" : "index1", "_source" : true} }
{ "doc" : {"field" : "value"} }
{ "update" : {"_id" : "4", "_index" : "index1"} }
{ "doc" : {"field" : "value"}, "_source": true}
To return only information about failed operations, run `POST /_bulk?filter_path=items.*.error`.
{ "update": {"_id": "5", "_index": "index1"} }
{ "doc": {"my_field": "foo"} }
{ "update": {"_id": "6", "_index": "index1"} }
{ "doc": {"my_field": "foo"} }
{ "create": {"_id": "7", "_index": "index1"} }
{ "my_field": "foo" }
Run `POST /_bulk` to perform a bulk request that consists of index and create actions with the `dynamic_templates` parameter. The bulk request creates two new fields `work_location` and `home_location` with type `geo_point` according to the `dynamic_templates` parameter. However, the `raw_location` field is created using default dynamic mapping rules, as a text field in that case since it is supplied as a string in the JSON document.
{ "index" : { "_index" : "my_index", "_id" : "1", "dynamic_templates": {"work_location": "geo_point"}} }
{ "field" : "value1", "work_location": "41.12,-71.34", "raw_location": "41.12,-71.34"}
{ "create" : { "_index" : "my_index", "_id" : "2", "dynamic_templates": {"home_location": "geo_point"}} }
{ "field" : "value2", "home_location": "41.12,-71.34"}
Response examples (200)
{
   "took": 30,
   "errors": false,
   "items": [
      {
         "index": {
            "_index": "test",
            "_id": "1",
            "_version": 1,
            "result": "created",
            "_shards": {
               "total": 2,
               "successful": 1,
               "failed": 0
            },
            "status": 201,
            "_seq_no" : 0,
            "_primary_term": 1
         }
      },
      {
         "delete": {
            "_index": "test",
            "_id": "2",
            "_version": 1,
            "result": "not_found",
            "_shards": {
               "total": 2,
               "successful": 1,
               "failed": 0
            },
            "status": 404,
            "_seq_no" : 1,
            "_primary_term" : 2
         }
      },
      {
         "create": {
            "_index": "test",
            "_id": "3",
            "_version": 1,
            "result": "created",
            "_shards": {
               "total": 2,
               "successful": 1,
               "failed": 0
            },
            "status": 201,
            "_seq_no" : 2,
            "_primary_term" : 3
         }
      },
      {
         "update": {
            "_index": "test",
            "_id": "1",
            "_version": 2,
            "result": "updated",
            "_shards": {
                "total": 2,
                "successful": 1,
                "failed": 0
            },
            "status": 200,
            "_seq_no" : 3,
            "_primary_term" : 4
         }
      }
   ]
}
If you run `POST /_bulk` with operations that update non-existent documents, the operations cannot complete successfully. The API returns a response with an `errors` property value `true`. The response also includes an error object for any failed operations. The error object contains additional information about the failure, such as the error type and reason.
{
  "took": 486,
  "errors": true,
  "items": [
    {
      "update": {
        "_index": "index1",
        "_id": "5",
        "status": 404,
        "error": {
          "type": "document_missing_exception",
          "reason": "[5]: document missing",
          "index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
          "shard": "0",
          "index": "index1"
        }
      }
    },
    {
      "update": {
        "_index": "index1",
        "_id": "6",
        "status": 404,
        "error": {
          "type": "document_missing_exception",
          "reason": "[6]: document missing",
          "index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
          "shard": "0",
          "index": "index1"
        }
      }
    },
    {
      "create": {
        "_index": "index1",
        "_id": "7",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 2,
          "successful": 1,
          "failed": 0
        },
        "_seq_no": 0,
        "_primary_term": 1,
        "status": 201
      }
    }
  ]
}
An example response from `POST /_bulk?filter_path=items.*.error`, which returns only information about failed operations.
{
  "items": [
    {
      "update": {
        "error": {
          "type": "document_missing_exception",
          "reason": "[5]: document missing",
          "index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
          "shard": "0",
          "index": "index1"
        }
      }
    },
    {
      "update": {
        "error": {
          "type": "document_missing_exception",
          "reason": "[6]: document missing",
          "index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
          "shard": "0",
          "index": "index1"
        }
      }
    }
  ]
}

Bulk index or delete documents

PUT /{index}/_bulk

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Client suppport for bulk requests

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

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

Submitting bulk requests with cURL

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

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

Optimistic concurrency control

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

Versioning

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

Routing

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

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

Wait for active shards

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

Refresh

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

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

Path parameters

  • index string Required

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

Query parameters

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

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

  • pipeline string

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

  • refresh string

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

    Values are true, false, or wait_for.

  • routing string

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

  • _source boolean | string | array[string]

    Indicates whether to return the _source field (true or false) or contains a list of fields to return.

  • _source_excludes string | array[string]

    A comma-separated list of source fields to exclude from the response. You can also use this parameter to exclude fields from the subset specified in _source_includes query parameter. If the _source parameter is false, this parameter is ignored.

  • _source_includes string | array[string]

    A comma-separated list of source fields to include in the response. If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the _source_excludes query parameter. If the _source parameter is false, this parameter is ignored.

  • timeout string

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

  • wait_for_active_shards number | string

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

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

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

application/json

Body object Required

One of:
  • index object

    Additional properties are allowed.

    Hide index attributes Show index attributes object
    • _id string
    • _index string
    • routing string
    • version number
    • Values are internal, external, external_gte, or force.

    • A map from the full name of fields to the name of dynamic templates. It defaults to an empty map. If a name matches a dynamic template, that template will be applied regardless of other match predicates defined in the template. If a field is already defined in the mapping, then this parameter won't be used.

      Hide dynamic_templates attribute Show dynamic_templates attribute object
      • * string Additional properties
    • pipeline string

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

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

  • create object

    Additional properties are allowed.

    Hide create attributes Show create attributes object
    • _id string
    • _index string
    • routing string
    • version number
    • Values are internal, external, external_gte, or force.

    • A map from the full name of fields to the name of dynamic templates. It defaults to an empty map. If a name matches a dynamic template, that template will be applied regardless of other match predicates defined in the template. If a field is already defined in the mapping, then this parameter won't be used.

      Hide dynamic_templates attribute Show dynamic_templates attribute object
      • * string Additional properties
    • pipeline string

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

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

  • update object

    Additional properties are allowed.

    Hide update attributes Show update attributes object
  • delete object

    Additional properties are allowed.

    Hide delete attributes Show delete attributes object

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • errors boolean Required

      If true, one or more of the operations in the bulk request did not complete successfully.

    • items array[object] Required

      The result of each operation in the bulk request, in the order they were submitted.

      Hide items attribute Show items attribute object
      • * object Additional properties

        Additional properties are allowed.

        Hide * attributes Show * attributes object
        • _id string | null

          The document ID associated with the operation.

        • _index string Required

          The name of the index associated with the operation. If the operation targeted a data stream, this is the backing index into which the document was written.

        • status number Required

          The HTTP status code returned for the operation.

        • Values are not_applicable_or_unknown, used, not_enabled, or failed.

        • error object

          Additional properties are allowed.

          Hide error attributes Show error attributes object
          • type string Required

            The type of error

          • reason string

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

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

          • Additional properties are allowed.

          • root_cause array[object]

            Additional properties are allowed.

          • suppressed array[object]

            Additional properties are allowed.

        • The primary term assigned to the document for the operation. This property is returned only for successful operations.

        • result string

          The result of the operation. Successful values are created, deleted, and updated.

        • _seq_no number
        • _shards object

          Additional properties are allowed.

          Hide _shards attributes Show _shards attributes object
        • _version number
        • get object

          Additional properties are allowed.

          Hide get attributes Show get attributes object
          • fields object
            Hide fields attribute Show fields attribute object
            • * object Additional properties

              Additional properties are allowed.

          • found boolean Required
          • _seq_no number
          • _routing string
          • _source object
            Hide _source attribute Show _source attribute object
            • * object Additional properties

              Additional properties are allowed.

    • took number Required

      The length of time, in milliseconds, it took to process the bulk request.

PUT /{index}/_bulk
curl \
 --request PUT http://api.example.com/{index}/_bulk \
 --header "Content-Type: application/json" \
 --data '"{ \"index\" : { \"_index\" : \"test\", \"_id\" : \"1\" } }\n{ \"field1\" : \"value1\" }\n{ \"delete\" : { \"_index\" : \"test\", \"_id\" : \"2\" } }\n{ \"create\" : { \"_index\" : \"test\", \"_id\" : \"3\" } }\n{ \"field1\" : \"value3\" }\n{ \"update\" : {\"_id\" : \"1\", \"_index\" : \"test\"} }\n{ \"doc\" : {\"field2\" : \"value2\"} }"'
Run `POST _bulk` to perform multiple operations.
{ "index" : { "_index" : "test", "_id" : "1" } }
{ "field1" : "value1" }
{ "delete" : { "_index" : "test", "_id" : "2" } }
{ "create" : { "_index" : "test", "_id" : "3" } }
{ "field1" : "value3" }
{ "update" : {"_id" : "1", "_index" : "test"} }
{ "doc" : {"field2" : "value2"} }
When you run `POST _bulk` and use the `update` action, you can use `retry_on_conflict` as a field in the action itself (not in the extra payload line) to specify how many times an update should be retried in the case of a version conflict.
{ "update" : {"_id" : "1", "_index" : "index1", "retry_on_conflict" : 3} }
{ "doc" : {"field" : "value"} }
{ "update" : { "_id" : "0", "_index" : "index1", "retry_on_conflict" : 3} }
{ "script" : { "source": "ctx._source.counter += params.param1", "lang" : "painless", "params" : {"param1" : 1}}, "upsert" : {"counter" : 1}}
{ "update" : {"_id" : "2", "_index" : "index1", "retry_on_conflict" : 3} }
{ "doc" : {"field" : "value"}, "doc_as_upsert" : true }
{ "update" : {"_id" : "3", "_index" : "index1", "_source" : true} }
{ "doc" : {"field" : "value"} }
{ "update" : {"_id" : "4", "_index" : "index1"} }
{ "doc" : {"field" : "value"}, "_source": true}
To return only information about failed operations, run `POST /_bulk?filter_path=items.*.error`.
{ "update": {"_id": "5", "_index": "index1"} }
{ "doc": {"my_field": "foo"} }
{ "update": {"_id": "6", "_index": "index1"} }
{ "doc": {"my_field": "foo"} }
{ "create": {"_id": "7", "_index": "index1"} }
{ "my_field": "foo" }
Run `POST /_bulk` to perform a bulk request that consists of index and create actions with the `dynamic_templates` parameter. The bulk request creates two new fields `work_location` and `home_location` with type `geo_point` according to the `dynamic_templates` parameter. However, the `raw_location` field is created using default dynamic mapping rules, as a text field in that case since it is supplied as a string in the JSON document.
{ "index" : { "_index" : "my_index", "_id" : "1", "dynamic_templates": {"work_location": "geo_point"}} }
{ "field" : "value1", "work_location": "41.12,-71.34", "raw_location": "41.12,-71.34"}
{ "create" : { "_index" : "my_index", "_id" : "2", "dynamic_templates": {"home_location": "geo_point"}} }
{ "field" : "value2", "home_location": "41.12,-71.34"}
Response examples (200)
{
   "took": 30,
   "errors": false,
   "items": [
      {
         "index": {
            "_index": "test",
            "_id": "1",
            "_version": 1,
            "result": "created",
            "_shards": {
               "total": 2,
               "successful": 1,
               "failed": 0
            },
            "status": 201,
            "_seq_no" : 0,
            "_primary_term": 1
         }
      },
      {
         "delete": {
            "_index": "test",
            "_id": "2",
            "_version": 1,
            "result": "not_found",
            "_shards": {
               "total": 2,
               "successful": 1,
               "failed": 0
            },
            "status": 404,
            "_seq_no" : 1,
            "_primary_term" : 2
         }
      },
      {
         "create": {
            "_index": "test",
            "_id": "3",
            "_version": 1,
            "result": "created",
            "_shards": {
               "total": 2,
               "successful": 1,
               "failed": 0
            },
            "status": 201,
            "_seq_no" : 2,
            "_primary_term" : 3
         }
      },
      {
         "update": {
            "_index": "test",
            "_id": "1",
            "_version": 2,
            "result": "updated",
            "_shards": {
                "total": 2,
                "successful": 1,
                "failed": 0
            },
            "status": 200,
            "_seq_no" : 3,
            "_primary_term" : 4
         }
      }
   ]
}
If you run `POST /_bulk` with operations that update non-existent documents, the operations cannot complete successfully. The API returns a response with an `errors` property value `true`. The response also includes an error object for any failed operations. The error object contains additional information about the failure, such as the error type and reason.
{
  "took": 486,
  "errors": true,
  "items": [
    {
      "update": {
        "_index": "index1",
        "_id": "5",
        "status": 404,
        "error": {
          "type": "document_missing_exception",
          "reason": "[5]: document missing",
          "index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
          "shard": "0",
          "index": "index1"
        }
      }
    },
    {
      "update": {
        "_index": "index1",
        "_id": "6",
        "status": 404,
        "error": {
          "type": "document_missing_exception",
          "reason": "[6]: document missing",
          "index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
          "shard": "0",
          "index": "index1"
        }
      }
    },
    {
      "create": {
        "_index": "index1",
        "_id": "7",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 2,
          "successful": 1,
          "failed": 0
        },
        "_seq_no": 0,
        "_primary_term": 1,
        "status": 201
      }
    }
  ]
}
An example response from `POST /_bulk?filter_path=items.*.error`, which returns only information about failed operations.
{
  "items": [
    {
      "update": {
        "error": {
          "type": "document_missing_exception",
          "reason": "[5]: document missing",
          "index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
          "shard": "0",
          "index": "index1"
        }
      }
    },
    {
      "update": {
        "error": {
          "type": "document_missing_exception",
          "reason": "[6]: document missing",
          "index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
          "shard": "0",
          "index": "index1"
        }
      }
    }
  ]
}




















Create or update a document in an index

POST /{index}/_doc/{id}

Add a JSON document to the specified data stream or index and make it searchable. If the target is an index and the document already exists, the request updates the document and increments its version.

NOTE: You cannot use this API to send update requests for existing documents in a data stream.

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 or overwrite a document using the PUT /<target>/_doc/<_id> request format, you must have the create, index, or write index privilege.
  • To add a document using the POST /<target>/_doc/ request format, 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.

NOTE: Replica shards might not all be started when an indexing operation returns successfully. By default, only the primary is required. Set wait_for_active_shards to change this default behavior.

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.

Optimistic concurrency control

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

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.

No operation (noop) updates

When updating a document by using this API, a new version of the document is always created even if the document hasn't changed. If this isn't acceptable use the _update API with detect_noop set to true. The detect_noop option isn't available on this API because it doesn’t fetch the old source and isn't able to compare it against the new source.

There isn't a definitive rule for when noop updates aren't acceptable. It's a combination of lots of factors like how frequently your data source sends updates that are actually noops and how many queries per second Elasticsearch runs on the shard receiving the updates.

Versioning

Each indexed document is given a version number. By default, internal versioning is used that starts at 1 and increments with each update, deletes included. Optionally, the version number can be set to an external value (for example, if maintained in a database). To enable this functionality, version_type should be set to external. The value provided must be a numeric, long value greater than or equal to 0, and less than around 9.2e+18.

NOTE: Versioning is completely real time, and is not affected by the near real time aspects of search operations. If no version is provided, the operation runs without any version checks.

When using the external version type, the system checks to see if the version number passed to the index request is greater than the version of the currently stored document. If true, the document will be indexed and the new version number used. If the value provided is less than or equal to the stored document's version number, a version conflict will occur and the index operation will fail. For example:

PUT my-index-000001/_doc/1?version=2&version_type=external
{
  "user": {
    "id": "elkbee"
  }
}

In this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1.
If the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code).

A nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used.
Even the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order.

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. You can check for existing targets with the resolve index API.

  • id string Required

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

Query parameters

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

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

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

  • op_type string

    Set to create to only index the document if it does not already exist (put if absent). If a document with the specified _id already exists, the indexing operation will fail. The behavior is the same as using the <index>/_create endpoint. If a document ID is specified, this paramater defaults to index. Otherwise, it defaults to create. If the request targets a data stream, an op_type of create is required.

    Values are index or create.

  • pipeline string

    The ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, then setting the value to _none disables 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.

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

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

  • version number

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

  • The version type.

    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.

  • If true, the destination must be an index alias.

application/json

Body Required

object object

Additional properties are allowed.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • _id string Required
    • _index string Required
    • 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

      Additional properties are allowed.

      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

          Additional properties are allowed.

          Hide reason attributes Show reason attributes object
          • type string Required

            The type of error

          • reason string

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

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

          • Additional properties are allowed.

          • root_cause array[object]

            Additional properties are allowed.

          • suppressed array[object]

            Additional properties are allowed.

        • shard number Required
        • status string
      • skipped number
    • _version number Required
POST /{index}/_doc/{id}
curl \
 --request POST http://api.example.com/{index}/_doc/{id} \
 --header "Content-Type: application/json" \
 --data '"{\n  \"@timestamp\": \"2099-11-15T13:12:00\",\n  \"message\": \"GET /search HTTP/1.1 200 1070000\",\n  \"user\": {\n    \"id\": \"kimchy\"\n  }\n}"'
Request examples
Run `POST my-index-000001/_doc/` to index a document. When you use the `POST /<target>/_doc/` request format, the `op_type` is automatically set to `create` and the index operation generates a unique ID for the document.
{
  "@timestamp": "2099-11-15T13:12:00",
  "message": "GET /search HTTP/1.1 200 1070000",
  "user": {
    "id": "kimchy"
  }
}
Run `PUT my-index-000001/_doc/1` to insert a JSON document into the `my-index-000001` index with an `_id` of 1.
{
  "@timestamp": "2099-11-15T13:12:00",
  "message": "GET /search HTTP/1.1 200 1070000",
  "user": {
    "id": "kimchy"
  }
}
Response examples (200)
A successful response from `POST my-index-000001/_doc/`, which contains an automated document ID.
{
  "_shards": {
    "total": 2,
    "failed": 0,
    "successful": 2
  },
  "_index": "my-index-000001",
  "_id": "W0tpsmIBdwcYyG50zbta",
  "_version": 1,
  "_seq_no": 0,
  "_primary_term": 1,
  "result": "created"
}
A successful response from `PUT my-index-000001/_doc/1`.
{
  "_shards": {
    "total": 2,
    "failed": 0,
    "successful": 2
  },
  "_index": "my-index-000001",
  "_id": "1",
  "_version": 1,
  "_seq_no": 0,
  "_primary_term": 1,
  "result": "created"
}








Delete documents Added in 5.0.0

POST /{index}/_delete_by_query

Deletes documents that match the specified query.

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

  • read
  • delete or write

You can specify the query criteria in the request URI or the request body using the same syntax as the search API. When you submit a delete by query request, Elasticsearch gets a snapshot of the data stream or index when it begins processing the request and deletes matching documents using internal versioning. If a document changes between the time that the snapshot is taken and the delete operation is processed, it results in a version conflict and the delete operation fails.

NOTE: Documents with a version equal to 0 cannot be deleted using delete by query because internal versioning does not support 0 as a valid version number.

While processing a delete by query request, Elasticsearch performs multiple search requests sequentially to find all of the matching documents to delete. A bulk delete request is performed for each batch of matching documents. If a search or bulk request is rejected, the requests are retried up to 10 times, with exponential back off. If the maximum retry limit is reached, processing halts and all failed requests are returned in the response. Any delete requests that completed successfully still stick, they are not rolled back.

You can opt to count version conflicts instead of halting and returning by setting conflicts to proceed. Note that if you opt to count version conflicts the operation could attempt to delete more documents from the source than max_docs until it has successfully deleted max_docs documents, or it has gone through every document in the source query.

Throttling delete requests

To control the rate at which delete by query issues batches of delete operations, you can set requests_per_second to any positive decimal number. This pads each batch with a wait time to throttle the rate. Set requests_per_second to -1 to disable throttling.

Throttling uses a wait time between batches so that the internal scroll requests can be given a timeout that takes the request padding into account. The padding time is the difference between the batch size divided by the requests_per_second and the time spent writing. By default the batch size is 1000, so if requests_per_second is set to 500:

target_time = 1000 / 500 per second = 2 seconds
wait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds

Since the batch is issued as a single _bulk request, large batch sizes cause Elasticsearch to create many requests and wait before starting the next set. This is "bursty" instead of "smooth".

Slicing

Delete by query supports sliced scroll to parallelize the delete process. This can improve efficiency and provide a convenient way to break the request down into smaller parts.

Setting slices to auto lets Elasticsearch choose the number of slices to use. This setting will use one slice per shard, up to a certain limit. If there are multiple source data streams or indices, it will choose the number of slices based on the index or backing index with the smallest number of shards. Adding slices to the delete by query operation creates sub-requests which means it has some quirks:

  • You can see these requests in the tasks APIs. These sub-requests are "child" tasks of the task for the request with slices.
  • Fetching the status of the task for the request with slices only contains the status of completed slices.
  • These sub-requests are individually addressable for things like cancellation and rethrottling.
  • Rethrottling the request with slices will rethrottle the unfinished sub-request proportionally.
  • Canceling the request with slices will cancel each sub-request.
  • Due to the nature of slices each sub-request won't get a perfectly even portion of the documents. All documents will be addressed, but some slices may be larger than others. Expect larger slices to have a more even distribution.
  • Parameters like requests_per_second and max_docs on a request with slices are distributed proportionally to each sub-request. Combine that with the earlier point about distribution being uneven and you should conclude that using max_docs with slices might not result in exactly max_docs documents being deleted.
  • Each sub-request gets a slightly different snapshot of the source data stream or index though these are all taken at approximately the same time.

If you're slicing manually or otherwise tuning automatic slicing, keep in mind that:

  • Query performance is most efficient when the number of slices is equal to the number of shards in the index or backing index. If that number is large (for example, 500), choose a lower number as too many slices hurts performance. Setting slices higher than the number of shards generally does not improve efficiency and adds overhead.
  • Delete performance scales linearly across available resources with the number of slices.

Whether query or delete performance dominates the runtime depends on the documents being reindexed and cluster resources.

Cancel a delete by query operation

Any delete by query can be canceled using the task cancel API. For example:

POST _tasks/r1A2WoRbTwKZ516z6NEs5A:36619/_cancel

The task ID can be found by using the get tasks API.

Cancellation should happen quickly but might take a few seconds. The get task status API will continue to list the delete by query task until this task checks that it has been cancelled and terminates itself.

Path parameters

  • index string | array[string] Required

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

Query parameters

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

  • analyzer string

    Analyzer to use for the query string. This parameter can be used only when the q query string parameter is specified.

  • If true, wildcard and prefix queries are analyzed. This parameter can be used only when the q query string parameter is specified.

  • What to do if delete by query hits version conflicts: abort or proceed.

    Values are abort or proceed.

  • The default operator for query string query: AND or OR. This parameter can be used only when the q query string parameter is specified.

    Values are and, AND, or, or OR.

  • df string

    The field to use as default where no field prefix is given in the query string. This parameter can be used only when the q query string parameter is specified.

  • expand_wildcards string | array[string]

    The type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. It supports comma-separated values, such as open,hidden.

  • from number

    Starting offset (default: 0)

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

  • lenient boolean

    If true, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. This parameter can be used only when the q query string parameter is specified.

  • max_docs number

    The maximum number of documents to process. Defaults to all documents. When set to a value less then or equal to scroll_size, a scroll will not be used to retrieve the results for the operation.

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

  • refresh boolean

    If true, Elasticsearch refreshes all shards involved in the delete by query after the request completes. This is different than the delete API's refresh parameter, which causes just the shard that received the delete request to be refreshed. Unlike the delete API, it does not support wait_for.

  • If true, the request cache is used for this request. Defaults to the index-level setting.

  • The throttle for this request in sub-requests per second.

  • routing string

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

  • q string

    A query in the Lucene query string syntax.

  • scroll string

    The period to retain the search context for scrolling.

  • The size of the scroll request that powers the operation.

  • The explicit timeout for each search request. It defaults to no timeout.

  • The type of the search operation. Available options include query_then_fetch and dfs_query_then_fetch.

    Values are query_then_fetch or dfs_query_then_fetch.

  • slices number | string

    The number of slices this task should be divided into.

  • sort array[string]

    A comma-separated list of <field>:<direction> pairs.

  • stats array[string]

    The specific tag of the request for logging and statistical purposes.

  • The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.

    Use with caution. Elasticsearch applies this parameter to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers.

  • timeout string

    The period each deletion request waits for active shards.

  • version boolean

    If true, returns the document version as part of a hit.

  • wait_for_active_shards number | string

    The number of shard copies that must be active before proceeding with the operation. Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1). The timeout value controls how long each write request waits for unavailable shards to become available.

  • If true, the request blocks until the operation is complete. If false, Elasticsearch performs some preflight checks, launches the request, and returns a task you can use to cancel or get the status of the task. Elasticsearch creates a record of this task as a document at .tasks/task/${taskId}. When you are done with a task, you should delete the task document so Elasticsearch can reclaim the space.

application/json

Body Required

  • max_docs number

    The maximum number of documents to delete.

  • query object

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

    Additional properties are allowed.

  • slice object

    Additional properties are allowed.

    Hide slice attributes Show slice attributes object
    • field string

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

    • id string Required
    • max number Required

Responses

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

      The number of scroll responses pulled back by the delete by query.

    • deleted number

      The number of documents that were successfully deleted.

    • failures array[object]

      An array of failures if there were any unrecoverable errors during the process. If this array is not empty, the request ended abnormally because of those failures. Delete by query is implemented using batches and any failures cause the entire process to end but all failures in the current batch are collected into the array. You can use the conflicts option to prevent reindex from ending on version conflicts.

      Hide failures attributes Show failures attributes object
      • cause object Required

        Additional properties are allowed.

        Hide cause attributes Show cause attributes object
        • type string Required

          The type of error

        • reason string

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

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

        • Additional properties are allowed.

        • root_cause array[object]

          Additional properties are allowed.

        • suppressed array[object]

          Additional properties are allowed.

      • id string Required
      • index string Required
      • status number Required
      • type string Required
    • noops number

      This field is always equal to zero for delete by query. It exists only so that delete by query, update by query, and reindex APIs return responses with the same structure.

    • The number of requests per second effectively run during the delete by query.

    • retries object

      Additional properties are allowed.

      Hide retries attributes Show retries attributes object
      • bulk number Required

        The number of bulk actions retried.

    • slice_id number
    • 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

    • 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

    • timed_out boolean

      If true, some requests run during the delete by query operation timed out.

    • took number

      Time unit for milliseconds

    • total number

      The number of documents that were successfully processed.

    • The number of version conflicts that the delete by query hit.

POST /{index}/_delete_by_query
curl \
 --request POST http://api.example.com/{index}/_delete_by_query \
 --header "Content-Type: application/json" \
 --data '"{\n  \"query\": {\n    \"match_all\": {}\n  }\n}"'
Run `POST /my-index-000001,my-index-000002/_delete_by_query` to delete all documents from multiple data streams or indices.
{
  "query": {
    "match_all": {}
  }
}
Run `POST my-index-000001/_delete_by_query` to delete a document by using a unique attribute.
{
  "query": {
    "term": {
      "user.id": "kimchy"
    }
  },
  "max_docs": 1
}
Run `POST my-index-000001/_delete_by_query` to slice a delete by query manually. Provide a slice ID and total number of slices.
{
  "slice": {
    "id": 0,
    "max": 2
  },
  "query": {
    "range": {
      "http.response.bytes": {
        "lt": 2000000
      }
    }
  }
}
Run `POST my-index-000001/_delete_by_query?refresh&slices=5` to let delete by query automatically parallelize using sliced scroll to slice on `_id`. The `slices` query parameter value specifies the number of slices to use.
{
  "query": {
    "range": {
      "http.response.bytes": {
        "lt": 2000000
      }
    }
  }
}
Response examples (200)
A successful response from `POST /my-index-000001/_delete_by_query`.
{
  "took" : 147,
  "timed_out": false,
  "total": 119,
  "deleted": 119,
  "batches": 1,
  "version_conflicts": 0,
  "noops": 0,
  "retries": {
    "bulk": 0,
    "search": 0
  },
  "throttled_millis": 0,
  "requests_per_second": -1.0,
  "throttled_until_millis": 0,
  "failures" : [ ]
}




Get a document's source

GET /{index}/_source/{id}

Get the source of a document. For example:

GET my-index-000001/_source/1

You can use the source filtering parameters to control which parts of the _source are returned:

GET my-index-000001/_source/1/?_source_includes=*.id&_source_excludes=entities

Path parameters

  • index string Required

    The name of the index that contains the document.

  • id string Required

    A unique document identifier.

Query parameters

  • The node or shard the operation should be performed on. By default, the operation is randomized between the shard replicas.

  • realtime boolean

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

  • refresh boolean

    If true, the request refreshes the relevant shards before retrieving the document. Setting it to true should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).

  • routing string

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

  • _source boolean | string | array[string]

    Indicates whether to return the _source field (true or false) or lists the fields to return.

  • _source_excludes string | array[string]

    A comma-separated list of source fields to exclude in the response.

  • _source_includes string | array[string]

    A comma-separated list of source fields to include in the response.

  • stored_fields string | array[string]

    A comma-separated list of stored fields to return as part of a hit.

  • version number

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

  • The version type.

    Values are internal, external, external_gte, or force.

Responses

  • 200 application/json

    Additional properties are allowed.

GET /{index}/_source/{id}
curl \
 --request GET http://api.example.com/{index}/_source/{id}
Response examples (200)
{}
























Get multiple term vectors

GET /_mtermvectors

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

Artificial documents

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

Query parameters

  • ids array[string]

    A comma-separated list of documents ids. You must define ids as parameter or set "ids" or "docs" in the request body

  • fields string | array[string]

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

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

  • offsets boolean

    If true, the response includes term offsets.

  • payloads boolean

    If true, the response includes term payloads.

  • positions boolean

    If true, the response includes term positions.

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

  • realtime boolean

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

  • routing string

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

  • If true, the response includes term frequency and document frequency.

  • version number

    If true, returns the document version as part of a hit.

  • The version type.

    Values are internal, external, external_gte, or force.

application/json

Body

  • docs array[object]

    An array of existing or artificial documents.

    Hide docs attributes Show docs attributes object
    • _id string
    • _index string
    • doc object

      An artificial document (a document not present in the index) for which you want to retrieve term vectors.

      Additional properties are allowed.

    • fields string | array[string]
    • If true, the response includes the document count, sum of document frequencies, and sum of total term frequencies.

    • filter object

      Additional properties are allowed.

      Hide filter attributes Show filter attributes object
      • Ignore words which occur in more than this many docs. Defaults to unbounded.

      • The maximum number of terms that must be returned per field.

      • Ignore words with more than this frequency in the source doc. It defaults to unbounded.

      • The maximum word length above which words will be ignored. Defaults to unbounded.

      • Ignore terms which do not occur in at least this many docs.

      • Ignore words with less than this frequency in the source doc.

      • The minimum word length below which words will be ignored.

    • offsets boolean

      If true, the response includes term offsets.

    • payloads boolean

      If true, the response includes term payloads.

    • positions boolean

      If true, the response includes term positions.

    • routing string
    • If true, the response includes term frequency and document frequency.

    • version number
    • Values are internal, external, external_gte, or force.

  • ids array[string]

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

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • docs array[object] Required
      Hide docs attributes Show docs attributes object
      • _id string
      • _index string Required
      • _version number
      • took number
      • found boolean
      • Hide term_vectors attribute Show term_vectors attribute object
        • * object Additional properties

          Additional properties are allowed.

          Hide * attributes Show * attributes object
          • Additional properties are allowed.

            Hide field_statistics attributes Show field_statistics attributes object
          • terms object Required
            Hide terms attribute Show terms attribute object
            • * object Additional properties

              Additional properties are allowed.

      • error object

        Additional properties are allowed.

        Hide error attributes Show error attributes object
        • type string Required

          The type of error

        • reason string

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

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

        • Additional properties are allowed.

        • root_cause array[object]

          Additional properties are allowed.

        • suppressed array[object]

          Additional properties are allowed.

GET /_mtermvectors
curl \
 --request GET http://api.example.com/_mtermvectors \
 --header "Content-Type: application/json" \
 --data '"{\n  \"docs\": [\n      {\n        \"_id\": \"2\",\n        \"fields\": [\n            \"message\"\n        ],\n        \"term_statistics\": true\n      },\n      {\n        \"_id\": \"1\"\n      }\n  ]\n}"'
Run `POST /my-index-000001/_mtermvectors`. When you specify an index in the request URI, the index does not need to be specified for each documents in the request body.
{
  "docs": [
      {
        "_id": "2",
        "fields": [
            "message"
        ],
        "term_statistics": true
      },
      {
        "_id": "1"
      }
  ]
}
Run `POST /my-index-000001/_mtermvectors`. If all requested documents are in same index and the parameters are the same, you can use a simplified syntax.
{
  "ids": [ "1", "2" ],
  "parameters": {
    "fields": [
      "message"
    ],
    "term_statistics": true
  }
}
Run `POST /_mtermvectors` to generate term vectors for artificial documents provided in the body of the request. The mapping used is determined by the specified `_index`.
{
  "docs": [
      {
        "_index": "my-index-000001",
        "doc" : {
            "message" : "test test test"
        }
      },
      {
        "_index": "my-index-000001",
        "doc" : {
          "message" : "Another test ..."
        }
      }
  ]
}
Response examples (200)
{
  "docs": [
    {
      "_id": "string",
      "_index": "string",
      "_version": 42.0,
      "took": 42.0,
      "found": true,
      "term_vectors": {
        "additionalProperty1": {
          "field_statistics": {
            "doc_count": 42.0,
            "sum_doc_freq": 42.0,
            "sum_ttf": 42.0
          },
          "terms": {
            "additionalProperty1": {},
            "additionalProperty2": {}
          }
        },
        "additionalProperty2": {
          "field_statistics": {
            "doc_count": 42.0,
            "sum_doc_freq": 42.0,
            "sum_ttf": 42.0
          },
          "terms": {
            "additionalProperty1": {},
            "additionalProperty2": {}
          }
        }
      },
      "error": {
        "type": "string",
        "reason": "string",
        "stack_trace": "string",
        "caused_by": {},
        "root_cause": [
          {}
        ],
        "suppressed": [
          {}
        ]
      }
    }
  ]
}
















Throttle a reindex operation 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

  • 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
POST /_reindex/{task_id}/_rethrottle
curl \
 --request POST http://api.example.com/_reindex/{task_id}/_rethrottle
Response examples (200)
{
  "nodes": {}
}




Get term vector information

POST /{index}/_termvectors/{id}

Get information and statistics about terms in the fields of a particular document.

You can retrieve term vectors for documents stored in the index or for artificial documents passed in the body of the request. You can specify the fields you are interested in through the fields parameter or by adding the fields to the request body. For example:

GET /my-index-000001/_termvectors/1?fields=message

Fields can be specified using wildcards, similar to the multi match query.

Term vectors are real-time by default, not near real-time. This can be changed by setting realtime parameter to false.

You can request three types of values: term information, term statistics, and field statistics. By default, all term information and field statistics are returned for all fields but term statistics are excluded.

Term information

  • term frequency in the field (always returned)
  • term positions (positions: true)
  • start and end offsets (offsets: true)
  • term payloads (payloads: true), as base64 encoded bytes

If the requested information wasn't stored in the index, it will be computed on the fly if possible. Additionally, term vectors could be computed for documents not even existing in the index, but instead provided by the user.


Start and end offsets assume UTF-16 encoding is being used. If you want to use these offsets in order to get the original text that produced this token, you should make sure that the string you are taking a sub-string of is also encoded using UTF-16.

Behaviour

The term and field statistics are not accurate. Deleted documents are not taken into account. The information is only retrieved for the shard the requested document resides in. The term and field statistics are therefore only useful as relative measures whereas the absolute numbers have no meaning in this context. By default, when requesting term vectors of artificial documents, a shard to get the statistics from is randomly selected. Use routing only to hit a particular shard.

Path parameters

  • index string Required

    The name of the index that contains the document.

  • id string Required

    A unique identifier for the document.

Query parameters

  • fields string | array[string]

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

  • If true, the response includes:

    • The document count (how many documents contain this field).
    • The sum of document frequencies (the sum of document frequencies for all terms in this field).
    • The sum of total term frequencies (the sum of total term frequencies of each term in this field).
  • offsets boolean

    If true, the response includes term offsets.

  • payloads boolean

    If true, the response includes term payloads.

  • positions boolean

    If true, the response includes term positions.

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

  • realtime boolean

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

  • routing string

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

  • If true, the response includes:

    • The total term frequency (how often a term occurs in all documents).
    • The document frequency (the number of documents containing the current term).

    By default these values are not returned since term statistics can have a serious performance impact.

  • version number

    If true, returns the document version as part of a hit.

  • The version type.

    Values are internal, external, external_gte, or force.

application/json

Body

  • doc object

    An artificial document (a document not present in the index) for which you want to retrieve term vectors.

    Additional properties are allowed.

  • filter object

    Additional properties are allowed.

    Hide filter attributes Show filter attributes object
    • Ignore words which occur in more than this many docs. Defaults to unbounded.

    • The maximum number of terms that must be returned per field.

    • Ignore words with more than this frequency in the source doc. It defaults to unbounded.

    • The maximum word length above which words will be ignored. Defaults to unbounded.

    • Ignore terms which do not occur in at least this many docs.

    • Ignore words with less than this frequency in the source doc.

    • The minimum word length below which words will be ignored.

  • Override the default per-field analyzer. This is useful in order to generate term vectors in any fashion, especially when using artificial documents. When providing an analyzer for a field that already stores term vectors, the term vectors will be regenerated.

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

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • found boolean Required
    • _id string
    • _index string Required
    • Hide term_vectors attribute Show term_vectors attribute object
      • * object Additional properties

        Additional properties are allowed.

        Hide * attributes Show * attributes object
    • took number Required
    • _version number Required
POST /{index}/_termvectors/{id}
curl \
 --request POST http://api.example.com/{index}/_termvectors/{id} \
 --header "Content-Type: application/json" \
 --data '"{\n  \"fields\" : [\"text\"],\n  \"offsets\" : true,\n  \"payloads\" : true,\n  \"positions\" : true,\n  \"term_statistics\" : true,\n  \"field_statistics\" : true\n}"'
Run `GET /my-index-000001/_termvectors/1` to return all information and statistics for field `text` in document 1.
{
  "fields" : ["text"],
  "offsets" : true,
  "payloads" : true,
  "positions" : true,
  "term_statistics" : true,
  "field_statistics" : true
}
Run `GET /my-index-000001/_termvectors/1` to set per-field analyzers. A different analyzer than the one at the field may be provided by using the `per_field_analyzer` parameter.
{
  "doc" : {
    "fullname" : "John Doe",
    "text" : "test test test"
  },
  "fields": ["fullname"],
  "per_field_analyzer" : {
    "fullname": "keyword"
  }
}
Run `GET /imdb/_termvectors` to filter the terms returned based on their tf-idf scores. It returns the three most "interesting" keywords from the artificial document having the given "plot" field value. Notice that the keyword "Tony" or any stop words are not part of the response, as their tf-idf must be too low.
{
  "doc": {
    "plot": "When wealthy industrialist Tony Stark is forced to build an armored suit after a life-threatening incident, he ultimately decides to use its technology to fight against evil."
  },
  "term_statistics": true,
  "field_statistics": true,
  "positions": false,
  "offsets": false,
  "filter": {
    "max_num_terms": 3,
    "min_term_freq": 1,
    "min_doc_freq": 1
  }
}
Run `GET /my-index-000001/_termvectors/1`. Term vectors which are not explicitly stored in the index are automatically computed on the fly. This request returns all information and statistics for the fields in document 1, even though the terms haven't been explicitly stored in the index. Note that for the field text, the terms are not regenerated.
{
  "fields" : ["text", "some_field_without_term_vectors"],
  "offsets" : true,
  "positions" : true,
  "term_statistics" : true,
  "field_statistics" : true
}
Run `GET /my-index-000001/_termvectors`. Term vectors can be generated for artificial documents, that is for documents not present in the index. If dynamic mapping is turned on (default), the document fields not in the original mapping will be dynamically created.
{
  "doc" : {
    "fullname" : "John Doe",
    "text" : "test test test"
  }
}
Response examples (200)
A successful response from `GET /my-index-000001/_termvectors/1`.
{
  "_index": "my-index-000001",
  "_id": "1",
  "_version": 1,
  "found": true,
  "took": 6,
  "term_vectors": {
    "text": {
      "field_statistics": {
        "sum_doc_freq": 4,
        "doc_count": 2,
        "sum_ttf": 6
      },
      "terms": {
        "test": {
          "doc_freq": 2,
          "ttf": 4,
          "term_freq": 3,
          "tokens": [
            {
              "position": 0,
              "start_offset": 0,
              "end_offset": 4,
              "payload": "d29yZA=="
            },
            {
              "position": 1,
              "start_offset": 5,
              "end_offset": 9,
              "payload": "d29yZA=="
            },
            {
              "position": 2,
              "start_offset": 10,
              "end_offset": 14,
              "payload": "d29yZA=="
            }
          ]
        }
      }
    }
  }
}
A successful response from `GET /my-index-000001/_termvectors` with `per_field_analyzer` in the request body.
{
  "_index": "my-index-000001",
  "_version": 0,
  "found": true,
  "took": 6,
  "term_vectors": {
    "fullname": {
      "field_statistics": {
          "sum_doc_freq": 2,
          "doc_count": 4,
          "sum_ttf": 4
      },
      "terms": {
          "John Doe": {
            "term_freq": 1,
            "tokens": [
                {
                  "position": 0,
                  "start_offset": 0,
                  "end_offset": 8
                }
            ]
          }
      }
    }
  }
}
A successful response from `GET /my-index-000001/_termvectors` with a `filter` in the request body.
{
  "_index": "imdb",
  "_version": 0,
  "found": true,
  "term_vectors": {
      "plot": {
        "field_statistics": {
            "sum_doc_freq": 3384269,
            "doc_count": 176214,
            "sum_ttf": 3753460
        },
        "terms": {
            "armored": {
              "doc_freq": 27,
              "ttf": 27,
              "term_freq": 1,
              "score": 9.74725
            },
            "industrialist": {
              "doc_freq": 88,
              "ttf": 88,
              "term_freq": 1,
              "score": 8.590818
            },
            "stark": {
              "doc_freq": 44,
              "ttf": 47,
              "term_freq": 1,
              "score": 9.272792
            }
        }
      }
  }
}




Get term vector information

POST /{index}/_termvectors

Get information and statistics about terms in the fields of a particular document.

You can retrieve term vectors for documents stored in the index or for artificial documents passed in the body of the request. You can specify the fields you are interested in through the fields parameter or by adding the fields to the request body. For example:

GET /my-index-000001/_termvectors/1?fields=message

Fields can be specified using wildcards, similar to the multi match query.

Term vectors are real-time by default, not near real-time. This can be changed by setting realtime parameter to false.

You can request three types of values: term information, term statistics, and field statistics. By default, all term information and field statistics are returned for all fields but term statistics are excluded.

Term information

  • term frequency in the field (always returned)
  • term positions (positions: true)
  • start and end offsets (offsets: true)
  • term payloads (payloads: true), as base64 encoded bytes

If the requested information wasn't stored in the index, it will be computed on the fly if possible. Additionally, term vectors could be computed for documents not even existing in the index, but instead provided by the user.


Start and end offsets assume UTF-16 encoding is being used. If you want to use these offsets in order to get the original text that produced this token, you should make sure that the string you are taking a sub-string of is also encoded using UTF-16.

Behaviour

The term and field statistics are not accurate. Deleted documents are not taken into account. The information is only retrieved for the shard the requested document resides in. The term and field statistics are therefore only useful as relative measures whereas the absolute numbers have no meaning in this context. By default, when requesting term vectors of artificial documents, a shard to get the statistics from is randomly selected. Use routing only to hit a particular shard.

Path parameters

  • index string Required

    The name of the index that contains the document.

Query parameters

  • fields string | array[string]

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

  • If true, the response includes:

    • The document count (how many documents contain this field).
    • The sum of document frequencies (the sum of document frequencies for all terms in this field).
    • The sum of total term frequencies (the sum of total term frequencies of each term in this field).
  • offsets boolean

    If true, the response includes term offsets.

  • payloads boolean

    If true, the response includes term payloads.

  • positions boolean

    If true, the response includes term positions.

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

  • realtime boolean

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

  • routing string

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

  • If true, the response includes:

    • The total term frequency (how often a term occurs in all documents).
    • The document frequency (the number of documents containing the current term).

    By default these values are not returned since term statistics can have a serious performance impact.

  • version number

    If true, returns the document version as part of a hit.

  • The version type.

    Values are internal, external, external_gte, or force.

application/json

Body

  • doc object

    An artificial document (a document not present in the index) for which you want to retrieve term vectors.

    Additional properties are allowed.

  • filter object

    Additional properties are allowed.

    Hide filter attributes Show filter attributes object
    • Ignore words which occur in more than this many docs. Defaults to unbounded.

    • The maximum number of terms that must be returned per field.

    • Ignore words with more than this frequency in the source doc. It defaults to unbounded.

    • The maximum word length above which words will be ignored. Defaults to unbounded.

    • Ignore terms which do not occur in at least this many docs.

    • Ignore words with less than this frequency in the source doc.

    • The minimum word length below which words will be ignored.

  • Override the default per-field analyzer. This is useful in order to generate term vectors in any fashion, especially when using artificial documents. When providing an analyzer for a field that already stores term vectors, the term vectors will be regenerated.

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

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • found boolean Required
    • _id string
    • _index string Required
    • Hide term_vectors attribute Show term_vectors attribute object
      • * object Additional properties

        Additional properties are allowed.

        Hide * attributes Show * attributes object
    • took number Required
    • _version number Required
POST /{index}/_termvectors
curl \
 --request POST http://api.example.com/{index}/_termvectors \
 --header "Content-Type: application/json" \
 --data '"{\n  \"fields\" : [\"text\"],\n  \"offsets\" : true,\n  \"payloads\" : true,\n  \"positions\" : true,\n  \"term_statistics\" : true,\n  \"field_statistics\" : true\n}"'
Run `GET /my-index-000001/_termvectors/1` to return all information and statistics for field `text` in document 1.
{
  "fields" : ["text"],
  "offsets" : true,
  "payloads" : true,
  "positions" : true,
  "term_statistics" : true,
  "field_statistics" : true
}
Run `GET /my-index-000001/_termvectors/1` to set per-field analyzers. A different analyzer than the one at the field may be provided by using the `per_field_analyzer` parameter.
{
  "doc" : {
    "fullname" : "John Doe",
    "text" : "test test test"
  },
  "fields": ["fullname"],
  "per_field_analyzer" : {
    "fullname": "keyword"
  }
}
Run `GET /imdb/_termvectors` to filter the terms returned based on their tf-idf scores. It returns the three most "interesting" keywords from the artificial document having the given "plot" field value. Notice that the keyword "Tony" or any stop words are not part of the response, as their tf-idf must be too low.
{
  "doc": {
    "plot": "When wealthy industrialist Tony Stark is forced to build an armored suit after a life-threatening incident, he ultimately decides to use its technology to fight against evil."
  },
  "term_statistics": true,
  "field_statistics": true,
  "positions": false,
  "offsets": false,
  "filter": {
    "max_num_terms": 3,
    "min_term_freq": 1,
    "min_doc_freq": 1
  }
}
Run `GET /my-index-000001/_termvectors/1`. Term vectors which are not explicitly stored in the index are automatically computed on the fly. This request returns all information and statistics for the fields in document 1, even though the terms haven't been explicitly stored in the index. Note that for the field text, the terms are not regenerated.
{
  "fields" : ["text", "some_field_without_term_vectors"],
  "offsets" : true,
  "positions" : true,
  "term_statistics" : true,
  "field_statistics" : true
}
Run `GET /my-index-000001/_termvectors`. Term vectors can be generated for artificial documents, that is for documents not present in the index. If dynamic mapping is turned on (default), the document fields not in the original mapping will be dynamically created.
{
  "doc" : {
    "fullname" : "John Doe",
    "text" : "test test test"
  }
}
Response examples (200)
A successful response from `GET /my-index-000001/_termvectors/1`.
{
  "_index": "my-index-000001",
  "_id": "1",
  "_version": 1,
  "found": true,
  "took": 6,
  "term_vectors": {
    "text": {
      "field_statistics": {
        "sum_doc_freq": 4,
        "doc_count": 2,
        "sum_ttf": 6
      },
      "terms": {
        "test": {
          "doc_freq": 2,
          "ttf": 4,
          "term_freq": 3,
          "tokens": [
            {
              "position": 0,
              "start_offset": 0,
              "end_offset": 4,
              "payload": "d29yZA=="
            },
            {
              "position": 1,
              "start_offset": 5,
              "end_offset": 9,
              "payload": "d29yZA=="
            },
            {
              "position": 2,
              "start_offset": 10,
              "end_offset": 14,
              "payload": "d29yZA=="
            }
          ]
        }
      }
    }
  }
}
A successful response from `GET /my-index-000001/_termvectors` with `per_field_analyzer` in the request body.
{
  "_index": "my-index-000001",
  "_version": 0,
  "found": true,
  "took": 6,
  "term_vectors": {
    "fullname": {
      "field_statistics": {
          "sum_doc_freq": 2,
          "doc_count": 4,
          "sum_ttf": 4
      },
      "terms": {
          "John Doe": {
            "term_freq": 1,
            "tokens": [
                {
                  "position": 0,
                  "start_offset": 0,
                  "end_offset": 8
                }
            ]
          }
      }
    }
  }
}
A successful response from `GET /my-index-000001/_termvectors` with a `filter` in the request body.
{
  "_index": "imdb",
  "_version": 0,
  "found": true,
  "term_vectors": {
      "plot": {
        "field_statistics": {
            "sum_doc_freq": 3384269,
            "doc_count": 176214,
            "sum_ttf": 3753460
        },
        "terms": {
            "armored": {
              "doc_freq": 27,
              "ttf": 27,
              "term_freq": 1,
              "score": 9.74725
            },
            "industrialist": {
              "doc_freq": 88,
              "ttf": 88,
              "term_freq": 1,
              "score": 8.590818
            },
            "stark": {
              "doc_freq": 44,
              "ttf": 47,
              "term_freq": 1,
              "score": 9.272792
            }
        }
      }
  }
}

Update a document

POST /{index}/_update/{id}

Update a document by running a script or passing a partial document.

If the Elasticsearch security features are enabled, you must have the index or write index privilege for the target index or index alias.

The script can update, delete, or skip modifying the document. The API also supports passing a partial document, which is merged into the existing document. To fully replace an existing document, use the index API. This operation:

  • Gets the document (collocated with the shard) from the index.
  • Runs the specified script.
  • Indexes the result.

The document must still be reindexed, but using this API removes some network roundtrips and reduces chances of version conflicts between the GET and the index operation.

The _source field must be enabled to use this API. In addition to _source, you can access the following variables through the ctx map: _index, _type, _id, _version, _routing, and _now (the current timestamp).

Path parameters

  • index string Required

    The name of the target index. By default, the index is created automatically if it doesn't exist.

  • id string Required

    A unique identifier for the document to be updated.

Query parameters

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

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

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

  • lang string

    The script language.

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

  • If true, the destination must be an index alias.

  • The number of times the operation should be retried when a conflict occurs.

  • routing string

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

  • timeout string

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

  • wait_for_active_shards number | string

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

  • _source boolean | string | array[string]

    If false, source retrieval is turned off. You can also specify a comma-separated list of the fields you want to retrieve.

  • _source_excludes string | array[string]

    The source fields you want to exclude.

  • _source_includes string | array[string]

    The source fields you want to retrieve.

application/json

Body Required

  • If true, the result in the response is set to noop (no operation) when there are no changes to the document.

  • doc object

    A partial update to an existing document. If both doc and script are specified, doc is ignored.

    Additional properties are allowed.

  • If true, use the contents of 'doc' as the value of 'upsert'. NOTE: Using ingest pipelines with doc_as_upsert is not supported.

  • script object

    Additional properties are allowed.

    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

        Additional properties are allowed.

    • lang string

      Any of:

      Values are painless, expression, mustache, or java.

    • options object
      Hide options attribute Show options attribute object
      • * string Additional properties
  • If true, run the script whether or not the document exists.

  • _source boolean | object

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

    One of:
  • upsert object

    If the document does not already exist, the contents of 'upsert' are inserted as a new document. If the document exists, the 'script' is run.

    Additional properties are allowed.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
POST /{index}/_update/{id}
curl \
 --request POST http://api.example.com/{index}/_update/{id} \
 --header "Content-Type: application/json" \
 --data '"{\n  \"script\" : {\n    \"source\": \"ctx._source.counter += params.count\",\n    \"lang\": \"painless\",\n    \"params\" : {\n      \"count\" : 4\n    }\n  }\n}"'
Run `POST test/_update/1` to increment a counter by using a script.
{
  "script" : {
    "source": "ctx._source.counter += params.count",
    "lang": "painless",
    "params" : {
      "count" : 4
    }
  }
}
Run `POST test/_update/1` to use a script to add a tag to a list of tags. In this example, it is just a list, so the tag is added even it exists.
{
  "script": {
    "source": "ctx._source.tags.add(params.tag)",
    "lang": "painless",
    "params": {
      "tag": "blue"
    }
  }
}
Run `POST test/_update/1` to use a script to remove a tag from a list of tags. The Painless function to remove a tag takes the array index of the element you want to remove. To avoid a possible runtime error, you first need to make sure the tag exists. If the list contains duplicates of the tag, this script just removes one occurrence.
{
  "script": {
    "source": "if (ctx._source.tags.contains(params.tag)) { ctx._source.tags.remove(ctx._source.tags.indexOf(params.tag)) }",
    "lang": "painless",
    "params": {
      "tag": "blue"
    }
  }
}
Run `POST test/_update/1` to use a script to add a field `new_field` to the document.
{
  "script" : "ctx._source.new_field = 'value_of_new_field'"
}
Run `POST test/_update/1` to use a script to remove a field `new_field` from the document.
{
  "script" : "ctx._source.remove('new_field')"
}
Run `POST test/_update/1` to use a script to remove a subfield from an object field.
{
  "script": "ctx._source['my-object'].remove('my-subfield')"
}
Run `POST test/_update/1` to change the operation that runs from within the script. For example, this request deletes the document if the `tags` field contains `green`, otherwise it does nothing (`noop`).
{
  "script": {
    "source": "if (ctx._source.tags.contains(params.tag)) { ctx.op = 'delete' } else { ctx.op = 'noop' }",
    "lang": "painless",
    "params": {
      "tag": "green"
    }
  }
}
Run `POST test/_update/1` to do a partial update that adds a new field to the existing document.
{
  "doc": {
    "name": "new_name"
  }
}
Run `POST test/_update/1` to perfom an upsert. If the document does not already exist, the contents of the upsert element are inserted as a new document. If the document exists, the script is run.
{
  "script": {
    "source": "ctx._source.counter += params.count",
    "lang": "painless",
    "params": {
      "count": 4
    }
  },
  "upsert": {
    "counter": 1
  }
}
Run `POST test/_update/1` to perform a scripted upsert. When `scripted_upsert` is `true`, the script runs whether or not the document exists.
{
  "scripted_upsert": true,
  "script": {
    "source": """
      if ( ctx.op == 'create' ) {
        ctx._source.counter = params.count
      } else {
        ctx._source.counter += params.count
      }
    """,
    "params": {
      "count": 4
    }
  },
  "upsert": {}
}
Run `POST test/_update/1` to perform a doc as upsert. Instead of sending a partial `doc` plus an `upsert` doc, you can set `doc_as_upsert` to `true` to use the contents of `doc` as the `upsert` value.
{
  "doc": {
    "name": "new_name"
  },
  "doc_as_upsert": true
}
Response examples (200)
By default updates that don't change anything detect that they don't change anything and return `"result": "noop"`.
{
   "_shards": {
        "total": 0,
        "successful": 0,
        "failed": 0
   },
   "_index": "test",
   "_id": "1",
   "_version": 2,
   "_primary_term": 1,
   "_seq_no": 1,
   "result": "noop"
}

















Delete an enrich policy Added in 7.5.0

DELETE /_enrich/policy/{name}

Deletes an existing enrich policy and its enrich index.

Path parameters

  • name string Required

    Enrich policy to delete.

Query parameters

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 /_enrich/policy/{name}
curl \
 --request DELETE http://api.example.com/_enrich/policy/{name}
Response examples (200)
{
  "acknowledged": true
}