Get the autoscaling capacity Generally available; Added in 7.11.0

GET /_autoscaling/capacity

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

This API gets the current autoscaling capacity based on the configured autoscaling policy. It will return information to size the cluster appropriately to the current workload.

The required_capacity is calculated as the maximum of the required_capacity result of all individual deciders that are enabled for the policy.

The operator should verify that the current_nodes match the operator’s knowledge of the cluster to avoid making autoscaling decisions based on stale or incomplete information.

The response contains decider-specific information you can use to diagnose how and why autoscaling determined a certain capacity was required. This information is provided for diagnosis only. Do not use this information to make autoscaling decisions.

External documentation

Query parameters

  • master_timeout string

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

    Values are -1 or 0.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • policies object Required
      Hide policies attribute Show policies attribute object
      • * object Additional properties
        Hide * attributes Show * attributes object
        • required_capacity object Required
          Hide required_capacity attributes Show required_capacity attributes object
          • node object Required
            Hide node attributes Show node attributes object
            • storage number Required
            • memory number Required
          • total object Required
            Hide total attributes Show total attributes object
            • storage number Required
            • memory number Required
        • current_capacity object Required
          Hide current_capacity attributes Show current_capacity attributes object
          • node object Required
            Hide node attributes Show node attributes object
            • storage number Required
            • memory number Required
          • total object Required
            Hide total attributes Show total attributes object
            • storage number Required
            • memory number Required
        • current_nodes array[object] Required
          Hide current_nodes attribute Show current_nodes attribute object
          • name string Required
        • deciders object Required
          Hide deciders attribute Show deciders attribute object
          • * object Additional properties
            Hide * attributes Show * attributes object
            • required_capacity object Required
              Hide required_capacity attributes Show required_capacity attributes object
              • node object Required
              • total object Required
            • reason_summary string
            • reason_details object
GET /_autoscaling/capacity
resp = client.autoscaling.get_autoscaling_capacity()
const response = await client.autoscaling.getAutoscalingCapacity();
response = client.autoscaling.get_autoscaling_capacity
$resp = $client->autoscaling()->getAutoscalingCapacity();
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_autoscaling/capacity"
client.autoscaling().getAutoscalingCapacity(g -> g);
Response examples (200)
This may be a response to `GET /_autoscaling/capacity`.
{
  policies: {}
}

Get behavioral analytics collections Technical preview; Added in 8.8.0

GET /_application/analytics/{name}

All methods and paths for this operation:

GET /_application/analytics

GET /_application/analytics/{name}

Path parameters

  • name array[string] Required

    A list of analytics collections to limit the returned information

Responses

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








Create a behavioral analytics collection event Technical preview

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

Path parameters

  • collection_name string Required

    The name of the behavioral analytics collection.

  • event_type string

    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

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • accepted boolean Required
    • event object
POST /_application/analytics/{collection_name}/event/{event_type}
POST _application/analytics/my_analytics_collection/event/search_click
{
  "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"
  }
}
resp = client.search_application.post_behavioral_analytics_event(
    collection_name="my_analytics_collection",
    event_type="search_click",
    payload={
        "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"
        }
    },
)
const response = await client.searchApplication.postBehavioralAnalyticsEvent({
  collection_name: "my_analytics_collection",
  event_type: "search_click",
  payload: {
    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 = client.search_application.post_behavioral_analytics_event(
  collection_name: "my_analytics_collection",
  event_type: "search_click",
  body: {
    "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"
    }
  }
)
$resp = $client->searchApplication()->postBehavioralAnalyticsEvent([
    "collection_name" => "my_analytics_collection",
    "event_type" => "search_click",
    "body" => [
        "session" => [
            "id" => "1797ca95-91c9-4e2e-b1bd-9c38e6f386a9",
        ],
        "user" => [
            "id" => "5f26f01a-bbee-4202-9298-81261067abbd",
        ],
        "search" => [
            "query" => "search term",
            "results" => [
                "items" => array(
                    [
                        "document" => [
                            "id" => "123",
                            "index" => "products",
                        ],
                    ],
                ),
                "total_results" => 10,
            ],
            "sort" => [
                "name" => "relevance",
            ],
            "search_application" => "website",
        ],
        "document" => [
            "id" => "123",
            "index" => "products",
        ],
    ],
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"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"}}' "$ELASTICSEARCH_URL/_application/analytics/my_analytics_collection/event/search_click"
client.searchApplication().postBehavioralAnalyticsEvent(p -> p
    .collectionName("my_analytics_collection")
    .eventType(EventType.SearchClick)
    .payload(JsonData.fromJson("{\"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\"}}"))
);
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"
  }
}

Get aliases Generally available

GET /_cat/aliases/{name}

All methods and paths for this operation:

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

Required authorization

  • Index privileges: view_index_metadata

Path parameters

  • name string | array[string]

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

Query parameters

  • h string | array[string]

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

  • s string | array[string]

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

  • expand_wildcards string | array[string]

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

    Supported values include:

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

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

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

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • alias string

      alias name

    • index string
    • filter string

      filter

    • routing.index string

      index routing

    • is_write_index string

      write index

GET _cat/aliases?format=json&v=true
resp = client.cat.aliases(
    format="json",
    v=True,
)
const response = await client.cat.aliases({
  format: "json",
  v: "true",
});
response = client.cat.aliases(
  format: "json",
  v: "true"
)
$resp = $client->cat()->aliases([
    "format" => "json",
    "v" => "true",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/aliases?format=json&v=true"
client.cat().aliases();
Response examples (200)
A successful response from `GET _cat/aliases?format=json&v=true`. This response shows that `alias2` has configured a filter and `alias3` and `alias4` have routing configurations.
[
  {
    "alias": "alias1",
    "index": "test1",
    "filter": "-",
    "routing.index": "-",
    "routing.search": "-",
    "is_write_index": "true"
  },
  {
    "alias": "alias1",
    "index": "test1",
    "filter": "*",
    "routing.index": "-",
    "routing.search": "-",
    "is_write_index": "true"
  },
  {
    "alias": "alias3",
    "index": "test1",
    "filter": "-",
    "routing.index": "1",
    "routing.search": "1",
    "is_write_index": "true"
  },
  {
    "alias": "alias4",
    "index": "test1",
    "filter": "-",
    "routing.index": "2",
    "routing.search": "1,2",
    "is_write_index": "true"
  }
]




































































Get snapshot repository information Generally available; 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.

Required authorization

  • Cluster privileges: monitor_snapshot

Query parameters

  • h string | array[string]

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

  • s string | array[string]

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

  • local boolean

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

  • master_timeout string

    Period to wait for a connection to the master node.

    Values are -1 or 0.

Responses

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

      The unique repository identifier.

    • type string

      The repository type.

GET /_cat/repositories?v=true&format=json
resp = client.cat.repositories(
    v=True,
    format="json",
)
const response = await client.cat.repositories({
  v: "true",
  format: "json",
});
response = client.cat.repositories(
  v: "true",
  format: "json"
)
$resp = $client->cat()->repositories([
    "v" => "true",
    "format" => "json",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/repositories?v=true&format=json"
client.cat().repositories();
Response examples (200)
A successful response from `GET /_cat/repositories?v=true&format=json`.
[
  {
    "id": "repo1",
    "type": "fs"
  },
  {
    "id": "repo2",
    "type": "s3"
  }
]









































































Get cluster statistics Generally available; Added in 1.3.0

GET /_cluster/stats/nodes/{node_id}

All methods and paths for this operation:

GET /_cluster/stats

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

Required authorization

  • Cluster privileges: monitor

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_remotes boolean

    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.

    Values are -1 or 0.

Responses

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

      Contains statistics about the number of nodes selected by the request.

      Hide _nodes attributes Show _nodes attributes object
      • failures array[object]

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

        Hide failures attributes Show failures attributes object
        • type string Required

          The type of error

        • reason string | null

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

        • stack_trace string

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

        • caused_by object

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

        • root_cause array[object]

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

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

        • suppressed array[object]

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

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

      • 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
      Hide indices attributes Show indices attributes object
      • analysis object
        Hide analysis attributes Show analysis attributes object
        • analyzer_types array[object] Required

          Contains statistics about analyzer types used in selected nodes.

          Hide analyzer_types attributes Show analyzer_types attributes object
          • name string Required
          • count number Required

            The number of occurrences of the field type in selected nodes.

          • index_count number Required

            The number of indices containing the field type in selected nodes.

          • indexed_vector_count number

            For dense_vector field types, number of indexed vector types in selected nodes.

          • indexed_vector_dim_max number

            For dense_vector field types, the maximum dimension of all indexed vector types in selected nodes.

          • indexed_vector_dim_min number

            For dense_vector field types, the minimum dimension of all indexed vector types in selected nodes.

          • script_count number Generally available; Added in 7.13.0

            The number of fields that declare a script.

          • vector_index_type_count object

            For dense_vector field types, count of mappings by index type

          • vector_similarity_type_count object

            For dense_vector field types, count of mappings by similarity

          • vector_element_type_count object

            For dense_vector field types, count of mappings by element type

        • built_in_analyzers array[object] Required

          Contains statistics about built-in analyzers used in selected nodes.

          Hide built_in_analyzers attributes Show built_in_analyzers attributes object
          • name string Required
          • count number Required

            The number of occurrences of the field type in selected nodes.

          • index_count number Required

            The number of indices containing the field type in selected nodes.

          • indexed_vector_count number

            For dense_vector field types, number of indexed vector types in selected nodes.

          • indexed_vector_dim_max number

            For dense_vector field types, the maximum dimension of all indexed vector types in selected nodes.

          • indexed_vector_dim_min number

            For dense_vector field types, the minimum dimension of all indexed vector types in selected nodes.

          • script_count number Generally available; Added in 7.13.0

            The number of fields that declare a script.

          • vector_index_type_count object

            For dense_vector field types, count of mappings by index type

          • vector_similarity_type_count object

            For dense_vector field types, count of mappings by similarity

          • vector_element_type_count object

            For dense_vector field types, count of mappings by element type

        • built_in_char_filters array[object] Required

          Contains statistics about built-in character filters used in selected nodes.

          Hide built_in_char_filters attributes Show built_in_char_filters attributes object
          • name string Required
          • count number Required

            The number of occurrences of the field type in selected nodes.

          • index_count number Required

            The number of indices containing the field type in selected nodes.

          • indexed_vector_count number

            For dense_vector field types, number of indexed vector types in selected nodes.

          • indexed_vector_dim_max number

            For dense_vector field types, the maximum dimension of all indexed vector types in selected nodes.

          • indexed_vector_dim_min number

            For dense_vector field types, the minimum dimension of all indexed vector types in selected nodes.

          • script_count number Generally available; Added in 7.13.0

            The number of fields that declare a script.

          • vector_index_type_count object

            For dense_vector field types, count of mappings by index type

          • vector_similarity_type_count object

            For dense_vector field types, count of mappings by similarity

          • vector_element_type_count object

            For dense_vector field types, count of mappings by element type

        • built_in_filters array[object] Required

          Contains statistics about built-in token filters used in selected nodes.

          Hide built_in_filters attributes Show built_in_filters attributes object
          • name string Required
          • count number Required

            The number of occurrences of the field type in selected nodes.

          • index_count number Required

            The number of indices containing the field type in selected nodes.

          • indexed_vector_count number

            For dense_vector field types, number of indexed vector types in selected nodes.

          • indexed_vector_dim_max number

            For dense_vector field types, the maximum dimension of all indexed vector types in selected nodes.

          • indexed_vector_dim_min number

            For dense_vector field types, the minimum dimension of all indexed vector types in selected nodes.

          • script_count number Generally available; Added in 7.13.0

            The number of fields that declare a script.

          • vector_index_type_count object

            For dense_vector field types, count of mappings by index type

          • vector_similarity_type_count object

            For dense_vector field types, count of mappings by similarity

          • vector_element_type_count object

            For dense_vector field types, count of mappings by element type

        • built_in_tokenizers array[object] Required

          Contains statistics about built-in tokenizers used in selected nodes.

          Hide built_in_tokenizers attributes Show built_in_tokenizers attributes object
          • name string Required
          • count number Required

            The number of occurrences of the field type in selected nodes.

          • index_count number Required

            The number of indices containing the field type in selected nodes.

          • indexed_vector_count number

            For dense_vector field types, number of indexed vector types in selected nodes.

          • indexed_vector_dim_max number

            For dense_vector field types, the maximum dimension of all indexed vector types in selected nodes.

          • indexed_vector_dim_min number

            For dense_vector field types, the minimum dimension of all indexed vector types in selected nodes.

          • script_count number Generally available; Added in 7.13.0

            The number of fields that declare a script.

          • vector_index_type_count object

            For dense_vector field types, count of mappings by index type

          • vector_similarity_type_count object

            For dense_vector field types, count of mappings by similarity

          • vector_element_type_count object

            For dense_vector field types, count of mappings by element type

        • char_filter_types array[object] Required

          Contains statistics about character filter types used in selected nodes.

          Hide char_filter_types attributes Show char_filter_types attributes object
          • name string Required
          • count number Required

            The number of occurrences of the field type in selected nodes.

          • index_count number Required

            The number of indices containing the field type in selected nodes.

          • indexed_vector_count number

            For dense_vector field types, number of indexed vector types in selected nodes.

          • indexed_vector_dim_max number

            For dense_vector field types, the maximum dimension of all indexed vector types in selected nodes.

          • indexed_vector_dim_min number

            For dense_vector field types, the minimum dimension of all indexed vector types in selected nodes.

          • script_count number Generally available; Added in 7.13.0

            The number of fields that declare a script.

          • vector_index_type_count object

            For dense_vector field types, count of mappings by index type

          • vector_similarity_type_count object

            For dense_vector field types, count of mappings by similarity

          • vector_element_type_count object

            For dense_vector field types, count of mappings by element type

        • filter_types array[object] Required

          Contains statistics about token filter types used in selected nodes.

          Hide filter_types attributes Show filter_types attributes object
          • name string Required
          • count number Required

            The number of occurrences of the field type in selected nodes.

          • index_count number Required

            The number of indices containing the field type in selected nodes.

          • indexed_vector_count number

            For dense_vector field types, number of indexed vector types in selected nodes.

          • indexed_vector_dim_max number

            For dense_vector field types, the maximum dimension of all indexed vector types in selected nodes.

          • indexed_vector_dim_min number

            For dense_vector field types, the minimum dimension of all indexed vector types in selected nodes.

          • script_count number Generally available; Added in 7.13.0

            The number of fields that declare a script.

          • vector_index_type_count object

            For dense_vector field types, count of mappings by index type

          • vector_similarity_type_count object

            For dense_vector field types, count of mappings by similarity

          • vector_element_type_count object

            For dense_vector field types, count of mappings by element type

        • tokenizer_types array[object] Required

          Contains statistics about tokenizer types used in selected nodes.

          Hide tokenizer_types attributes Show tokenizer_types attributes object
          • name string Required
          • count number Required

            The number of occurrences of the field type in selected nodes.

          • index_count number Required

            The number of indices containing the field type in selected nodes.

          • indexed_vector_count number

            For dense_vector field types, number of indexed vector types in selected nodes.

          • indexed_vector_dim_max number

            For dense_vector field types, the maximum dimension of all indexed vector types in selected nodes.

          • indexed_vector_dim_min number

            For dense_vector field types, the minimum dimension of all indexed vector types in selected nodes.

          • script_count number Generally available; Added in 7.13.0

            The number of fields that declare a script.

          • vector_index_type_count object

            For dense_vector field types, count of mappings by index type

          • vector_similarity_type_count object

            For dense_vector field types, count of mappings by similarity

          • vector_element_type_count object

            For dense_vector field types, count of mappings by element type

        • synonyms object Required

          Contains statistics about synonyms types used in selected nodes.

          Hide synonyms attribute Show synonyms attribute object
          • * object Additional properties
            Hide * attributes Show * attributes object
            • count number Required
            • index_count number Required
      • completion object Required
        Hide completion attributes Show completion attributes object
        • size_in_bytes number Required

          Total amount, in bytes, of memory used for completion across all shards assigned to selected nodes.

        • size number | string

        • fields object
          Hide fields attribute Show fields attribute object
          • * object Additional properties
            Hide * attributes Show * attributes object
            • size
            • size_in_bytes number Required
      • count number Required

        Total number of indices with shards assigned to selected nodes.

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

          Total number of non-deleted documents across all primary shards assigned to selected nodes. This number is based on documents in Lucene segments and may include documents from nested fields.

        • deleted number

          Total number of deleted documents across all primary shards assigned to selected nodes. This number is based on documents in Lucene segments. Elasticsearch reclaims the disk space of deleted Lucene documents when a segment is merged.

        • total_size_in_bytes number Required

          Returns the total size in bytes of all documents in this stats. This value may be more reliable than store_stats.size_in_bytes in estimating the index size.

        • total_size number | string

      • fielddata object Required
        Hide fielddata attributes Show fielddata attributes object
        • evictions number
        • memory_size number | string

        • memory_size_in_bytes number Required
        • fields object
          Hide fields attribute Show fields attribute object
          • * object Additional properties
            Hide * attributes Show * attributes object
            • memory_size
            • memory_size_in_bytes number Required
        • global_ordinals object Required
          Hide global_ordinals attributes Show global_ordinals attributes object
          • build_time_in_millis number Required

            Time unit for milliseconds

          • build_time string
          • fields object
            Hide fields attribute Show fields attribute object
            • * object Additional properties
      • query_cache object Required
        Hide query_cache attributes Show query_cache attributes object
        • cache_count number Required

          Total number of entries added to the query cache across all shards assigned to selected nodes. This number includes current and evicted entries.

        • cache_size number Required

          Total number of entries currently in the query cache across all shards assigned to selected nodes.

        • evictions number Required

          Total number of query cache evictions across all shards assigned to selected nodes.

        • hit_count number Required

          Total count of query cache hits across all shards assigned to selected nodes.

        • memory_size number | string

        • memory_size_in_bytes number Required

          Total amount, in bytes, of memory used for the query cache across all shards assigned to selected nodes.

        • miss_count number Required

          Total count of query cache misses across all shards assigned to selected nodes.

        • total_count number Required

          Total count of hits and misses in the query cache across all shards assigned to selected nodes.

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

          Total number of segments across all shards assigned to selected nodes.

        • doc_values_memory number | string

        • doc_values_memory_in_bytes number Required

          Total amount, in bytes, of memory used for doc values across all shards assigned to selected nodes.

        • file_sizes object Required

          This object is not populated by the cluster stats API. To get information on segment files, use the node stats API.

          Hide file_sizes attribute Show file_sizes attribute object
          • * object Additional properties
            Hide * attributes Show * attributes object
            • description string Required
            • size_in_bytes number Required
            • min_size_in_bytes number
            • max_size_in_bytes number
            • average_size_in_bytes number
            • count number
        • fixed_bit_set number | string

        • fixed_bit_set_memory_in_bytes number Required

          Total amount of memory, in bytes, used by fixed bit sets across all shards assigned to selected nodes.

        • index_writer_memory number | string

        • index_writer_memory_in_bytes number Required

          Total amount, in bytes, of memory used by all index writers across all shards assigned to selected nodes.

        • max_unsafe_auto_id_timestamp number Required

          Unix timestamp, in milliseconds, of the most recently retried indexing request.

        • memory number | string

        • memory_in_bytes number Required

          Total amount, in bytes, of memory used for segments across all shards assigned to selected nodes.

        • norms_memory number | string

        • norms_memory_in_bytes number Required

          Total amount, in bytes, of memory used for normalization factors across all shards assigned to selected nodes.

        • points_memory number | string

        • points_memory_in_bytes number Required

          Total amount, in bytes, of memory used for points across all shards assigned to selected nodes.

        • stored_fields_memory_in_bytes number Required

          Total amount, in bytes, of memory used for stored fields across all shards assigned to selected nodes.

        • stored_fields_memory number | string

        • terms_memory_in_bytes number Required

          Total amount, in bytes, of memory used for terms across all shards assigned to selected nodes.

        • terms_memory number | string

        • term_vectors_memory number | string

        • term_vectors_memory_in_bytes number Required

          Total amount, in bytes, of memory used for term vectors across all shards assigned to selected nodes.

        • version_map_memory number | string

        • version_map_memory_in_bytes number Required

          Total amount, in bytes, of memory used by all version maps across all shards assigned to selected nodes.

      • shards object Required

        Contains statistics about shards assigned to selected nodes.

        Hide shards attributes Show shards attributes object
        • index object
          Hide index attributes Show index attributes object
          • primaries object Required
            Hide primaries attributes Show primaries attributes object
            • avg number Required

              Mean number of shards in an index, counting only shards assigned to selected nodes.

            • max number Required

              Maximum number of shards in an index, counting only shards assigned to selected nodes.

            • min number Required

              Minimum number of shards in an index, counting only shards assigned to selected nodes.

          • replication object Required
            Hide replication attributes Show replication attributes object
            • avg number Required

              Mean number of shards in an index, counting only shards assigned to selected nodes.

            • max number Required

              Maximum number of shards in an index, counting only shards assigned to selected nodes.

            • min number Required

              Minimum number of shards in an index, counting only shards assigned to selected nodes.

          • shards object Required
            Hide shards attributes Show shards attributes object
            • avg number Required

              Mean number of shards in an index, counting only shards assigned to selected nodes.

            • max number Required

              Maximum number of shards in an index, counting only shards assigned to selected nodes.

            • min number Required

              Minimum number of shards in an index, counting only shards assigned to selected nodes.

        • primaries number

          Number of primary shards assigned to selected nodes.

        • replication number

          Ratio of replica shards to primary shards across all selected nodes.

        • total number

          Total number of shards assigned to selected nodes.

      • store object Required
        Hide store attributes Show store attributes object
        • size number | string

        • size_in_bytes number Required

          Total size, in bytes, of all shards assigned to selected nodes.

        • reserved number | string

        • reserved_in_bytes number Required

          A prediction, in bytes, of how much larger the shard stores will eventually grow due to ongoing peer recoveries, restoring snapshots, and similar activities.

        • total_data_set_size number | string

        • total_data_set_size_in_bytes number

          Total data set size, in bytes, of all shards assigned to selected nodes. This includes the size of shards not stored fully on the nodes, such as the cache for partially mounted indices.

      • mappings object
        Hide mappings attributes Show mappings attributes object
        • field_types array[object] Required

          Contains statistics about field data types used in selected nodes.

          Hide field_types attributes Show field_types attributes object
          • name string Required
          • count number Required

            The number of occurrences of the field type in selected nodes.

          • index_count number Required

            The number of indices containing the field type in selected nodes.

          • indexed_vector_count number

            For dense_vector field types, number of indexed vector types in selected nodes.

          • indexed_vector_dim_max number

            For dense_vector field types, the maximum dimension of all indexed vector types in selected nodes.

          • indexed_vector_dim_min number

            For dense_vector field types, the minimum dimension of all indexed vector types in selected nodes.

          • script_count number Generally available; Added in 7.13.0

            The number of fields that declare a script.

          • vector_index_type_count object

            For dense_vector field types, count of mappings by index type

          • vector_similarity_type_count object

            For dense_vector field types, count of mappings by similarity

          • vector_element_type_count object

            For dense_vector field types, count of mappings by element type

        • runtime_field_types array[object] Required

          Contains statistics about runtime field data types used in selected nodes.

          Hide runtime_field_types attributes Show runtime_field_types attributes object
          • chars_max number Required

            Maximum number of characters for a single runtime field script.

          • chars_total number Required

            Total number of characters for the scripts that define the current runtime field data type.

          • count number Required

            Number of runtime fields mapped to the field data type in selected nodes.

          • doc_max number Required

            Maximum number of accesses to doc_values for a single runtime field script

          • doc_total number Required

            Total number of accesses to doc_values for the scripts that define the current runtime field data type.

          • index_count number Required

            Number of indices containing a mapping of the runtime field data type in selected nodes.

          • lang array[string] Required

            Script languages used for the runtime fields scripts.

          • lines_max number Required

            Maximum number of lines for a single runtime field script.

          • lines_total number Required

            Total number of lines for the scripts that define the current runtime field data type.

          • name string Required
          • scriptless_count number Required

            Number of runtime fields that don’t declare a script.

          • shadowed_count number Required

            Number of runtime fields that shadow an indexed field.

          • source_max number Required

            Maximum number of accesses to _source for a single runtime field script.

          • source_total number Required

            Total number of accesses to _source for the scripts that define the current runtime field data type.

        • total_field_count number

          Total number of fields in all non-system indices.

        • total_deduplicated_field_count number

          Total number of fields in all non-system indices, accounting for mapping deduplication.

        • total_deduplicated_mapping_size number | string

        • total_deduplicated_mapping_size_in_bytes number

          Total size of all mappings, in bytes, after deduplication and compression.

        • source_modes object Required

          Source mode usage count.

          Hide source_modes attribute Show source_modes attribute object
          • * number Additional properties
      • versions array[object]

        Contains statistics about analyzers and analyzer components used in selected nodes.

        Hide versions attributes Show versions attributes object
        • index_count number Required
        • primary_shard_count number Required
        • total_primary_bytes number Required
        • total_primary_size number | string

        • version string Required
      • dense_vector object Required
        Hide dense_vector attributes Show dense_vector attributes object
      • sparse_vector object Required
        Hide sparse_vector attribute Show sparse_vector attribute object
        • value_count number Required
    • nodes object Required
      Hide nodes attributes Show nodes attributes object
      • count object Required
        Hide count attributes Show count attributes object
        • total number Required
        • coordinating_only number
        • data number
        • data_cold number
        • data_content number
        • data_frozen number Generally available; Added in 7.13.0
        • data_hot number
        • data_warm number
        • index number
        • ingest number
        • master number
        • ml number
        • remote_cluster_client number
        • transform number
        • voting_only number
      • 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
        Hide fs attributes Show fs attributes object
      • indexing_pressure object Required
        Hide indexing_pressure attribute Show indexing_pressure attribute object
        • memory object Required
          Hide memory attributes Show memory attributes object
          • limit number | string

          • limit_in_bytes number

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

          • current object
            Hide current attributes Show current attributes object
            • all
            • all_in_bytes number

              Memory consumed, in bytes, by indexing requests in the coordinating, primary, or replica stage.

            • combined_coordinating_and_primary
            • combined_coordinating_and_primary_in_bytes number

              Memory consumed, in bytes, by indexing requests in the coordinating or primary stage. This value is not the sum of coordinating and primary as a node can reuse the coordinating memory if the primary stage is executed locally.

            • coordinating
            • coordinating_in_bytes number

              Memory consumed, in bytes, by indexing requests in the coordinating stage.

            • primary
            • primary_in_bytes number

              Memory consumed, in bytes, by indexing requests in the primary stage.

            • replica
            • replica_in_bytes number

              Memory consumed, in bytes, by indexing requests in the replica stage.

            • coordinating_rejections number

              Number of indexing requests rejected in the coordinating stage.

            • primary_rejections number

              Number of indexing requests rejected in the primary stage.

            • replica_rejections number

              Number of indexing requests rejected in the replica stage.

            • primary_document_rejections number
            • large_operation_rejections number
          • total object
            Hide total attributes Show total attributes object
            • all
            • all_in_bytes number

              Memory consumed, in bytes, by indexing requests in the coordinating, primary, or replica stage.

            • combined_coordinating_and_primary
            • combined_coordinating_and_primary_in_bytes number

              Memory consumed, in bytes, by indexing requests in the coordinating or primary stage. This value is not the sum of coordinating and primary as a node can reuse the coordinating memory if the primary stage is executed locally.

            • coordinating
            • coordinating_in_bytes number

              Memory consumed, in bytes, by indexing requests in the coordinating stage.

            • primary
            • primary_in_bytes number

              Memory consumed, in bytes, by indexing requests in the primary stage.

            • replica
            • replica_in_bytes number

              Memory consumed, in bytes, by indexing requests in the replica stage.

            • coordinating_rejections number

              Number of indexing requests rejected in the coordinating stage.

            • primary_rejections number

              Number of indexing requests rejected in the primary stage.

            • replica_rejections number

              Number of indexing requests rejected in the replica stage.

            • primary_document_rejections number
            • large_operation_rejections number
      • ingest object Required
        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
            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
        Hide jvm attributes Show jvm attributes object
        • Time unit for milliseconds

        • max_uptime 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 Required
          Hide mem attributes Show mem attributes object
        • 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
          • bundled_jdk boolean Required

            Always true. All distributions come with a bundled Java Development Kit (JDK).

          • count number Required

            Total number of selected nodes using JVM.

          • using_bundled_jdk boolean Required

            If true, a bundled JDK is in use by JVM.

          • version string Required
          • vm_name string Required

            Name of the JVM.

          • vm_vendor string Required

            Vendor of the JVM.

          • vm_version string Required
      • network_types object Required
        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
        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
          Hide mem attributes Show mem attributes object
          • adjusted_total_in_bytes number Generally available; Added in 7.16.0

            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.

          • adjusted_total number | string

          • free_in_bytes number Required

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

          • free number | string

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

          • total number | string

          • used_in_bytes number Required

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

          • used number | string

          • 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
        • classname string Required
        • description string Required
        • elasticsearch_version string Required
        • extended_plugins array[string] Required
        • has_native_controller boolean Required
        • java_version string Required
        • name string Required
        • version string Required
        • licensed boolean Required
      • process object Required
        Hide process attributes Show process attributes object
        • cpu object Required
          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
          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.

    • repositories object Required

      Contains stats on repository feature usage exposed in cluster stats for telemetry.

      Hide repositories attribute Show repositories attribute object
      • * object Additional properties
        Hide * attribute Show * attribute object
        • * number Additional properties
    • snapshots object Required
      Hide snapshots attributes Show snapshots attributes object
      • current_counts object Required
        Hide current_counts attributes Show current_counts attributes object
        • snapshots number Required

          Snapshots currently in progress

        • shard_snapshots number Required

          Incomplete shard snapshots

        • snapshot_deletions number Required

          Snapshots deletions in progress

        • concurrent_operations number Required

          Sum of snapshots and snapshot_deletions

        • cleanups number Required

          Cleanups in progress, not counted in concurrent_operations as they are not concurrent

      • repositories object Required
        Hide repositories attribute Show repositories attribute object
        • * object Additional properties
          Hide * attributes Show * attributes object
          • type string Required
          • oldest_start_time_millis number Required

            Time unit for milliseconds

          • oldest_start_time string
          • current_counts object Required
            Hide current_counts attributes Show current_counts attributes object
            • snapshots number Required
            • clones number Required
            • finalizations number Required
            • deletions number Required
            • snapshot_deletions number Required
            • active_deletions number Required
            • shards object Required
    • status string

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

    • timestamp number Required

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

    • ccs object Required
      Hide ccs attributes Show ccs attributes object
      • clusters object

        Contains remote cluster settings and metrics collected from them. The keys are cluster names, and the values are per-cluster data. Only present if include_remotes option is set to true.

        Hide clusters attribute Show clusters attribute object
        • * object Additional properties
          Hide * attributes Show * attributes object
          • cluster_uuid string Required

            The UUID of the remote cluster.

          • mode string Required

            The connection mode used to communicate with the remote cluster.

          • skip_unavailable boolean Required

            The skip_unavailable setting used for this remote cluster.

          • transport.compress string Required

            Transport compression setting used for this remote cluster.

          • status string Required

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

          • version array[string] Required

            The list of Elasticsearch versions used by the nodes on the remote cluster.

          • nodes_count number Required

            The total count of nodes in the remote cluster.

          • shards_count number Required

            The total number of shards in the remote cluster.

          • indices_count number Required

            The total number of indices in the remote cluster.

          • indices_total_size_in_bytes number Required

            Total data set size, in bytes, of all shards assigned to selected nodes.

          • indices_total_size string

            Total data set size of all shards assigned to selected nodes, as a human-readable string.

          • max_heap_in_bytes number Required

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

          • max_heap string

            Maximum amount of memory available for use by the heap across the nodes of the remote cluster, as a human-readable string.

          • mem_total_in_bytes number Required

            Total amount, in bytes, of physical memory across the nodes of the remote cluster.

          • mem_total string

            Total amount of physical memory across the nodes of the remote cluster, as a human-readable string.

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

          The total number of cross-cluster search requests that have been executed by the cluster.

        • success number Required

          The total number of cross-cluster search requests that have been successfully executed by the cluster.

        • skipped number Required

          The total number of cross-cluster search requests (successful or failed) that had at least one remote cluster skipped.

        • took object Required
          Hide took attributes Show took attributes object
          • Time unit for milliseconds

          • Time unit for milliseconds

          • Time unit for milliseconds

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

          • Time unit for milliseconds

          • Time unit for milliseconds

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

          • Time unit for milliseconds

          • Time unit for milliseconds

        • remotes_per_search_max number Required

          The maximum number of remote clusters that were queried in a single cross-cluster search request.

        • remotes_per_search_avg number Required

          The average number of remote clusters that were queried in a single cross-cluster search request.

        • failure_reasons object Required

          Statistics about the reasons for cross-cluster search request failures. The keys are the failure reason names and the values are the number of requests that failed for that reason.

          Hide failure_reasons attribute Show failure_reasons attribute object
          • * number Additional properties
        • features object Required

          The keys are the names of the search feature, and the values are the number of requests that used that feature. Single request can use more than one feature (e.g. both async and wildcard).

          Hide features attribute Show features attribute object
          • * number Additional properties
        • clients object Required

          Statistics about the clients that executed cross-cluster search requests. The keys are the names of the clients, and the values are the number of requests that were executed by that client. Only known clients (such as kibana or elasticsearch) are counted.

          Hide clients attribute Show clients attribute object
          • * number Additional properties
        • clusters object Required

          Statistics about the clusters that were queried in cross-cluster search requests. The keys are cluster names, and the values are per-cluster telemetry data. This also includes the local cluster itself, which uses the name (local).

          Hide clusters attribute Show clusters attribute object
          • * object Additional properties
            Hide * attributes Show * attributes object
            • total number Required

              The total number of successful (not skipped) cross-cluster search requests that were executed against this cluster. This may include requests where partial results were returned, but not requests in which the cluster has been skipped entirely.

            • skipped number Required

              The total number of cross-cluster search requests for which this cluster was skipped.

            • took object Required
GET /_cluster/stats/nodes/{node_id}
GET _cluster/stats?human&filter_path=indices.mappings.total_deduplicated_mapping_size*
resp = client.cluster.stats(
    human=True,
    filter_path="indices.mappings.total_deduplicated_mapping_size*",
)
const response = await client.cluster.stats({
  human: "true",
  filter_path: "indices.mappings.total_deduplicated_mapping_size*",
});
response = client.cluster.stats(
  human: "true",
  filter_path: "indices.mappings.total_deduplicated_mapping_size*"
)
$resp = $client->cluster()->stats([
    "human" => "true",
    "filter_path" => "indices.mappings.total_deduplicated_mapping_size*",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cluster/stats?human&filter_path=indices.mappings.total_deduplicated_mapping_size*"




Clear the archived repositories metering Technical preview; Added in 7.16.0

DELETE /_nodes/{node_id}/_repositories_metering/{max_archive_version}

Clear the archived repositories metering information in the cluster.

Required authorization

  • Cluster privileges: monitor,manage

Path parameters

  • node_id string | array[string] Required

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

  • max_archive_version number Required

    Specifies the maximum archive_version to be cleared from the archive.

Responses

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

      Contains statistics about the number of nodes selected by the request.

      Hide _nodes attributes Show _nodes attributes object
      • failures array[object]

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

        Hide failures attributes Show failures attributes object
        • type string Required

          The type of error

        • reason string | null

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

        • stack_trace string

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

        • caused_by object

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

        • root_cause array[object]

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

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

        • suppressed array[object]

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

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

      • 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

      Contains repositories metering information for the nodes selected by the request.

      Hide nodes attribute Show nodes attribute object
      • * object Additional properties
        Hide * attributes Show * attributes object
        • repository_name string Required
        • repository_type string Required

          Repository type.

        • repository_location object Required
          Hide repository_location attributes Show repository_location attributes object
          • base_path string Required
          • container string

            Container name (Azure)

          • bucket string

            Bucket name (GCP, S3)

        • repository_ephemeral_id string Required
        • Time unit for milliseconds

        • Time unit for milliseconds

        • archived boolean Required

          A flag that tells whether or not this object has been archived. When a repository is closed or updated the repository metering information is archived and kept for a certain period of time. This allows retrieving the repository metering information of previous repository instantiations.

        • cluster_version number
        • request_counts object Required
          Hide request_counts attributes Show request_counts attributes object
          • GetBlobProperties number

            Number of Get Blob Properties requests (Azure)

          • GetBlob number

            Number of Get Blob requests (Azure)

          • ListBlobs number

            Number of List Blobs requests (Azure)

          • PutBlob number

            Number of Put Blob requests (Azure)

          • PutBlock number

            Number of Put Block (Azure)

          • PutBlockList number

            Number of Put Block List requests

          • GetObject number

            Number of get object requests (GCP, S3)

          • ListObjects number

            Number of list objects requests (GCP, S3)

          • InsertObject number

            Number of insert object requests, including simple, multipart and resumable uploads. Resumable uploads can perform multiple http requests to insert a single object but they are considered as a single request since they are billed as an individual operation. (GCP)

          • PutObject number

            Number of PutObject requests (S3)

          • PutMultipartObject number

            Number of Multipart requests, including CreateMultipartUpload, UploadPart and CompleteMultipartUpload requests (S3)

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

Get cluster repositories metering Technical preview; Added in 7.16.0

GET /_nodes/{node_id}/_repositories_metering

Get repositories metering information for a cluster. This API exposes monotonically non-decreasing counters and it is expected that clients would durably store the information needed to compute aggregations over a period of time. Additionally, the information exposed by this API is volatile, meaning that it will not be present after node restarts.

Required authorization

  • Cluster privileges: monitor,manage

Path parameters

  • node_id string | array[string] Required

    Comma-separated list of node IDs or names used to limit returned information. For more information about the nodes selective options, refer to the node specification documentation.

Responses

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

      Contains statistics about the number of nodes selected by the request.

      Hide _nodes attributes Show _nodes attributes object
      • failures array[object]

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

        Hide failures attributes Show failures attributes object
        • type string Required

          The type of error

        • reason string | null

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

        • stack_trace string

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

        • caused_by object

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

        • root_cause array[object]

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

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

        • suppressed array[object]

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

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

      • 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

      Contains repositories metering information for the nodes selected by the request.

      Hide nodes attribute Show nodes attribute object
      • * object Additional properties
        Hide * attributes Show * attributes object
        • repository_name string Required
        • repository_type string Required

          Repository type.

        • repository_location object Required
          Hide repository_location attributes Show repository_location attributes object
          • base_path string Required
          • container string

            Container name (Azure)

          • bucket string

            Bucket name (GCP, S3)

        • repository_ephemeral_id string Required
        • Time unit for milliseconds

        • Time unit for milliseconds

        • archived boolean Required

          A flag that tells whether or not this object has been archived. When a repository is closed or updated the repository metering information is archived and kept for a certain period of time. This allows retrieving the repository metering information of previous repository instantiations.

        • cluster_version number
        • request_counts object Required
          Hide request_counts attributes Show request_counts attributes object
          • GetBlobProperties number

            Number of Get Blob Properties requests (Azure)

          • GetBlob number

            Number of Get Blob requests (Azure)

          • ListBlobs number

            Number of List Blobs requests (Azure)

          • PutBlob number

            Number of Put Blob requests (Azure)

          • PutBlock number

            Number of Put Block (Azure)

          • PutBlockList number

            Number of Put Block List requests

          • GetObject number

            Number of get object requests (GCP, S3)

          • ListObjects number

            Number of list objects requests (GCP, S3)

          • InsertObject number

            Number of insert object requests, including simple, multipart and resumable uploads. Resumable uploads can perform multiple http requests to insert a single object but they are considered as a single request since they are billed as an individual operation. (GCP)

          • PutObject number

            Number of PutObject requests (S3)

          • PutMultipartObject number

            Number of Multipart requests, including CreateMultipartUpload, UploadPart and CompleteMultipartUpload requests (S3)

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












Get node statistics Generally available

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

All methods and paths for this operation:

GET /_nodes/stats

GET /_nodes/stats/{metric}
GET /_nodes/{node_id}/stats
GET /_nodes/{node_id}/stats/{metric}
GET /_nodes/stats/{metric}/{index_metric}
GET /_nodes/{node_id}/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.

Required authorization

  • Cluster privileges: monitor,manage

Path parameters

  • node_id string | array[string] Required

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

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

  • include_segment_file_sizes boolean

    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.

    Values are -1 or 0.

  • types array[string]

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

  • include_unloaded_segments boolean

    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

      Contains statistics about the number of nodes selected by the request.

      Hide _nodes attributes Show _nodes attributes object
      • failures array[object]

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

        Hide failures attributes Show failures attributes object
        • type string Required

          The type of error

        • reason string | null

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

        • stack_trace string

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

        • caused_by object

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

        • root_cause array[object]

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

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

        • suppressed array[object]

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

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

      • 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
    • nodes object Required
      Hide nodes attribute Show nodes attribute object
      • * object Additional properties
        Hide * attributes Show * attributes object
        • adaptive_selection object

          Statistics about adaptive replica selection.

          Hide adaptive_selection attribute Show adaptive_selection attribute object
          • * object Additional properties
            Hide * attributes Show * attributes object
            • avg_queue_size number

              The exponentially weighted moving average queue size of search requests on the keyed node.

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

            • avg_response_time_ns number

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

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

            • avg_service_time_ns number

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

            • outgoing_searches number

              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
            Hide * attributes Show * attributes object
            • estimated_size string

              Estimated memory used for the operation.

            • estimated_size_in_bytes number

              Estimated memory used, in bytes, for the operation.

            • limit_size string

              Memory limit for the circuit breaker.

            • limit_size_in_bytes number

              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
          Hide fs attributes Show fs attributes object
          • data array[object]

            List of all file stores.

          • timestamp number

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

          • total object
            Hide total attributes Show total attributes object
            • available string

              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.

            • available_in_bytes number

              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.

            • free_in_bytes number

              Total number of unallocated bytes in all file stores.

            • total string

              Total size of all file stores.

            • total_in_bytes number

              Total size of all file stores in bytes.

          • io_stats object
            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
        • host string
        • http object
          Hide http attributes Show http attributes object
          • current_open number

            Current number of open HTTP connections for the node.

          • total_opened number

            Total number of HTTP connections opened for the node.

          • clients array[object]

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

          • routes object Required Generally available; Added in 8.12.0

            Detailed HTTP stats broken down by route

            Hide routes attribute Show routes attribute object
            • * object Additional properties
        • ingest object
          Hide ingest attributes Show ingest attributes object
          • pipelines object

            Contains statistics about ingest pipelines for the node.

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

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

            • current number Required

              Total number of documents currently being ingested.

            • failed number Required

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

        • ip string | array[string]

          IP address and port for the node.

        • jvm object
          Hide jvm attributes Show jvm attributes object
          • buffer_pools object

            Contains statistics about JVM buffer pools for the node.

            Hide buffer_pools attribute Show buffer_pools attribute object
            • * object Additional properties
          • classes object
            Hide classes attributes Show classes attributes object
            • current_loaded_count number

              Number of classes currently loaded by JVM.

            • total_loaded_count number

              Total number of classes loaded since the JVM started.

            • total_unloaded_count number

              Total number of classes unloaded since the JVM started.

          • gc object
            Hide gc attribute Show gc attribute object
            • collectors object

              Contains statistics about JVM garbage collectors for the node.

          • mem object
            Hide mem attributes Show mem attributes object
            • heap_used_in_bytes number

              Memory, in bytes, currently in use by the heap.

            • heap_used_percent number

              Percentage of memory currently in use by the heap.

            • heap_committed_in_bytes number

              Amount of memory, in bytes, available for use by the heap.

            • heap_max_in_bytes number

              Maximum amount of memory, in bytes, available for use by the heap.

            • heap_max
            • non_heap_used_in_bytes number

              Non-heap memory used, in bytes.

            • non_heap_committed_in_bytes number

              Amount of non-heap memory available, in bytes.

            • pools object

              Contains statistics about heap memory usage for the node.

          • threads object
            Hide threads attributes Show threads attributes object
            • count number

              Number of active threads in use by JVM.

            • peak_count number

              Highest number of threads used by JVM.

          • timestamp number

            Last time JVM statistics were refreshed.

          • uptime string

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

          • uptime_in_millis number

            JVM uptime in milliseconds.

        • name string
        • os object
          Hide os attributes Show os attributes object
          • cpu object
            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.

            • load_average object
          • swap object
            Hide swap attributes Show swap attributes object
            • adjusted_total_in_bytes number

              If the amount of physical memory has been overridden using the es.total_memory_bytes system property then this reports the overridden value in bytes. Otherwise it reports the same value as total_in_bytes.

            • resident string
            • resident_in_bytes number
            • share string
            • share_in_bytes number
            • total_virtual string
            • total_virtual_in_bytes number
            • total_in_bytes number

              Total amount of physical memory in bytes.

            • free_in_bytes number

              Amount of free physical memory in bytes.

            • used_in_bytes number

              Amount of used physical memory in bytes.

          • cgroup object
            Hide cgroup attributes Show cgroup attributes object
            • cpuacct object
            • cpu object
            • memory object
          • timestamp number
        • process object
          Hide process attributes Show process attributes object
          • cpu object
            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.

            • load_average object
          • mem object
            Hide mem attributes Show mem attributes object
            • adjusted_total_in_bytes number

              If the amount of physical memory has been overridden using the es.total_memory_bytes system property then this reports the overridden value in bytes. Otherwise it reports the same value as total_in_bytes.

            • resident string
            • resident_in_bytes number
            • share string
            • share_in_bytes number
            • total_virtual string
            • total_virtual_in_bytes number
            • total_in_bytes number

              Total amount of physical memory in bytes.

            • free_in_bytes number

              Amount of free physical memory in bytes.

            • used_in_bytes number

              Amount of used physical memory in bytes.

          • open_file_descriptors number

            Number of opened file descriptors associated with the current or -1 if not supported.

          • max_file_descriptors number

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

          • timestamp number

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

        • roles array[string]

          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
          Hide script attributes Show script attributes object
          • cache_evictions number

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

          • compilations number

            Total number of inline script compilations performed by the node.

          • compilations_history object

            Contains this recent history of script compilations.

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

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

          • contexts array[object]
        • script_cache object
        • thread_pool object

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

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

              Number of active threads in the thread pool.

            • completed number

              Number of tasks completed by the thread pool executor.

            • largest number

              Highest number of active threads in the thread pool.

            • queue number

              Number of tasks in queue for the thread pool.

            • rejected number

              Number of tasks rejected by the thread pool executor.

            • threads number

              Number of threads in the thread pool.

        • timestamp number
        • transport object
          Hide transport attributes Show transport attributes object
          • inbound_handling_time_histogram array[object]

            The distribution of the time spent handling each inbound message on a transport thread, represented as a histogram.

          • outbound_handling_time_histogram array[object]

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

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

          • rx_size_in_bytes number

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

          • server_open number

            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.

          • tx_size_in_bytes number

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

          • total_outbound_connections number

            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.

        • transport_address string
        • attributes object

          Contains a list of attributes for the node.

          Hide attributes attribute Show attributes attribute object
          • * string Additional properties
        • discovery object
          Hide discovery attributes Show discovery attributes object
          • cluster_state_queue object
            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.

            • committed number

              Number of committed cluster states in queue.

          • published_cluster_states object
            Hide published_cluster_states attributes Show published_cluster_states attributes object
            • full_states number

              Number of published cluster states.

            • incompatible_diffs number

              Number of incompatible differences between published cluster states.

            • compatible_diffs number

              Number of compatible differences between published cluster states.

          • cluster_state_update 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
          • serialized_cluster_states object
            Hide serialized_cluster_states attributes Show serialized_cluster_states attributes object
            • full_states object
            • diffs object
          • cluster_applier_stats object
            Hide cluster_applier_stats attribute Show cluster_applier_stats attribute object
            • recordings array[object]
        • indexing_pressure object
          Hide indexing_pressure attribute Show indexing_pressure attribute object
          • memory object
            Hide memory attributes Show memory attributes object
            • limit
            • limit_in_bytes number

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

            • current object
            • total object
        • indices object
          Hide indices attributes Show indices attributes object
          • commit object
            Hide commit attributes Show commit attributes object
            • generation number Required
            • id string Required
            • num_docs number Required
            • user_data object Required
          • completion object
            Hide completion attributes Show completion attributes object
            • size_in_bytes number Required

              Total amount, in bytes, of memory used for completion across all shards assigned to selected nodes.

            • size
            • fields object
          • docs object
            Hide docs attributes Show docs attributes object
            • count number Required

              Total number of non-deleted documents across all primary shards assigned to selected nodes. This number is based on documents in Lucene segments and may include documents from nested fields.

            • deleted number

              Total number of deleted documents across all primary shards assigned to selected nodes. This number is based on documents in Lucene segments. Elasticsearch reclaims the disk space of deleted Lucene documents when a segment is merged.

            • total_size_in_bytes number Required

              Returns the total size in bytes of all documents in this stats. This value may be more reliable than store_stats.size_in_bytes in estimating the index size.

            • total_size
          • fielddata object
            Hide fielddata attributes Show fielddata attributes object
            • evictions number
            • memory_size
            • memory_size_in_bytes number Required
            • fields object
            • global_ordinals object Required
          • flush object
            Hide flush attributes Show flush attributes object
            • periodic number Required
            • total number Required
            • total_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.

          • get object
            Hide get attributes Show get attributes object
            • current number Required
            • exists_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.

            • exists_total number Required
            • missing_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.

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

            • total number Required
          • indexing object
            Hide indexing attributes Show indexing attributes object
            • index_current number Required
            • delete_current number Required
            • delete_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.

            • delete_total number Required
            • is_throttled boolean Required
            • noop_update_total number Required
            • throttle_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.

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

            • index_total number Required
            • index_failed number Required
            • types object
            • write_load number
          • mappings object
            Hide mappings attributes Show mappings attributes object
            • total_count number Required
            • total_estimated_overhead
            • total_estimated_overhead_in_bytes number Required
          • merges object
            Hide merges attributes Show merges attributes object
            • current number Required
            • current_docs number Required
            • current_size string
            • current_size_in_bytes number Required
            • total number Required
            • total_auto_throttle string
            • total_auto_throttle_in_bytes number Required
            • total_docs number Required
            • total_size string
            • total_size_in_bytes number Required
            • total_stopped_time string

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

            • total_throttled_time string

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

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

          • shard_path object
            Hide shard_path attributes Show shard_path attributes object
            • data_path string Required
            • is_custom_data_path boolean Required
            • state_path string Required
          • query_cache object
            Hide query_cache attributes Show query_cache attributes object
            • cache_count number Required
            • cache_size number Required
            • evictions number Required
            • hit_count number Required
            • memory_size_in_bytes number Required
            • miss_count number Required
            • total_count number Required
          • recovery object
            Hide recovery attributes Show recovery attributes object
            • current_as_source number Required
            • current_as_target number Required
            • throttle_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.

          • refresh object
            Hide refresh attributes Show refresh attributes object
            • external_total number Required
            • listeners number Required
            • total number Required
            • total_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.

          • request_cache object
            Hide request_cache attributes Show request_cache attributes object
            • evictions number Required
            • hit_count number Required
            • memory_size string
            • memory_size_in_bytes number Required
            • miss_count number Required
          • retention_leases object
            Hide retention_leases attributes Show retention_leases attributes object
            • primary_term number Required
            • version number Required
            • leases array[object] Required
          • routing object
            Hide routing attributes Show routing attributes object
            • node string Required
            • primary boolean Required
            • relocating_node
            • state string Required

              Values are UNASSIGNED, INITIALIZING, STARTED, or RELOCATING.

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

              Total number of segments across all shards assigned to selected nodes.

            • doc_values_memory
            • doc_values_memory_in_bytes number Required

              Total amount, in bytes, of memory used for doc values across all shards assigned to selected nodes.

            • file_sizes object Required

              This object is not populated by the cluster stats API. To get information on segment files, use the node stats API.

            • fixed_bit_set
            • fixed_bit_set_memory_in_bytes number Required

              Total amount of memory, in bytes, used by fixed bit sets across all shards assigned to selected nodes.

            • index_writer_memory
            • index_writer_memory_in_bytes number Required

              Total amount, in bytes, of memory used by all index writers across all shards assigned to selected nodes.

            • max_unsafe_auto_id_timestamp number Required

              Unix timestamp, in milliseconds, of the most recently retried indexing request.

            • memory
            • memory_in_bytes number Required

              Total amount, in bytes, of memory used for segments across all shards assigned to selected nodes.

            • norms_memory
            • norms_memory_in_bytes number Required

              Total amount, in bytes, of memory used for normalization factors across all shards assigned to selected nodes.

            • points_memory
            • points_memory_in_bytes number Required

              Total amount, in bytes, of memory used for points across all shards assigned to selected nodes.

            • stored_fields_memory_in_bytes number Required

              Total amount, in bytes, of memory used for stored fields across all shards assigned to selected nodes.

            • stored_fields_memory
            • terms_memory_in_bytes number Required

              Total amount, in bytes, of memory used for terms across all shards assigned to selected nodes.

            • terms_memory
            • term_vectors_memory
            • term_vectors_memory_in_bytes number Required

              Total amount, in bytes, of memory used for term vectors across all shards assigned to selected nodes.

            • version_map_memory
            • version_map_memory_in_bytes number Required

              Total amount, in bytes, of memory used by all version maps across all shards assigned to selected nodes.

          • seq_no object
            Hide seq_no attributes Show seq_no attributes object
            • global_checkpoint number Required
            • local_checkpoint number Required
            • max_seq_no number Required
          • store object
            Hide store attributes Show store attributes object
            • size
            • size_in_bytes number Required

              Total size, in bytes, of all shards assigned to selected nodes.

            • reserved
            • reserved_in_bytes number Required

              A prediction, in bytes, of how much larger the shard stores will eventually grow due to ongoing peer recoveries, restoring snapshots, and similar activities.

            • total_data_set_size
            • total_data_set_size_in_bytes number

              Total data set size, in bytes, of all shards assigned to selected nodes. This includes the size of shards not stored fully on the nodes, such as the cache for partially mounted indices.

          • translog object
            Hide translog attributes Show translog attributes object
            • earliest_last_modified_age number Required
            • operations number Required
            • size string
            • size_in_bytes number Required
            • uncommitted_operations number Required
            • uncommitted_size string
            • uncommitted_size_in_bytes number Required
          • warmer object
            Hide warmer attributes Show warmer attributes object
            • current number Required
            • total number Required
            • total_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.

          • bulk object
            Hide bulk attributes Show bulk attributes object
            • total_operations number Required
            • total_time string

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

            • total_size
            • total_size_in_bytes number Required
            • avg_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.

            • avg_size
            • avg_size_in_bytes number Required
          • shards object Generally available; Added in 7.15.0
            Hide shards attribute Show shards attribute object
            • * object Additional properties
          • shard_stats object
            Hide shard_stats attribute Show shard_stats attribute object
            • total_count number Required
          • indices object Additional properties
            Hide indices attributes Show indices attributes object
            • primaries object
            • shards object
            • total object
            • uuid string
            • health string

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

            • status string

              Values are open or close.

GET /_nodes/{node_id}/stats/{metric}/{index_metric}
GET _nodes/stats/process?filter_path=**.max_file_descriptors
resp = client.nodes.stats(
    metric="process",
    filter_path="**.max_file_descriptors",
)
const response = await client.nodes.stats({
  metric: "process",
  filter_path: "**.max_file_descriptors",
});
response = client.nodes.stats(
  metric: "process",
  filter_path: "**.max_file_descriptors"
)
$resp = $client->nodes()->stats([
    "metric" => "process",
    "filter_path" => "**.max_file_descriptors",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_nodes/stats/process?filter_path=**.max_file_descriptors"









Connector

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

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

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

Check out the connector API tutorial

Check in a connector Technical preview; Added in 8.12.0

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
PUT _connector/my-connector/_check_in
resp = client.connector.check_in(
    connector_id="my-connector",
)
const response = await client.connector.checkIn({
  connector_id: "my-connector",
});
response = client.connector.check_in(
  connector_id: "my-connector"
)
$resp = $client->connector()->checkIn([
    "connector_id" => "my-connector",
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/my-connector/_check_in"
client.connector().checkIn(c -> c
    .connectorId("my-connector")
);
Response examples (200)
{
    "result": "updated"
}




Create or update a connector Beta; Added in 8.12.0

PUT /_connector/{connector_id}

All methods and paths for this operation:

PUT /_connector

PUT /_connector/{connector_id}

Path parameters

  • connector_id string Required

    The unique identifier of the connector to be created or updated. ID is auto-generated if not provided.

application/json

Body

  • description string
  • index_name string
  • is_native boolean
  • language string
  • name string
  • service_type string

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
PUT _connector/my-connector
{
  "index_name": "search-google-drive",
  "name": "My Connector",
  "service_type": "google_drive"
}
resp = client.connector.put(
    connector_id="my-connector",
    index_name="search-google-drive",
    name="My Connector",
    service_type="google_drive",
)
const response = await client.connector.put({
  connector_id: "my-connector",
  index_name: "search-google-drive",
  name: "My Connector",
  service_type: "google_drive",
});
response = client.connector.put(
  connector_id: "my-connector",
  body: {
    "index_name": "search-google-drive",
    "name": "My Connector",
    "service_type": "google_drive"
  }
)
$resp = $client->connector()->put([
    "connector_id" => "my-connector",
    "body" => [
        "index_name" => "search-google-drive",
        "name" => "My Connector",
        "service_type" => "google_drive",
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"index_name":"search-google-drive","name":"My Connector","service_type":"google_drive"}' "$ELASTICSEARCH_URL/_connector/my-connector"
client.connector().put(p -> p
    .connectorId("my-connector")
    .indexName("search-google-drive")
    .name("My Connector")
    .serviceType("google_drive")
);
Request examples
{
  "index_name": "search-google-drive",
  "name": "My Connector",
  "service_type": "google_drive"
}
{
  "index_name": "search-google-drive",
  "name": "My Connector",
  "description": "My Connector to sync data to Elastic index from Google Drive",
  "service_type": "google_drive",
  "language": "english"
}
Response examples (200)
{
  "result": "created",
  "id": "my-connector"
}




Get all connectors Beta; Added in 8.12.0

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

  • query string

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

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • count number Required
    • results array[object] Required
      Hide results attributes Show results attributes object
      • api_key_id string
      • api_key_secret_id string
      • configuration object Required
        Hide configuration attribute Show configuration attribute object
      • custom_scheduling object Required
        Hide custom_scheduling attribute Show custom_scheduling attribute object
        • * object Additional properties
          Hide * attributes Show * attributes object
          • configuration_overrides object Required
            Hide configuration_overrides attributes Show configuration_overrides attributes object
            • max_crawl_depth number
            • sitemap_discovery_disabled boolean
            • domain_allowlist array[string]
            • sitemap_urls array[string]
            • seed_urls array[string]
          • enabled boolean Required
          • interval string Required
          • last_synced string
          • name string Required
      • description string
      • features object
        Hide features attributes Show features attributes object
        • document_level_security object
          Hide document_level_security attribute Show document_level_security attribute object
          • enabled boolean Required
        • incremental_sync object
          Hide incremental_sync attribute Show incremental_sync attribute object
          • enabled boolean Required
        • native_connector_api_keys object
          Hide native_connector_api_keys attribute Show native_connector_api_keys attribute object
          • enabled boolean Required
        • sync_rules object
          Hide sync_rules attributes Show sync_rules attributes object
          • advanced object
            Hide advanced attribute Show advanced attribute object
            • enabled boolean Required
          • basic object
            Hide basic attribute Show basic attribute object
            • enabled boolean Required
      • filtering array[object] Required
        Hide filtering attributes Show filtering attributes object
        • active object Required
          Hide active attributes Show active attributes object
          • advanced_snippet object Required
          • rules array[object] Required
          • validation object Required
        • domain string
        • draft object Required
          Hide draft attributes Show draft attributes object
          • advanced_snippet object Required
          • rules array[object] Required
          • validation object Required
      • id string
      • index_name string | null

      • is_native boolean Required
      • language string
      • last_access_control_sync_error string
      • last_access_control_sync_scheduled_at string | number

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

        One of:
      • last_access_control_sync_status string

        Values are canceling, canceled, completed, error, in_progress, pending, or suspended.

      • last_deleted_document_count number
      • last_incremental_sync_scheduled_at string | number

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

        One of:
      • last_indexed_document_count number
      • last_seen string | number

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

        One of:
      • last_sync_error string
      • last_sync_scheduled_at string | number

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

        One of:
      • last_sync_status string

        Values are canceling, canceled, completed, error, in_progress, pending, or suspended.

      • last_synced string | number

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

        One of:
      • name string
      • pipeline object
        Hide pipeline attributes Show pipeline attributes object
        • extract_binary_content boolean Required
        • name string Required
        • reduce_whitespace boolean Required
        • run_ml_inference boolean Required
      • scheduling object Required
        Hide scheduling attributes Show scheduling attributes object
        • access_control object
          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
          Hide full attributes Show full attributes object
          • enabled boolean Required
          • interval string Required

            The interval is expressed using the crontab syntax

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

            The interval is expressed using the crontab syntax

      • service_type string
      • status string Required

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

      • sync_cursor object
      • sync_now boolean Required
GET _connector
resp = client.connector.list()
const response = await client.connector.list();
response = client.connector.list
$resp = $client->connector()->list();
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector"
client.connector().list(l -> l);




























Get all connector sync jobs Beta; Added in 8.12.0

GET /_connector/_sync_job

Get information about all stored connector sync jobs listed by their creation date in ascending order.

Query parameters

  • from number

    Starting offset (default: 0)

  • size number

    Specifies a max number of results to get

  • status string

    A sync job status to fetch connector sync jobs for

    Values are canceling, canceled, completed, error, in_progress, pending, or suspended.

  • connector_id string

    A connector id to fetch connector sync jobs for

  • job_type string | array[string]

    A comma-separated list of job types to fetch the sync jobs for

    Supported values include: full, incremental, access_control

    Values are full, incremental, or access_control.

Responses

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

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

        One of:
      • canceled_at string | number

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

        One of:
      • completed_at string | number

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

        One of:
      • connector object Required
        Hide connector attributes Show connector attributes object
        • configuration object Required
          Hide configuration attribute Show configuration attribute object
          • * object Additional properties
            Hide * attributes Show * attributes object
            • category string
            • default_value
            • depends_on array[object] Required
            • display string Required

              Values are textbox, textarea, numeric, toggle, or dropdown.

            • label string Required
            • options array[object] Required
            • order number
            • placeholder string
            • required boolean Required
            • sensitive boolean Required
            • tooltip
            • type string

              Values are str, int, list, or bool.

            • ui_restrictions array[string]
            • validations array[object]
            • value object Required
        • filtering object Required
          Hide filtering attributes Show filtering attributes object
          • advanced_snippet object Required
            Hide advanced_snippet attributes Show advanced_snippet attributes object
            • created_at
            • updated_at
            • value object Required
          • rules array[object] Required
          • validation object Required
            Hide validation attributes Show validation attributes object
            • errors array[object] Required
            • state string Required

              Values are edited, invalid, or valid.

        • id string Required
        • index_name string Required
        • language string
        • pipeline object
          Hide pipeline attributes Show pipeline attributes object
          • extract_binary_content boolean Required
          • name string Required
          • reduce_whitespace boolean Required
          • run_ml_inference boolean Required
        • service_type string Required
        • sync_cursor object
      • created_at string | number Required

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

        One of:
      • deleted_document_count number Required
      • error string
      • id string Required
      • indexed_document_count number Required
      • indexed_document_volume number Required
      • job_type string Required

        Values are full, incremental, or access_control.

      • last_seen string | number

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

        One of:
      • metadata object Required
        Hide metadata attribute Show metadata attribute object
        • * object Additional properties
      • started_at string | number

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

        One of:
      • status string Required

        Values are canceling, canceled, completed, error, in_progress, pending, or suspended.

      • total_document_count number Required
      • trigger_method string Required

        Values are on_demand or scheduled.

      • worker_hostname string
GET _connector/_sync_job?connector_id=my-connector-id&size=1
resp = client.connector.sync_job_list(
    connector_id="my-connector-id",
    size="1",
)
const response = await client.connector.syncJobList({
  connector_id: "my-connector-id",
  size: 1,
});
response = client.connector.sync_job_list(
  connector_id: "my-connector-id",
  size: "1"
)
$resp = $client->connector()->syncJobList([
    "connector_id" => "my-connector-id",
    "size" => "1",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/_sync_job?connector_id=my-connector-id&size=1"
client.connector().syncJobList(s -> s
    .connectorId("my-connector-id")
    .size(1)
);
























Update the connector features Technical preview

PUT /_connector/{connector_id}/_features

Update the connector features in the connector document. This API can be used to control the following aspects of a connector:

  • document-level security
  • incremental syncs
  • advanced sync rules
  • basic sync rules

Normally, the running connector service automatically manages these features. However, you can use this API to override the default behavior.

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

Path parameters

  • connector_id string Required

    The unique identifier of the connector to be updated.

application/json

Body Required

  • features object Required
    Hide features attributes Show features attributes object
    • document_level_security object
      Hide document_level_security attribute Show document_level_security attribute object
      • enabled boolean Required
    • incremental_sync object
      Hide incremental_sync attribute Show incremental_sync attribute object
      • enabled boolean Required
    • native_connector_api_keys object
      Hide native_connector_api_keys attribute Show native_connector_api_keys attribute object
      • enabled boolean Required
    • sync_rules object
      Hide sync_rules attributes Show sync_rules attributes object
      • advanced object
        Hide advanced attribute Show advanced attribute object
        • enabled boolean Required
      • basic object
        Hide basic attribute Show basic attribute object
        • enabled boolean 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}/_features
PUT _connector/my-connector/_features
{
  "features": {
    "document_level_security": {
      "enabled": true
    },
    "incremental_sync": {
      "enabled": true
    },
    "sync_rules": {
      "advanced": {
        "enabled": false
      },
      "basic": {
        "enabled": true
      }
    }
  }
}
resp = client.connector.update_features(
    connector_id="my-connector",
    features={
        "document_level_security": {
            "enabled": True
        },
        "incremental_sync": {
            "enabled": True
        },
        "sync_rules": {
            "advanced": {
                "enabled": False
            },
            "basic": {
                "enabled": True
            }
        }
    },
)
const response = await client.connector.updateFeatures({
  connector_id: "my-connector",
  features: {
    document_level_security: {
      enabled: true,
    },
    incremental_sync: {
      enabled: true,
    },
    sync_rules: {
      advanced: {
        enabled: false,
      },
      basic: {
        enabled: true,
      },
    },
  },
});
response = client.connector.update_features(
  connector_id: "my-connector",
  body: {
    "features": {
      "document_level_security": {
        "enabled": true
      },
      "incremental_sync": {
        "enabled": true
      },
      "sync_rules": {
        "advanced": {
          "enabled": false
        },
        "basic": {
          "enabled": true
        }
      }
    }
  }
)
$resp = $client->connector()->updateFeatures([
    "connector_id" => "my-connector",
    "body" => [
        "features" => [
            "document_level_security" => [
                "enabled" => true,
            ],
            "incremental_sync" => [
                "enabled" => true,
            ],
            "sync_rules" => [
                "advanced" => [
                    "enabled" => false,
                ],
                "basic" => [
                    "enabled" => true,
                ],
            ],
        ],
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"features":{"document_level_security":{"enabled":true},"incremental_sync":{"enabled":true},"sync_rules":{"advanced":{"enabled":false},"basic":{"enabled":true}}}}' "$ELASTICSEARCH_URL/_connector/my-connector/_features"
client.connector().updateFeatures(u -> u
    .connectorId("my-connector")
    .features(f -> f
        .documentLevelSecurity(d -> d
            .enabled(true)
        )
        .incrementalSync(i -> i
            .enabled(true)
        )
        .syncRules(s -> s
            .advanced(a -> a
                .enabled(false)
            )
            .basic(b -> b
                .enabled(true)
            )
        )
    )
);
Request examples
{
  "features": {
    "document_level_security": {
      "enabled": true
    },
    "incremental_sync": {
      "enabled": true
    },
    "sync_rules": {
      "advanced": {
        "enabled": false
      },
      "basic": {
        "enabled": true
      }
    }
  }
}
{
  "features": {
    "document_level_security": {
      "enabled": true
    }
  }
}
Response examples (200)
{
  "result": "updated"
}
















Update the connector is_native flag Beta; Added in 8.12.0

PUT /_connector/{connector_id}/_native

Path parameters

  • connector_id string Required

    The unique identifier of the connector to be updated

application/json

Body Required

  • is_native boolean 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 "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"is_native":true}'













































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

POST /_ccr/auto_follow/{name}/pause

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

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

Required authorization

  • Cluster privileges: manage_ccr
External documentation

Path parameters

  • name string Required

    The name of the auto-follow pattern to pause.

Query parameters

  • master_timeout string

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

    Values are -1 or 0.

Responses

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

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

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












Get cross-cluster replication stats Generally available; Added in 6.5.0

GET /_ccr/stats

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

Required authorization

  • Cluster privileges: monitor

Query parameters

  • master_timeout string

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

    Values are -1 or 0.

  • timeout string

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

    Values are -1 or 0.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • auto_follow_stats object Required
      Hide auto_follow_stats attributes Show auto_follow_stats attributes object
      • auto_followed_clusters array[object] Required
        Hide auto_followed_clusters attributes Show auto_followed_clusters attributes object
        • cluster_name string Required
        • last_seen_metadata_version number Required
        • time_since_last_check_millis number

          Time unit for milliseconds

      • number_of_failed_follow_indices number Required

        The number of indices that the auto-follow coordinator failed to automatically follow. The causes of recent failures are captured in the logs of the elected master node and in the auto_follow_stats.recent_auto_follow_errors field.

      • number_of_failed_remote_cluster_state_requests number Required

        The number of times that the auto-follow coordinator failed to retrieve the cluster state from a remote cluster registered in a collection of auto-follow patterns.

      • number_of_successful_follow_indices number Required

        The number of indices that the auto-follow coordinator successfully followed.

      • recent_auto_follow_errors array[object] Required

        An array of objects representing failures by the auto-follow coordinator.

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

        Hide recent_auto_follow_errors attributes Show recent_auto_follow_errors attributes object
        • type string Required

          The type of error

        • reason string | null

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

        • stack_trace string

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

        • caused_by object

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

        • root_cause array[object]

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

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

        • suppressed array[object]

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

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

    • follow_stats object Required
      Hide follow_stats attribute Show follow_stats attribute object
      • indices array[object] Required
        Hide indices attributes Show indices attributes object
        • index string Required
        • shards array[object] Required

          An array of shard-level following task statistics.

          Hide shards attributes Show shards attributes object
          • bytes_read number Required

            The total of transferred bytes read from the leader. This is only an estimate and does not account for compression if enabled.

          • failed_read_requests number Required

            The number of failed reads.

          • failed_write_requests number Required

            The number of failed bulk write requests on the follower.

          • fatal_exception object

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

          • follower_aliases_version number Required
          • follower_global_checkpoint number Required

            The current global checkpoint on the follower. The difference between the leader_global_checkpoint and the follower_global_checkpoint is an indication of how much the follower is lagging the leader.

          • follower_index string Required

            The name of the follower index.

          • follower_mapping_version number Required
          • follower_max_seq_no number Required
          • follower_settings_version number Required
          • last_requested_seq_no number Required
          • leader_global_checkpoint number Required

            The current global checkpoint on the leader known to the follower task.

          • leader_index string Required

            The name of the index in the leader cluster being followed.

          • leader_max_seq_no number Required
          • operations_read number Required

            The total number of operations read from the leader.

          • operations_written number Required

            The number of operations written on the follower.

          • outstanding_read_requests number Required

            The number of active read requests from the follower.

          • outstanding_write_requests number Required

            The number of active bulk write requests on the follower.

          • read_exceptions array[object] Required

            An array of objects representing failed reads.

          • remote_cluster string Required

            The remote cluster containing the leader index.

          • shard_id number Required

            The numerical shard ID, with values from 0 to one less than the number of replicas.

          • successful_read_requests number Required

            The number of successful fetches.

          • successful_write_requests number Required

            The number of bulk write requests run on the follower.

          • time_since_last_read string

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

          • time_since_last_read_millis
          • total_read_remote_exec_time string

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

          • total_read_remote_exec_time_millis
          • total_read_time string

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

          • total_read_time_millis
          • total_write_time string

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

          • total_write_time_millis
          • write_buffer_operation_count number Required

            The number of write operations queued on the follower.

          • write_buffer_size_in_bytes
GET /_ccr/stats
resp = client.ccr.stats()
const response = await client.ccr.stats();
response = client.ccr.stats
$resp = $client->ccr()->stats();
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ccr/stats"
client.ccr().stats(s -> s);
Response examples (200)
A successful response from `GET /_ccr/stats` that returns cross-cluster replication stats.
{
  "auto_follow_stats" : {
    "number_of_failed_follow_indices" : 0,
    "number_of_failed_remote_cluster_state_requests" : 0,
    "number_of_successful_follow_indices" : 1,
    "recent_auto_follow_errors" : [],
    "auto_followed_clusters" : []
  },
  "follow_stats" : {
    "indices" : [
      {
        "index" : "follower_index",
        "total_global_checkpoint_lag" : 256,
        "shards" : [
          {
            "remote_cluster" : "remote_cluster",
            "leader_index" : "leader_index",
            "follower_index" : "follower_index",
            "shard_id" : 0,
            "leader_global_checkpoint" : 1024,
            "leader_max_seq_no" : 1536,
            "follower_global_checkpoint" : 768,
            "follower_max_seq_no" : 896,
            "last_requested_seq_no" : 897,
            "outstanding_read_requests" : 8,
            "outstanding_write_requests" : 2,
            "write_buffer_operation_count" : 64,
            "follower_mapping_version" : 4,
            "follower_settings_version" : 2,
            "follower_aliases_version" : 8,
            "total_read_time_millis" : 32768,
            "total_read_remote_exec_time_millis" : 16384,
            "successful_read_requests" : 32,
            "failed_read_requests" : 0,
            "operations_read" : 896,
            "bytes_read" : 32768,
            "total_write_time_millis" : 16384,
            "write_buffer_size_in_bytes" : 1536,
            "successful_write_requests" : 16,
            "failed_write_requests" : 0,
            "operations_written" : 832,
            "read_exceptions" : [ ],
            "time_since_last_read_millis" : 8
          }
        ]
      }
    ]
  }
}

























Update data stream lifecycles Generally available; Added in 8.11.0

PUT /_data_stream/{name}/_lifecycle

Update the data stream lifecycle of the specified data streams.

External documentation

Path parameters

  • name string | array[string] Required

    Comma-separated list of data streams used to limit the request. Supports wildcards (*). To target all data streams use * or _all.

Query parameters

  • expand_wildcards string | array[string]

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

    Supported values include:

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

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

  • master_timeout string

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

    Values are -1 or 0.

  • timeout string

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

    Values are -1 or 0.

application/json

Body

  • data_retention string

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

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

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

      Hide rounds attributes Show rounds attributes object
      • after string Required

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

      • config object Required
        Hide config attribute Show config attribute object
        • fixed_interval string Required

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

  • enabled boolean

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

    Default value is true.

Responses

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

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

PUT /_data_stream/{name}/_lifecycle
PUT _data_stream/my-data-stream/_lifecycle
{
  "data_retention": "7d"
}
resp = client.indices.put_data_lifecycle(
    name="my-data-stream",
    data_retention="7d",
)
const response = await client.indices.putDataLifecycle({
  name: "my-data-stream",
  data_retention: "7d",
});
response = client.indices.put_data_lifecycle(
  name: "my-data-stream",
  body: {
    "data_retention": "7d"
  }
)
$resp = $client->indices()->putDataLifecycle([
    "name" => "my-data-stream",
    "body" => [
        "data_retention" => "7d",
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"data_retention":"7d"}' "$ELASTICSEARCH_URL/_data_stream/my-data-stream/_lifecycle"
client.indices().putDataLifecycle(p -> p
    .dataRetention(d -> d
        .time("7d")
    )
    .name("my-data-stream")
);
{
  "data_retention": "7d"
}
This example configures two downsampling rounds.
{
    "downsampling": [
      {
        "after": "1d",
        "fixed_interval": "10m"
      },
      {
        "after": "7d",
        "fixed_interval": "1d"
      }
    ]
}
Response examples (200)
A successful response for configuring a data stream lifecycle.
{
  "acknowledged": true
}

























































































Update documents Generally available; Added in 2.4.0

POST /{index}/_update_by_query

Updates documents that match the specified query. If no query is specified, performs an update on every document in the data stream or index without modifying the source, which is useful for picking up mapping changes.

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

  • read
  • index 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 an update by query request, Elasticsearch gets a snapshot of the data stream or index when it begins processing the request and updates matching documents using internal versioning. When the versions match, the document is updated and the version number is incremented. If a document changes between the time that the snapshot is taken and the update operation is processed, it results in a version conflict and the operation fails. 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 update more documents from the source than max_docs until it has successfully updated max_docs documents or it has gone through every document in the source query.

NOTE: Documents with a version equal to 0 cannot be updated using update by query because internal versioning does not support 0 as a valid version number.

While processing an update by query request, Elasticsearch performs multiple search requests sequentially to find all of the matching documents. A bulk update request is performed for each batch of matching documents. Any query or update failures cause the update by query request to fail and the failures are shown in the response. Any update requests that completed successfully still stick, they are not rolled back.

Throttling update requests

To control the rate at which update by query issues batches of update 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 turn off 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

Update by query supports sliced scroll to parallelize the update process. This can improve efficiency and provide a convenient way to break the request down into smaller parts.

Setting slices to auto chooses a reasonable number for most data streams and indices. 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 _update_by_query just automates the manual process of creating 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 point above about distribution being uneven and you should conclude that using max_docs with slices might not result in exactly max_docs documents being updated.
  • 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.
  • Update performance scales linearly across available resources with the number of slices.

Whether query or update performance dominates the runtime depends on the documents being reindexed and cluster resources.

Update the document source

Update by query supports scripts to update the document source. As with the update API, you can set ctx.op to change the operation that is performed.

Set ctx.op = "noop" if your script decides that it doesn't have to make any changes. The update by query operation skips updating the document and increments the noop counter.

Set ctx.op = "delete" if your script decides that the document should be deleted. The update by query operation deletes the document and increments the deleted counter.

Update by query supports only index, noop, and delete. Setting ctx.op to anything else is an error. Setting any other field in ctx is an error. This API enables you to only modify the source of matching documents; you cannot move them.

Required authorization

  • Index privileges: read,write

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

  • allow_no_indices boolean

    If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.

  • analyzer string

    The analyzer to use for the query string. This parameter can be used only when the q query string parameter is specified.

  • analyze_wildcard boolean

    If true, wildcard and prefix queries are analyzed. This parameter can be used only when the q query string parameter is specified.

  • conflicts string

    The preferred behavior when update by query hits version conflicts: abort or proceed.

    Supported values include:

    • abort: Stop reindexing if there are conflicts.
    • proceed: Continue reindexing even if there are conflicts.

    Values are abort or proceed.

  • default_operator string

    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.

    Supported values include:

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

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

  • from number

    Skips the specified number of documents.

  • ignore_unavailable boolean

    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. It defaults to all documents. When set to a value less then or equal to scroll_size then a scroll will not be used to retrieve the results for the operation.

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

  • preference string

    The node or shard the operation should be performed on. It is random by default.

  • q string

    A query in the Lucene query string syntax.

  • refresh boolean

    If true, Elasticsearch refreshes affected shards to make the operation visible to search after the request completes. This is different than the update API's refresh parameter, which causes just the shard that received the request to be refreshed.

  • request_cache boolean

    If true, the request cache is used for this request. It defaults to the index-level setting.

  • requests_per_second number

    The throttle for this request in sub-requests per second.

  • routing string

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

  • scroll string

    The period to retain the search context for scrolling.

    Values are -1 or 0.

  • scroll_size number

    The size of the scroll request that powers the operation.

  • search_timeout string

    An explicit timeout for each search request. By default, there is no timeout.

    Values are -1 or 0.

  • search_type string

    The type of the search operation. Available options include query_then_fetch and dfs_query_then_fetch.

    Supported values include:

    • query_then_fetch: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate.
    • dfs_query_then_fetch: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate.

    Values are query_then_fetch or dfs_query_then_fetch.

  • slices number | string

    The number of slices this task should be divided into.

    Value is auto.

  • sort array[string]

    A comma-separated list of : pairs.

  • stats array[string]

    The specific tag of the request for logging and statistical purposes.

  • terminate_after number

    The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.

    IMPORTANT: Use with caution. Elasticsearch applies this 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 update request waits for the following operations: dynamic mapping updates, waiting for active shards. By default, it is one minute. This guarantees Elasticsearch waits for at least the timeout before failing. The actual wait time could be longer, particularly when multiple waits occur.

    Values are -1 or 0.

  • version boolean

    If true, returns the document version as part of a hit.

  • version_type boolean

    Should the document increment the version number (internal) on hit or not (reindex)

  • 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 parameter controls how long each write request waits for unavailable shards to become available. Both work exactly the way they work in the bulk API.

    Values are all or index-setting.

  • wait_for_completion boolean

    If true, the request blocks until the operation is complete. If false, Elasticsearch performs some preflight checks, launches the request, and returns a task ID that 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}.

application/json

Body

  • max_docs number

    The maximum number of documents to update.

  • query object

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

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

      The script source.

    • id string
    • params object

      Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

      Hide params attribute Show params attribute object
      • * object Additional properties
    • lang string

      Any of:

      Values are painless, expression, mustache, or java.

    • options object
      Hide options attribute Show options attribute object
      • * string Additional properties
  • slice object
    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
  • conflicts string

    Values are abort or proceed.

Responses

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

      The number of scroll responses pulled back by the update by query.

    • failures array[object]

      Array of failures if there were any unrecoverable errors during the process. If this is non-empty then the request ended because of those failures. Update by query is implemented using batches. Any failure causes 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 when version conflicts occur.

      Hide failures attributes Show failures attributes object
      • cause object Required

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

        Hide cause attributes Show cause attributes object
        • type string Required

          The type of error

        • reason string | null

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

        • stack_trace string

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

        • caused_by object

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

        • root_cause array[object]

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

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

        • suppressed array[object]

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

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

      • id string Required
      • index string Required
      • status number Required
    • noops number

      The number of documents that were ignored because the script used for the update by query returned a noop value for ctx.op.

    • deleted number

      The number of documents that were successfully deleted.

    • requests_per_second number

      The number of requests per second effectively run during the update by query.

    • retries object
      Hide retries attributes Show retries attributes object
      • bulk number Required

        The number of bulk actions retried.

    • task string | number

    • timed_out boolean

      If true, some requests timed out during the update by query.

    • took number

      Time unit for milliseconds

    • total number

      The number of documents that were successfully processed.

    • updated number

      The number of documents that were successfully updated.

    • version_conflicts number

      The number of version conflicts that the update by query hit.

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

    • throttled_millis number

      Time unit for milliseconds

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

    • throttled_until_millis number

      Time unit for milliseconds

POST my-index-000001/_update_by_query?conflicts=proceed
{
  "query": { 
    "term": {
      "user.id": "kimchy"
    }
  }
}
resp = client.update_by_query(
    index="my-index-000001",
    conflicts="proceed",
    query={
        "term": {
            "user.id": "kimchy"
        }
    },
)
const response = await client.updateByQuery({
  index: "my-index-000001",
  conflicts: "proceed",
  query: {
    term: {
      "user.id": "kimchy",
    },
  },
});
response = client.update_by_query(
  index: "my-index-000001",
  conflicts: "proceed",
  body: {
    "query": {
      "term": {
        "user.id": "kimchy"
      }
    }
  }
)
$resp = $client->updateByQuery([
    "index" => "my-index-000001",
    "conflicts" => "proceed",
    "body" => [
        "query" => [
            "term" => [
                "user.id" => "kimchy",
            ],
        ],
    ],
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"query":{"term":{"user.id":"kimchy"}}}' "$ELASTICSEARCH_URL/my-index-000001/_update_by_query?conflicts=proceed"
client.updateByQuery(u -> u
    .conflicts(Conflicts.Proceed)
    .index("my-index-000001")
    .query(q -> q
        .term(t -> t
            .field("user.id")
            .value(FieldValue.of("kimchy"))
        )
    )
);
Run `POST my-index-000001/_update_by_query?conflicts=proceed` to update documents that match a query.
{
  "query": { 
    "term": {
      "user.id": "kimchy"
    }
  }
}
Run `POST my-index-000001/_update_by_query` with a script to update the document source. It increments the `count` field for all documents with a `user.id` of `kimchy` in `my-index-000001`.
{
  "script": {
    "source": "ctx._source.count++",
    "lang": "painless"
  },
  "query": {
    "term": {
      "user.id": "kimchy"
    }
  }
}
Run `POST my-index-000001/_update_by_query` to slice an update by query manually. Provide a slice ID and total number of slices to each request.
{
  "slice": {
    "id": 0,
    "max": 2
  },
  "script": {
    "source": "ctx._source['extra'] = 'test'"
  }
}
Run `POST my-index-000001/_update_by_query?refresh&slices=5` to use automatic slicing. It automatically parallelizes using sliced scroll to slice on `_id`.
{
  "script": {
    "source": "ctx._source['extra'] = 'test'"
  }
}

























EQL

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

Learn more about EQL search




Delete an async EQL search Generally available; Added in 7.9.0

DELETE /_eql/search/{id}

Delete an async EQL search or a stored synchronous EQL search. The API also deletes results for the search.

Path parameters

  • id string Required

    Identifier for the search to delete. A search ID is provided in the EQL search API's response for an async search. A search ID is also provided if the request’s keep_on_completion parameter is true.

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 /_eql/search/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=
resp = client.eql.delete(
    id="FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
)
const response = await client.eql.delete({
  id: "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
});
response = client.eql.delete(
  id: "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE="
)
$resp = $client->eql()->delete([
    "id" => "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
]);
curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_eql/search/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE="
client.eql().delete(d -> d
    .id("FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=")
);

















Delete an async ES|QL query Generally available; Added in 8.13.0

DELETE /_query/async/{id}

If the query is still running, it is cancelled. Otherwise, the stored results are deleted.

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

  • The authenticated user that submitted the original query request
  • Users with the cancel_task cluster privilege
External documentation

Path parameters

  • id string Required

    The unique identifier of the query. A query ID is provided in the ES|QL async query API response for a query that does not complete in the designated time. A query ID is also provided when the request was submitted with the keep_on_completion parameter set to true.

Responses

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

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

DELETE /_query/async/FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=
resp = client.esql.async_query_delete(
    id="FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=",
)
const response = await client.esql.asyncQueryDelete({
  id: "FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=",
});
response = client.esql.async_query_delete(
  id: "FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI="
)
$resp = $client->esql()->asyncQueryDelete([
    "id" => "FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=",
]);
curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_query/async/FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI="




Run an ES|QL query Generally available; Added in 8.11.0

POST /_query

Get search results for an ES|QL (Elasticsearch query language) query.

External documentation

Query parameters

  • format string

    A short version of the Accept header, e.g. json, yaml.

    csv, tsv, and txt formats will return results in a tabular format, excluding other metadata fields from the response.

    Values are csv, json, tsv, txt, yaml, cbor, smile, or arrow.

  • delimiter string

    The character to use between values within a CSV row. Only valid for the CSV format.

  • drop_null_columns boolean

    Should columns that are entirely null be removed from the columns and values portion of the results? Defaults to false. If true then the response will include an extra section under the name all_columns which has the name of all columns.

  • allow_partial_results boolean

    If true, partial results will be returned if there are shard failures, but the query can continue to execute on other clusters and shards. If false, the query will fail if there are any failures.

    To override the default behavior, you can set the esql.query.allow_partial_results cluster setting to false.

application/json

Body Required

  • columnar boolean

    By default, ES|QL returns results as rows. For example, FROM returns each individual document as one row. For the JSON, YAML, CBOR and smile formats, ES|QL can return the results in a columnar fashion where one row represents all the values of a certain column in the results.

  • filter object

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

    External documentation
  • locale string
  • params array[number | string | boolean | null | object]

    To avoid any attempts of hacking or code injection, extract the values in a separate list of parameters. Use question mark placeholders (?) in the query string for each of the parameters.

    A field value.

  • profile boolean

    If provided and true the response will include an extra profile object with information on how the query was executed. This information is for human debugging and its format can change at any time but it can give some insight into the performance of each part of the query.

  • query string Required

    The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results.

  • tables object

    Tables to use with the LOOKUP operation. The top level key is the table name and the next level key is the column name.

    Hide tables attribute Show tables attribute object
  • include_ccs_metadata boolean

    When set to true and performing a cross-cluster query, the response will include an extra _clusters object with information about the clusters that participated in the search along with info such as shards count.

    Default value is false.

Responses

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

      Time unit for milliseconds

    • is_partial boolean
    • all_columns array[object]
      Hide all_columns attributes Show all_columns attributes object
      • name string Required
      • type string Required
    • columns array[object] Required
      Hide columns attributes Show columns attributes object
      • name string Required
      • type string Required
    • values array[array] Required
    • _clusters object
      Hide _clusters attributes Show _clusters attributes object
      • total number Required
      • successful number Required
      • running number Required
      • skipped number Required
      • partial number Required
      • failed number Required
      • details object Required
        Hide details attribute Show details attribute object
        • * object Additional properties
          Hide * attributes Show * attributes object
          • status string Required

            Values are running, successful, partial, skipped, or failed.

          • indices string Required
          • took number

            Time unit for milliseconds

          • _shards object
            Hide _shards attributes Show _shards attributes object
            • total number Required
            • successful number
            • skipped number
            • failed number
            • failures array[object]
    • profile object

      Profiling information. Present if profile was true in the request. The contents of this field are currently unstable.

POST /_query
{
  "query": """
    FROM library,remote-*:library
    | EVAL year = DATE_TRUNC(1 YEARS, release_date)
    | STATS MAX(page_count) BY year
    | SORT year
    | LIMIT 5
  """,
  "include_ccs_metadata": true
}
resp = client.esql.query(
    query="\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
    include_ccs_metadata=True,
)
const response = await client.esql.query({
  query:
    "\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
  include_ccs_metadata: true,
});
response = client.esql.query(
  body: {
    "query": "\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
    "include_ccs_metadata": true
  }
)
$resp = $client->esql()->query([
    "body" => [
        "query" => "\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
        "include_ccs_metadata" => true,
    ],
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"query":"\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ","include_ccs_metadata":true}' "$ELASTICSEARCH_URL/_query"
client.esql().query(q -> q
    .includeCcsMetadata(true)
    .query(" FROM library,remote-*:library | EVAL year = DATE_TRUNC(1 YEARS, release_date) | STATS MAX(page_count) BY year | SORT year | LIMIT 5 ")
);
Request example
Run `POST /_query` to get results for an ES|QL query.
{
  "query": """
    FROM library,remote-*:library
    | EVAL year = DATE_TRUNC(1 YEARS, release_date)
    | STATS MAX(page_count) BY year
    | SORT year
    | LIMIT 5
  """,
  "include_ccs_metadata": true
}









Fleet



















Get component templates Generally available; Added in 7.8.0

GET /_component_template/{name}

All methods and paths for this operation:

GET /_component_template

GET /_component_template/{name}

Get information about component templates.

Required authorization

  • Cluster privileges: manage_index_templates

Path parameters

  • name string Required

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

Query parameters

  • flat_settings boolean

    If true, returns settings in flat format.

  • settings_filter string | array[string]

    Filter out results, for example to filter out sensitive information. Supports wildcards or full settings keys

  • include_defaults boolean Generally available; Added in 8.11.0

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

  • local boolean

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

  • master_timeout string

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

    Values are -1 or 0.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • component_templates array[object] Required
      Hide component_templates attributes Show component_templates attributes object
      • name string Required
      • component_template object Required
        Hide component_template attributes Show component_template attributes object
        • template object Required
          Hide template attributes Show template attributes object
          • _meta object
            Hide _meta attribute Show _meta attribute object
            • * object Additional properties
          • version number
          • settings object
            Hide settings attribute Show settings attribute object
            • * object
          • mappings object
            Hide mappings attributes Show mappings attributes object
            • all_field object
            • date_detection boolean
            • dynamic string

              Values are strict, runtime, true, or false.

            • dynamic_date_formats array[string]
            • dynamic_templates array[object]
            • _field_names object
            • index_field object
            • _meta object
            • numeric_detection boolean
            • properties object
            • _routing object
            • _size object
            • _source object
            • runtime object
            • enabled boolean
            • subobjects string

              Values are true or false.

            • _data_stream_timestamp object
          • aliases object
            Hide aliases attribute Show aliases attribute object
            • * object Additional properties
          • lifecycle object
        • version number
        • _meta object
          Hide _meta attribute Show _meta attribute object
          • * object Additional properties
        • deprecated boolean
GET /_component_template/template_1
resp = client.cluster.get_component_template(
    name="template_1",
)
const response = await client.cluster.getComponentTemplate({
  name: "template_1",
});
response = client.cluster.get_component_template(
  name: "template_1"
)
$resp = $client->cluster()->getComponentTemplate([
    "name" => "template_1",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_component_template/template_1"
client.cluster().getComponentTemplate(g -> g
    .name("template_1")
);
















Delete a dangling index Generally available; Added in 7.9.0

DELETE /_dangling/{index_uuid}

If Elasticsearch encounters index data that is absent from the current cluster state, those indices are considered to be dangling. For example, this can happen if you delete more than cluster.indices.tombstones.size indices while an Elasticsearch node is offline.

Required authorization

  • Cluster privileges: manage

Path parameters

  • index_uuid string Required

    The UUID of the index to delete. Use the get dangling indices API to find the UUID.

Query parameters

  • accept_data_loss boolean Required

    This parameter must be set to true to acknowledge that it will no longer be possible to recove data from the dangling index.

  • master_timeout string

    Specify timeout for connection to master

    Values are -1 or 0.

  • timeout string

    Explicit operation timeout

    Values are -1 or 0.

Responses

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

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

DELETE /_dangling/<index-uuid>?accept_data_loss=true
resp = client.dangling_indices.delete_dangling_index(
    index_uuid="<index-uuid>",
    accept_data_loss=True,
)
const response = await client.danglingIndices.deleteDanglingIndex({
  index_uuid: "<index-uuid>",
  accept_data_loss: "true",
});
response = client.dangling_indices.delete_dangling_index(
  index_uuid: "<index-uuid>",
  accept_data_loss: "true"
)
$resp = $client->danglingIndices()->deleteDanglingIndex([
    "index_uuid" => "<index-uuid>",
    "accept_data_loss" => "true",
]);
curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_dangling/<index-uuid>?accept_data_loss=true"
client.danglingIndices().deleteDanglingIndex(d -> d
    .acceptDataLoss(true)
    .indexUuid("<index-uuid>")
);

Get the dangling indices Generally available; Added in 7.9.0

GET /_dangling

If Elasticsearch encounters index data that is absent from the current cluster state, those indices are considered to be dangling. For example, this can happen if you delete more than cluster.indices.tombstones.size indices while an Elasticsearch node is offline.

Use this API to list dangling indices, which you can then import or delete.

Required authorization

  • Cluster privileges: manage

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • dangling_indices array[object] Required
      Hide dangling_indices attributes Show dangling_indices attributes object
GET /_dangling
resp = client.dangling_indices.list_dangling_indices()
const response = await client.danglingIndices.listDanglingIndices();
response = client.dangling_indices.list_dangling_indices
$resp = $client->danglingIndices()->listDanglingIndices();
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_dangling"
client.danglingIndices().listDanglingIndices();
Response examples (200)
{
  "dangling_indices": [
   {
    "index_name": "my-index-000001",
    "index_uuid": "zmM4e0JtBkeUjiHD-MihPQ",
    "creation_date_millis": 1589414451372,
    "node_ids": [
      "pL47UN3dAb2d5RCWP6lQ3e"
    ]
   }
  ]
}

Add an index block Generally available; Added in 7.9.0

PUT /{index}/_block/{block}

Add an index block to an index. Index blocks limit the operations allowed on an index by blocking specific operation types.

Path parameters

  • index string Required

    A comma-separated list or wildcard expression of index names used to limit the request. By default, you must explicitly name the indices you are adding blocks to. To allow the adding of blocks to indices with _all, *, or other wildcard expressions, change the action.destructive_requires_name setting to false. You can update this setting in the elasticsearch.yml file or by using the cluster update settings API.

  • block string

    The block type to add to the index.

    Supported values include:

    • metadata: Disable metadata changes, such as closing the index.
    • read: Disable read operations.
    • read_only: Disable write operations and metadata changes.
    • write: Disable write operations. However, metadata changes are still allowed.

    Values are metadata, read, read_only, or write.

Query parameters

  • allow_no_indices boolean

    If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.

  • expand_wildcards string | array[string]

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

    Supported values include:

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

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

  • ignore_unavailable boolean

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

  • master_timeout string

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

    Values are -1 or 0.

  • timeout string

    The period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata. If no response is received before the timeout expires, the cluster metadata update still applies but the response will indicate that it was not completely acknowledged. It can also be set to -1 to indicate that the request should never timeout.

    Values are -1 or 0.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • acknowledged boolean Required
    • shards_acknowledged boolean Required
    • indices array[object] Required
      Hide indices attributes Show indices attributes object
      • name string Required
      • blocked boolean Required
PUT /my-index-000001/_block/write
resp = client.indices.add_block(
    index="my-index-000001",
    block="write",
)
const response = await client.indices.addBlock({
  index: "my-index-000001",
  block: "write",
});
response = client.indices.add_block(
  index: "my-index-000001",
  block: "write"
)
$resp = $client->indices()->addBlock([
    "index" => "my-index-000001",
    "block" => "write",
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/my-index-000001/_block/write"
client.indices().addBlock(a -> a
    .block(IndicesBlockOptions.Write)
    .index("my-index-000001")
);
Response examples (200)
A successful response from `PUT /my-index-000001/_block/write`, which adds an index block to an index.'
{
  "acknowledged" : true,
  "shards_acknowledged" : true,
  "indices" : [ {
    "name" : "my-index-000001",
    "blocked" : true
  } ]
}








Clone an index Generally available; Added in 7.4.0

POST /{index}/_clone/{target}

All methods and paths for this operation:

PUT /{index}/_clone/{target}

POST /{index}/_clone/{target}

Clone an existing index into a new index. Each original primary shard is cloned into a new primary shard in the new index.

IMPORTANT: Elasticsearch does not apply index templates to the resulting index. The API also does not copy index metadata from the original index. Index metadata includes aliases, index lifecycle management phase definitions, and cross-cluster replication (CCR) follower information. For example, if you clone a CCR follower index, the resulting clone will not be a follower index.

The clone API copies most index settings from the source index to the resulting index, with the exception of index.number_of_replicas and index.auto_expand_replicas. To set the number of replicas in the resulting index, configure these settings in the clone request.

Cloning works as follows:

  • First, it creates a new target index with the same definition as the source index.
  • Then it hard-links segments from the source index into the target index. If the file system does not support hard-linking, all segments are copied into the new index, which is a much more time consuming process.
  • Finally, it recovers the target index as though it were a closed index which had just been re-opened.

IMPORTANT: Indices can only be cloned if they meet the following requirements:

  • The index must be marked as read-only and have a cluster health status of green.
  • The target index must not exist.
  • The source index must have the same number of primary shards as the target index.
  • The node handling the clone process must have sufficient free disk space to accommodate a second copy of the existing index.

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

NOTE: Mappings cannot be specified in the _clone request. The mappings of the source index will be used for the target index.

Monitor the cloning process

The cloning process can be monitored with the cat recovery API or the cluster health API can be used to wait until all primary shards have been allocated by setting the wait_for_status parameter to yellow.

The _clone API returns as soon as the target index has been added to the cluster state, before any shards have been allocated. At this point, all shards are in the state unassigned. If, for any reason, the target index can't be allocated, its primary shard will remain unassigned until it can be allocated on that node.

Once the primary shard is allocated, it moves to state initializing, and the clone process begins. When the clone operation completes, the shard will become active. At that point, Elasticsearch will try to allocate any replicas and may decide to relocate the primary shard to another node.

Wait for active shards

Because the clone operation creates a new index to clone the shards to, the wait for active shards setting on index creation applies to the clone index action as well.

Required authorization

  • Index privileges: manage

Path parameters

  • index string Required

    Name of the source index to clone.

  • target string Required

    Name of the target index to create.

Query parameters

  • master_timeout string

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

    Values are -1 or 0.

  • timeout string

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

    Values are -1 or 0.

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

    Values are all or index-setting.

application/json

Body

  • aliases object

    Aliases for the resulting index.

    Hide aliases attribute Show aliases attribute object
    • * object Additional properties
      Hide * attributes Show * attributes object
      • filter object

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

        External documentation
      • index_routing string
      • is_hidden boolean

        If true, the alias is hidden. All indices for the alias must have the same is_hidden value.

        Default value is false.

      • is_write_index boolean

        If true, the index is the write index for the alias.

        Default value is false.

      • routing string
      • search_routing string
  • settings object

    Configuration options for the target index.

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

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • acknowledged boolean Required
    • index string Required
    • shards_acknowledged boolean Required
POST /my_source_index/_clone/my_target_index
{
  "settings": {
    "index.number_of_shards": 5
  },
  "aliases": {
    "my_search_indices": {}
  }
}
resp = client.indices.clone(
    index="my_source_index",
    target="my_target_index",
    settings={
        "index.number_of_shards": 5
    },
    aliases={
        "my_search_indices": {}
    },
)
const response = await client.indices.clone({
  index: "my_source_index",
  target: "my_target_index",
  settings: {
    "index.number_of_shards": 5,
  },
  aliases: {
    my_search_indices: {},
  },
});
response = client.indices.clone(
  index: "my_source_index",
  target: "my_target_index",
  body: {
    "settings": {
      "index.number_of_shards": 5
    },
    "aliases": {
      "my_search_indices": {}
    }
  }
)
$resp = $client->indices()->clone([
    "index" => "my_source_index",
    "target" => "my_target_index",
    "body" => [
        "settings" => [
            "index.number_of_shards" => 5,
        ],
        "aliases" => [
            "my_search_indices" => new ArrayObject([]),
        ],
    ],
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"settings":{"index.number_of_shards":5},"aliases":{"my_search_indices":{}}}' "$ELASTICSEARCH_URL/my_source_index/_clone/my_target_index"
client.indices().clone(c -> c
    .aliases("my_search_indices", a -> a)
    .index("my_source_index")
    .settings("index.number_of_shards", JsonData.fromJson("5"))
    .target("my_target_index")
);
Request example
Clone `my_source_index` into a new index called `my_target_index` with `POST /my_source_index/_clone/my_target_index`. The API accepts `settings` and `aliases` parameters for the target index.
{
  "settings": {
    "index.number_of_shards": 5
  },
  "aliases": {
    "my_search_indices": {}
  }
}








Create an index Generally available

PUT /{index}

You can use the create index API to add a new index to an Elasticsearch cluster. When creating an index, you can specify the following:

  • Settings for the index.
  • Mappings for fields in the index.
  • Index aliases

Wait for active shards

By default, index creation will only return a response to the client when the primary copies of each shard have been started, or the request times out. The index creation response will indicate what happened. For example, acknowledged indicates whether the index was successfully created in the cluster, while shards_acknowledged indicates whether the requisite number of shard copies were started for each shard in the index before timing out. Note that it is still possible for either acknowledged or shards_acknowledged to be false, but for the index creation to be successful. These values simply indicate whether the operation completed before the timeout. If acknowledged is false, the request timed out before the cluster state was updated with the newly created index, but it probably will be created sometime soon. If shards_acknowledged is false, then the request timed out before the requisite number of shards were started (by default just the primaries), even if the cluster state was successfully updated to reflect the newly created index (that is to say, acknowledged is true).

You can change the default of only waiting for the primary shards to start through the index setting index.write.wait_for_active_shards. Note that changing this setting will also affect the wait_for_active_shards value on all subsequent write operations.

Required authorization

  • Index privileges: create_index,manage

Path parameters

  • index string Required

    Name of the index you wish to create.

Query parameters

  • master_timeout string

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

    Values are -1 or 0.

  • timeout string

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

    Values are -1 or 0.

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

    Values are all or index-setting.

application/json

Body

  • aliases object

    Aliases for the index.

    Hide aliases attribute Show aliases attribute object
    • * object Additional properties
      Hide * attributes Show * attributes object
      • filter object

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

        External documentation
      • index_routing string
      • is_hidden boolean

        If true, the alias is hidden. All indices for the alias must have the same is_hidden value.

        Default value is false.

      • is_write_index boolean

        If true, the index is the write index for the alias.

        Default value is false.

      • routing string
      • search_routing string
  • mappings object
    Hide mappings attributes Show mappings attributes object
    • all_field object
      Hide all_field attributes Show all_field attributes object
      • analyzer string Required
      • enabled boolean Required
      • omit_norms boolean Required
      • search_analyzer string Required
      • similarity string Required
      • store boolean Required
      • store_term_vector_offsets boolean Required
      • store_term_vector_payloads boolean Required
      • store_term_vector_positions boolean Required
      • store_term_vectors boolean Required
    • date_detection boolean
    • dynamic string

      Values are strict, runtime, true, or false.

    • dynamic_date_formats array[string]
    • dynamic_templates array[object]
    • _field_names object
      Hide _field_names attribute Show _field_names attribute object
      • enabled boolean Required
    • index_field object
      Hide index_field attribute Show index_field attribute object
      • enabled boolean Required
    • _meta object
      Hide _meta attribute Show _meta attribute object
      • * object Additional properties
    • numeric_detection boolean
    • properties object
    • _routing object
      Hide _routing attribute Show _routing attribute object
      • required boolean Required
    • _size object
      Hide _size attribute Show _size attribute object
      • enabled boolean Required
    • _source object
      Hide _source attributes Show _source attributes object
      • compress boolean
      • compress_threshold string
      • enabled boolean
      • excludes array[string]
      • includes array[string]
      • mode string

        Values are disabled, stored, or synthetic.

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

          For type composite

          Hide fields attribute Show fields attribute object
          • * object Additional properties
            Hide * attribute Show * attribute object
            • type string Required

              Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.

        • fetch_fields array[object]

          For type lookup

          Hide fetch_fields attributes Show fetch_fields attributes object
          • field string Required

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

          • format string
        • format string

          A custom format for date type runtime fields.

        • input_field string

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

        • target_field string

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

        • target_index string
        • script object
          Hide script attributes Show script attributes object
          • source string

            The script source.

          • id string
          • params object

            Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

            Hide params attribute Show params attribute object
            • * object Additional properties
          • lang string

            Any of:

            Values are painless, expression, mustache, or java.

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

          Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.

    • enabled boolean
    • subobjects string

      Values are true or false.

    • _data_stream_timestamp object
      Hide _data_stream_timestamp attribute Show _data_stream_timestamp attribute object
      • enabled boolean Required
  • settings object
    Index settings

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • index string Required
    • shards_acknowledged boolean Required
    • acknowledged boolean Required
PUT /my-index-000001
{
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 2
  }
}
resp = client.indices.create(
    index="my-index-000001",
    settings={
        "number_of_shards": 3,
        "number_of_replicas": 2
    },
)
const response = await client.indices.create({
  index: "my-index-000001",
  settings: {
    number_of_shards: 3,
    number_of_replicas: 2,
  },
});
response = client.indices.create(
  index: "my-index-000001",
  body: {
    "settings": {
      "number_of_shards": 3,
      "number_of_replicas": 2
    }
  }
)
$resp = $client->indices()->create([
    "index" => "my-index-000001",
    "body" => [
        "settings" => [
            "number_of_shards" => 3,
            "number_of_replicas" => 2,
        ],
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"settings":{"number_of_shards":3,"number_of_replicas":2}}' "$ELASTICSEARCH_URL/my-index-000001"
client.indices().create(c -> c
    .index("my-index-000001")
    .settings(s -> s
        .numberOfShards("3")
        .numberOfReplicas("2")
    )
);
This request specifies the `number_of_shards` and `number_of_replicas`.
{
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 2
  }
}
You can provide mapping definitions in the create index API requests.
{
  "settings": {
    "number_of_shards": 1
  },
  "mappings": {
    "properties": {
      "field1": { "type": "text" }
    }
  }
}
You can provide mapping definitions in the create index API requests. Index alias names also support date math.
{
  "aliases": {
    "alias_1": {},
    "alias_2": {
      "filter": {
        "term": {
          "user.id": "kimchy"
        }
      },
      "routing": "shard-1"
    }
  }
}

Delete indices Generally available

DELETE /{index}

Deleting an index deletes its documents, shards, and metadata. It does not delete related Kibana components, such as data views, visualizations, or dashboards.

You cannot delete the current write index of a data stream. To delete the index, you must roll over the data stream so a new write index is created. You can then use the delete index API to delete the previous write index.

Required authorization

  • Index privileges: delete_index

Path parameters

  • index string | array[string] Required

    Comma-separated list of indices to delete. You cannot specify index aliases. By default, this parameter does not support wildcards (*) or _all. To use wildcards or _all, set the action.destructive_requires_name cluster setting to false.

Query parameters

  • allow_no_indices boolean

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

  • expand_wildcards string | array[string]

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

    Supported values include:

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

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

  • ignore_unavailable boolean

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

  • master_timeout string

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

    Values are -1 or 0.

  • timeout string

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

    Values are -1 or 0.

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.

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

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

          Hide reason attributes Show reason attributes object
          • type string Required

            The type of error

          • reason
          • stack_trace string

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

          • caused_by object

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

          • root_cause array[object]
          • suppressed array[object]
        • shard number Required
        • status string
      • skipped number
DELETE /books
resp = client.indices.delete(
    index="books",
)
const response = await client.indices.delete({
  index: "books",
});
response = client.indices.delete(
  index: "books"
)
$resp = $client->indices()->delete([
    "index" => "books",
]);
curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/books"
client.indices().delete(d -> d
    .index("books")
);




























Check index templates Generally available

HEAD /_index_template/{name}

Check whether index templates exist.

Required authorization

  • Cluster privileges: manage_index_templates

Path parameters

  • name string Required

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

Query parameters

  • local boolean

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

  • flat_settings boolean

    If true, returns settings in flat format.

  • master_timeout string

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

    Values are -1 or 0.

Responses

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




























































Update index settings Generally available

PUT /{index}/_settings

All methods and paths for this operation:

PUT /_settings

PUT /{index}/_settings

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

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

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

{
  "number_of_replicas": 1
}

Or you can use an index setting object:

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

Or you can use dot annotation:

{
  "index.number_of_replicas": 1
}

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

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

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

Required authorization

  • Index privileges: manage
External documentation

Path parameters

  • index string | array[string] Required

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

Query parameters

  • allow_no_indices boolean

    If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.

  • expand_wildcards string | array[string]

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

    Supported values include:

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

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

  • flat_settings boolean

    If true, returns settings in flat format.

  • ignore_unavailable boolean

    If true, returns settings in flat format.

  • master_timeout string

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

    Values are -1 or 0.

  • preserve_existing boolean

    If true, existing index settings remain unchanged.

  • reopen boolean

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

  • timeout string

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

    Values are -1 or 0.

application/json

Body Required

object object
Index settings

Responses

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

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

PUT /my-index-000001/_settings
{
  "index" : {
    "number_of_replicas" : 2
  }
}
resp = client.indices.put_settings(
    index="my-index-000001",
    settings={
        "index": {
            "number_of_replicas": 2
        }
    },
)
const response = await client.indices.putSettings({
  index: "my-index-000001",
  settings: {
    index: {
      number_of_replicas: 2,
    },
  },
});
response = client.indices.put_settings(
  index: "my-index-000001",
  body: {
    "index": {
      "number_of_replicas": 2
    }
  }
)
$resp = $client->indices()->putSettings([
    "index" => "my-index-000001",
    "body" => [
        "index" => [
            "number_of_replicas" => 2,
        ],
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"index":{"number_of_replicas":2}}' "$ELASTICSEARCH_URL/my-index-000001/_settings"
client.indices().putSettings(p -> p
    .index("my-index-000001")
    .settings(s -> s
        .index(i -> i
            .numberOfReplicas("2")
        )
    )
);
{
  "index" : {
    "number_of_replicas" : 2
  }
}
To revert a setting to the default value, use `null`.
{
  "index" : {
    "refresh_interval" : null
  }
}
To add an analyzer, you must close the index (`POST /my-index-000001/_close`), define the analyzer, then reopen the index (`POST /my-index-000001/_open`).
{
  "analysis": {
    "analyzer": {
      "content": {
        "type": "custom",
        "tokenizer": "whitespace"
      }
    }
  }
}





































































Create or update a lifecycle policy Generally available; Added in 6.6.0

PUT /_ilm/policy/{policy}

If the specified policy exists, it is replaced and the policy version is incremented.

NOTE: Only the latest version of the policy is stored, you cannot revert to previous versions.

Required authorization

  • Index privileges: manage
  • Cluster privileges: manage_ilm
External documentation

Path parameters

  • policy string Required

    Identifier for the policy.

Query parameters

  • master_timeout string

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

    Values are -1 or 0.

  • timeout string

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

    Values are -1 or 0.

application/json

Body

  • policy object
    Hide policy attributes Show policy attributes object
    • phases object Required
      Hide phases attributes Show phases attributes object
      • cold object
        Hide cold attributes Show cold attributes object
        • actions object
          Hide actions attributes Show actions attributes object
          • allocate object
            Hide allocate attributes Show allocate attributes object
            • number_of_replicas number
            • total_shards_per_node number
            • include object
              Hide include attribute Show include attribute object
              • * string Additional properties
            • exclude object
              Hide exclude attribute Show exclude attribute object
              • * string Additional properties
            • require object
              Hide require attribute Show require attribute object
              • * string Additional properties
          • delete object
            Hide delete attribute Show delete attribute object
            • delete_searchable_snapshot boolean
          • downsample object
            Hide downsample attributes Show downsample attributes object
            • fixed_interval string Required

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

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

          • freeze object

            For empty Class assignments

          • forcemerge object
            Hide forcemerge attributes Show forcemerge attributes object
            • max_num_segments number Required
            • index_codec string
          • migrate object
            Hide migrate attribute Show migrate attribute object
            • enabled boolean
          • readonly object

            For empty Class assignments

          • rollover object
            Hide rollover attributes Show rollover attributes object
            • max_size number | string

            • max_primary_shard_size number | string

            • max_age string

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

            • max_docs number
            • max_primary_shard_docs number
            • min_size number | string

            • min_primary_shard_size number | string

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

            • min_docs number
            • min_primary_shard_docs number
          • set_priority object
            Hide set_priority attribute Show set_priority attribute object
            • priority number
          • searchable_snapshot object
            Hide searchable_snapshot attributes Show searchable_snapshot attributes object
            • snapshot_repository string Required
            • force_merge_index boolean
          • shrink object
            Hide shrink attributes Show shrink attributes object
          • unfollow object

            For empty Class assignments

          • wait_for_snapshot object
            Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
            • policy string Required
        • min_age 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.

      • delete object
        Hide delete attributes Show delete attributes object
        • actions object
          Hide actions attributes Show actions attributes object
          • allocate object
            Hide allocate attributes Show allocate attributes object
            • number_of_replicas number
            • total_shards_per_node number
            • include object
              Hide include attribute Show include attribute object
              • * string Additional properties
            • exclude object
              Hide exclude attribute Show exclude attribute object
              • * string Additional properties
            • require object
              Hide require attribute Show require attribute object
              • * string Additional properties
          • delete object
            Hide delete attribute Show delete attribute object
            • delete_searchable_snapshot boolean
          • downsample object
            Hide downsample attributes Show downsample attributes object
            • fixed_interval string Required

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

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

          • freeze object

            For empty Class assignments

          • forcemerge object
            Hide forcemerge attributes Show forcemerge attributes object
            • max_num_segments number Required
            • index_codec string
          • migrate object
            Hide migrate attribute Show migrate attribute object
            • enabled boolean
          • readonly object

            For empty Class assignments

          • rollover object
            Hide rollover attributes Show rollover attributes object
            • max_size number | string

            • max_primary_shard_size number | string

            • max_age string

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

            • max_docs number
            • max_primary_shard_docs number
            • min_size number | string

            • min_primary_shard_size number | string

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

            • min_docs number
            • min_primary_shard_docs number
          • set_priority object
            Hide set_priority attribute Show set_priority attribute object
            • priority number
          • searchable_snapshot object
            Hide searchable_snapshot attributes Show searchable_snapshot attributes object
            • snapshot_repository string Required
            • force_merge_index boolean
          • shrink object
            Hide shrink attributes Show shrink attributes object
          • unfollow object

            For empty Class assignments

          • wait_for_snapshot object
            Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
            • policy string Required
        • min_age 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.

      • frozen object
        Hide frozen attributes Show frozen attributes object
        • actions object
          Hide actions attributes Show actions attributes object
          • allocate object
            Hide allocate attributes Show allocate attributes object
            • number_of_replicas number
            • total_shards_per_node number
            • include object
              Hide include attribute Show include attribute object
              • * string Additional properties
            • exclude object
              Hide exclude attribute Show exclude attribute object
              • * string Additional properties
            • require object
              Hide require attribute Show require attribute object
              • * string Additional properties
          • delete object
            Hide delete attribute Show delete attribute object
            • delete_searchable_snapshot boolean
          • downsample object
            Hide downsample attributes Show downsample attributes object
            • fixed_interval string Required

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

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

          • freeze object

            For empty Class assignments

          • forcemerge object
            Hide forcemerge attributes Show forcemerge attributes object
            • max_num_segments number Required
            • index_codec string
          • migrate object
            Hide migrate attribute Show migrate attribute object
            • enabled boolean
          • readonly object

            For empty Class assignments

          • rollover object
            Hide rollover attributes Show rollover attributes object
            • max_size number | string

            • max_primary_shard_size number | string

            • max_age string

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

            • max_docs number
            • max_primary_shard_docs number
            • min_size number | string

            • min_primary_shard_size number | string

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

            • min_docs number
            • min_primary_shard_docs number
          • set_priority object
            Hide set_priority attribute Show set_priority attribute object
            • priority number
          • searchable_snapshot object
            Hide searchable_snapshot attributes Show searchable_snapshot attributes object
            • snapshot_repository string Required
            • force_merge_index boolean
          • shrink object
            Hide shrink attributes Show shrink attributes object
          • unfollow object

            For empty Class assignments

          • wait_for_snapshot object
            Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
            • policy string Required
        • min_age 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.

      • hot object
        Hide hot attributes Show hot attributes object
        • actions object
          Hide actions attributes Show actions attributes object
          • allocate object
            Hide allocate attributes Show allocate attributes object
            • number_of_replicas number
            • total_shards_per_node number
            • include object
              Hide include attribute Show include attribute object
              • * string Additional properties
            • exclude object
              Hide exclude attribute Show exclude attribute object
              • * string Additional properties
            • require object
              Hide require attribute Show require attribute object
              • * string Additional properties
          • delete object
            Hide delete attribute Show delete attribute object
            • delete_searchable_snapshot boolean
          • downsample object
            Hide downsample attributes Show downsample attributes object
            • fixed_interval string Required

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

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

          • freeze object

            For empty Class assignments

          • forcemerge object
            Hide forcemerge attributes Show forcemerge attributes object
            • max_num_segments number Required
            • index_codec string
          • migrate object
            Hide migrate attribute Show migrate attribute object
            • enabled boolean
          • readonly object

            For empty Class assignments

          • rollover object
            Hide rollover attributes Show rollover attributes object
            • max_size number | string

            • max_primary_shard_size number | string

            • max_age string

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

            • max_docs number
            • max_primary_shard_docs number
            • min_size number | string

            • min_primary_shard_size number | string

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

            • min_docs number
            • min_primary_shard_docs number
          • set_priority object
            Hide set_priority attribute Show set_priority attribute object
            • priority number
          • searchable_snapshot object
            Hide searchable_snapshot attributes Show searchable_snapshot attributes object
            • snapshot_repository string Required
            • force_merge_index boolean
          • shrink object
            Hide shrink attributes Show shrink attributes object
          • unfollow object

            For empty Class assignments

          • wait_for_snapshot object
            Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
            • policy string Required
        • min_age 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.

      • warm object
        Hide warm attributes Show warm attributes object
        • actions object
          Hide actions attributes Show actions attributes object
          • allocate object
            Hide allocate attributes Show allocate attributes object
            • number_of_replicas number
            • total_shards_per_node number
            • include object
              Hide include attribute Show include attribute object
              • * string Additional properties
            • exclude object
              Hide exclude attribute Show exclude attribute object
              • * string Additional properties
            • require object
              Hide require attribute Show require attribute object
              • * string Additional properties
          • delete object
            Hide delete attribute Show delete attribute object
            • delete_searchable_snapshot boolean
          • downsample object
            Hide downsample attributes Show downsample attributes object
            • fixed_interval string Required

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

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

          • freeze object

            For empty Class assignments

          • forcemerge object
            Hide forcemerge attributes Show forcemerge attributes object
            • max_num_segments number Required
            • index_codec string
          • migrate object
            Hide migrate attribute Show migrate attribute object
            • enabled boolean
          • readonly object

            For empty Class assignments

          • rollover object
            Hide rollover attributes Show rollover attributes object
            • max_size number | string

            • max_primary_shard_size number | string

            • max_age string

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

            • max_docs number
            • max_primary_shard_docs number
            • min_size number | string

            • min_primary_shard_size number | string

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

            • min_docs number
            • min_primary_shard_docs number
          • set_priority object
            Hide set_priority attribute Show set_priority attribute object
            • priority number
          • searchable_snapshot object
            Hide searchable_snapshot attributes Show searchable_snapshot attributes object
            • snapshot_repository string Required
            • force_merge_index boolean
          • shrink object
            Hide shrink attributes Show shrink attributes object
          • unfollow object

            For empty Class assignments

          • wait_for_snapshot object
            Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
            • policy string Required
        • min_age 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.

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

Responses

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

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

PUT _ilm/policy/my_policy
{
  "policy": {
    "_meta": {
      "description": "used for nginx log",
      "project": {
        "name": "myProject",
        "department": "myDepartment"
      }
    },
    "phases": {
      "warm": {
        "min_age": "10d",
        "actions": {
          "forcemerge": {
            "max_num_segments": 1
          }
        }
      },
      "delete": {
        "min_age": "30d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}
resp = client.ilm.put_lifecycle(
    name="my_policy",
    policy={
        "_meta": {
            "description": "used for nginx log",
            "project": {
                "name": "myProject",
                "department": "myDepartment"
            }
        },
        "phases": {
            "warm": {
                "min_age": "10d",
                "actions": {
                    "forcemerge": {
                        "max_num_segments": 1
                    }
                }
            },
            "delete": {
                "min_age": "30d",
                "actions": {
                    "delete": {}
                }
            }
        }
    },
)
const response = await client.ilm.putLifecycle({
  name: "my_policy",
  policy: {
    _meta: {
      description: "used for nginx log",
      project: {
        name: "myProject",
        department: "myDepartment",
      },
    },
    phases: {
      warm: {
        min_age: "10d",
        actions: {
          forcemerge: {
            max_num_segments: 1,
          },
        },
      },
      delete: {
        min_age: "30d",
        actions: {
          delete: {},
        },
      },
    },
  },
});
response = client.ilm.put_lifecycle(
  policy: "my_policy",
  body: {
    "policy": {
      "_meta": {
        "description": "used for nginx log",
        "project": {
          "name": "myProject",
          "department": "myDepartment"
        }
      },
      "phases": {
        "warm": {
          "min_age": "10d",
          "actions": {
            "forcemerge": {
              "max_num_segments": 1
            }
          }
        },
        "delete": {
          "min_age": "30d",
          "actions": {
            "delete": {}
          }
        }
      }
    }
  }
)
$resp = $client->ilm()->putLifecycle([
    "policy" => "my_policy",
    "body" => [
        "policy" => [
            "_meta" => [
                "description" => "used for nginx log",
                "project" => [
                    "name" => "myProject",
                    "department" => "myDepartment",
                ],
            ],
            "phases" => [
                "warm" => [
                    "min_age" => "10d",
                    "actions" => [
                        "forcemerge" => [
                            "max_num_segments" => 1,
                        ],
                    ],
                ],
                "delete" => [
                    "min_age" => "30d",
                    "actions" => [
                        "delete" => new ArrayObject([]),
                    ],
                ],
            ],
        ],
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"policy":{"_meta":{"description":"used for nginx log","project":{"name":"myProject","department":"myDepartment"}},"phases":{"warm":{"min_age":"10d","actions":{"forcemerge":{"max_num_segments":1}}},"delete":{"min_age":"30d","actions":{"delete":{}}}}}}' "$ELASTICSEARCH_URL/_ilm/policy/my_policy"
client.ilm().putLifecycle(p -> p
    .name("my_policy")
    .policy(po -> po
        .phases(ph -> ph
            .delete(d -> d
                .actions(a -> a
                    .delete(de -> de)
                )
                .minAge(m -> m
                    .time("30d")
                )
            )
            .warm(w -> w
                .actions(a -> a
                    .forcemerge(f -> f
                        .maxNumSegments(1)
                    )
                )
                .minAge(m -> m
                    .time("10d")
                )
            )
        )
        .meta(Map.of("description", JsonData.fromJson("\"used for nginx log\""),"project", JsonData.fromJson("{\"name\":\"myProject\",\"department\":\"myDepartment\"}")))
    )
);
Request example
Run `PUT _ilm/policy/my_policy` to create a new policy with arbitrary metadata.
{
  "policy": {
    "_meta": {
      "description": "used for nginx log",
      "project": {
        "name": "myProject",
        "department": "myDepartment"
      }
    },
    "phases": {
      "warm": {
        "min_age": "10d",
        "actions": {
          "forcemerge": {
            "max_num_segments": 1
          }
        }
      },
      "delete": {
        "min_age": "30d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}
Response examples (200)
A successful response when creating a new lifecycle policy.
{
  "acknowledged": true
}




































Inference

Inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Azure, Google AI Studio or Hugging Face. For built-in models and models uploaded through Eland, the inference APIs offer an alternative way to use and manage trained models. However, if you do not plan to use the inference APIs to use these models or if you want to use non-NLP models, use the machine learning trained model APIs.













Create an inference endpoint Generally available; Added in 8.11.0

PUT /_inference/{task_type}/{inference_id}

All methods and paths for this operation:

PUT /_inference/{inference_id}

PUT /_inference/{task_type}/{inference_id}

IMPORTANT: The inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Mistral, Azure OpenAI, Google AI Studio, Google Vertex AI, Anthropic, Watsonx.ai, or Hugging Face. For built-in models and models uploaded through Eland, the inference APIs offer an alternative way to use and manage trained models. However, if you do not plan to use the inference APIs to use these models or if you want to use non-NLP models, use the machine learning trained model APIs.

The following integrations are available through the inference API. You can find the available task types next to the integration name:

  • AlibabaCloud AI Search (completion, rerank, sparse_embedding, text_embedding)
  • Amazon Bedrock (completion, text_embedding)
  • Amazon SageMaker (chat_completion, completion, rerank, sparse_embedding, text_embedding)
  • Anthropic (completion)
  • Azure AI Studio (completion, text_embedding)
  • Azure OpenAI (completion, text_embedding)
  • Cohere (completion, rerank, text_embedding)
  • DeepSeek (chat_completion, completion)
  • Elasticsearch (rerank, sparse_embedding, text_embedding - this service is for built-in models and models uploaded through Eland)
  • ELSER (sparse_embedding)
  • Google AI Studio (completion, text_embedding)
  • Google Vertex AI (chat_completion, completion, rerank, text_embedding)
  • Hugging Face (chat_completion, completion, rerank, text_embedding)
  • JinaAI (rerank, text_embedding)
  • Llama (chat_completion, completion, text_embedding)
  • Mistral (chat_completion, completion, text_embedding)
  • OpenAI (chat_completion, completion, text_embedding)
  • VoyageAI (rerank, text_embedding)
  • Watsonx inference integration (text_embedding)

Required authorization

  • Cluster privileges: manage_inference

Path parameters

  • task_type string Required

    The task type. Refer to the integration list in the API description for the available task types.

    Values are sparse_embedding, text_embedding, rerank, completion, or chat_completion.

  • inference_id string Required

    The inference Id

Query parameters

  • timeout string

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

    Values are -1 or 0.

application/json

Body Required

  • chunking_settings object

    Chunking configuration object

    Hide chunking_settings attributes Show chunking_settings attributes object
    • max_chunk_size number

      The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).

      Default value is 250.

    • overlap number

      The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.

      Default value is 100.

    • sentence_overlap number

      The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.

      Default value is 1.

    • strategy string

      The chunking strategy: sentence or word.

      Default value is sentence.

  • service string Required

    The service type

  • service_settings object Required
  • task_settings object

Responses

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

    Represents an inference endpoint as returned by the GET API

    • chunking_settings object

      Chunking configuration object

      Hide chunking_settings attributes Show chunking_settings attributes object
      • max_chunk_size number

        The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).

        Default value is 250.

      • overlap number

        The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.

        Default value is 100.

      • sentence_overlap number

        The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.

        Default value is 1.

      • strategy string

        The chunking strategy: sentence or word.

        Default value is sentence.

    • service string Required

      The service type

    • service_settings object Required
    • task_settings object
    • inference_id string Required

      The inference Id

    • task_type string Required

      Values are sparse_embedding, text_embedding, rerank, completion, or chat_completion.

PUT /_inference/{task_type}/{inference_id}
PUT _inference/rerank/my-rerank-model
{
 "service": "cohere",
 "service_settings": {
   "model_id": "rerank-english-v3.0",
   "api_key": "{{COHERE_API_KEY}}"
 }
}
resp = client.inference.put(
    task_type="rerank",
    inference_id="my-rerank-model",
    inference_config={
        "service": "cohere",
        "service_settings": {
            "model_id": "rerank-english-v3.0",
            "api_key": "{{COHERE_API_KEY}}"
        }
    },
)
const response = await client.inference.put({
  task_type: "rerank",
  inference_id: "my-rerank-model",
  inference_config: {
    service: "cohere",
    service_settings: {
      model_id: "rerank-english-v3.0",
      api_key: "{{COHERE_API_KEY}}",
    },
  },
});
response = client.inference.put(
  task_type: "rerank",
  inference_id: "my-rerank-model",
  body: {
    "service": "cohere",
    "service_settings": {
      "model_id": "rerank-english-v3.0",
      "api_key": "{{COHERE_API_KEY}}"
    }
  }
)
$resp = $client->inference()->put([
    "task_type" => "rerank",
    "inference_id" => "my-rerank-model",
    "body" => [
        "service" => "cohere",
        "service_settings" => [
            "model_id" => "rerank-english-v3.0",
            "api_key" => "{{COHERE_API_KEY}}",
        ],
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"service":"cohere","service_settings":{"model_id":"rerank-english-v3.0","api_key":"{{COHERE_API_KEY}}"}}' "$ELASTICSEARCH_URL/_inference/rerank/my-rerank-model"
client.inference().put(p -> p
    .inferenceId("my-rerank-model")
    .taskType(TaskType.Rerank)
    .inferenceConfig(i -> i
        .service("cohere")
        .serviceSettings(JsonData.fromJson("{\"model_id\":\"rerank-english-v3.0\",\"api_key\":\"{{COHERE_API_KEY}}\"}"))
    )
);
Request example
An example body for a `PUT _inference/rerank/my-rerank-model` request.
{
 "service": "cohere",
 "service_settings": {
   "model_id": "rerank-english-v3.0",
   "api_key": "{{COHERE_API_KEY}}"
 }
}




Delete an inference endpoint Generally available; Added in 8.11.0

DELETE /_inference/{task_type}/{inference_id}

All methods and paths for this operation:

DELETE /_inference/{inference_id}

DELETE /_inference/{task_type}/{inference_id}

Path parameters

  • task_type string Required

    The task type

    Values are sparse_embedding, text_embedding, rerank, completion, or chat_completion.

  • inference_id string Required

    The inference identifier.

Query parameters

  • dry_run boolean

    When true, the endpoint is not deleted and a list of ingest processors which reference this endpoint is returned.

  • force boolean

    When true, the inference endpoint is forcefully deleted even if it is still being used by ingest processors or semantic text fields.

Responses

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

    Acknowledged response. For dry_run, contains the list of pipelines which reference the inference endpoint

    • acknowledged boolean Required

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

    • pipelines array[string] Required
DELETE /_inference/{task_type}/{inference_id}
DELETE /_inference/sparse_embedding/my-elser-model
resp = client.inference.delete(
    task_type="sparse_embedding",
    inference_id="my-elser-model",
)
const response = await client.inference.delete({
  task_type: "sparse_embedding",
  inference_id: "my-elser-model",
});
response = client.inference.delete(
  task_type: "sparse_embedding",
  inference_id: "my-elser-model"
)
$resp = $client->inference()->delete([
    "task_type" => "sparse_embedding",
    "inference_id" => "my-elser-model",
]);
curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_inference/sparse_embedding/my-elser-model"
client.inference().delete(d -> d
    .inferenceId("my-elser-model")
    .taskType(TaskType.SparseEmbedding)
);








Create an Amazon SageMaker inference endpoint Generally available; Added in 9.1.0

PUT /_inference/{task_type}/{amazonsagemaker_inference_id}

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

Required authorization

  • Cluster privileges: manage_inference

Path parameters

  • task_type string

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

    Values are text_embedding, completion, chat_completion, sparse_embedding, or rerank.

  • amazonsagemaker_inference_id string Required

    The unique identifier of the inference endpoint.

Query parameters

  • timeout string

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

    Values are -1 or 0.

application/json

Body

  • chunking_settings object

    Chunking configuration object

    Hide chunking_settings attributes Show chunking_settings attributes object
    • max_chunk_size number

      The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).

      Default value is 250.

    • overlap number

      The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.

      Default value is 100.

    • sentence_overlap number

      The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.

      Default value is 1.

    • strategy string

      The chunking strategy: sentence or word.

      Default value is sentence.

  • service string Required

    Value is amazon_sagemaker.

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

      A valid AWS access key that has permissions to use Amazon SageMaker and access to models for invoking requests.

    • endpoint_name string Required

      The name of the SageMaker endpoint.

      External documentation
    • api string Required

      Values are openai or elastic.

    • region string Required

      The region that your endpoint or Amazon Resource Name (ARN) is deployed in. The list of available regions per model can be found in the Amazon SageMaker documentation.

      External documentation
    • secret_key string Required

      A valid AWS secret key that is paired with the access_key. For information about creating and managing access and secret keys, refer to the AWS documentation.

      External documentation
    • target_model string

      The model ID when calling a multi-model endpoint.

      External documentation
    • target_container_hostname string

      The container to directly invoke when calling a multi-container endpoint.

      External documentation
    • inference_component_name string

      The inference component to directly invoke when calling a multi-component endpoint.

      External documentation
    • batch_size number

      The maximum number of inputs in each batch. This value is used by inference ingestion pipelines when processing semantic values. It correlates to the number of times the SageMaker endpoint is invoked (one per batch of input).

      Default value is 256.

    • dimensions number

      The number of dimensions returned by the text embedding models. If this value is not provided, then it is guessed by making invoking the endpoint for the text_embedding task.

  • task_settings object
    Hide task_settings attributes Show task_settings attributes object
    • custom_attributes string

      The AWS custom attributes passed verbatim through to the model running in the SageMaker Endpoint. Values will be returned in the X-elastic-sagemaker-custom-attributes header.

      External documentation
    • enable_explanations string

      The optional JMESPath expression used to override the EnableExplanations provided during endpoint creation.

      External documentation
    • inference_id string

      The capture data ID when enabled in the endpoint.

      External documentation
    • session_id string

      The stateful session identifier for a new or existing session. New sessions will be returned in the X-elastic-sagemaker-new-session-id header. Closed sessions will be returned in the X-elastic-sagemaker-closed-session-id header.

      External documentation
    • target_variant string

      Specifies the variant when running with multi-variant Endpoints.

      External documentation

Responses

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

      Chunking configuration object

      Hide chunking_settings attributes Show chunking_settings attributes object
      • max_chunk_size number

        The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).

        Default value is 250.

      • overlap number

        The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.

        Default value is 100.

      • sentence_overlap number

        The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.

        Default value is 1.

      • strategy string

        The chunking strategy: sentence or word.

        Default value is sentence.

    • service string Required

      The service type

    • service_settings object Required
    • task_settings object
    • inference_id string Required

      The inference Id

    • task_type string Required

      Values are text_embedding, completion, chat_completion, sparse_embedding, or rerank.

PUT /_inference/{task_type}/{amazonsagemaker_inference_id}
PUT _inference/text_embedding/amazon_sagemaker_embeddings
{
    "service": "amazon_sagemaker",
    "service_settings": {
        "access_key": "AWS-access-key",
        "secret_key": "AWS-secret-key",
        "region": "us-east-1",
        "api": "elastic",
        "endpoint_name": "my-endpoint",
        "dimensions": 384,
        "element_type": "float"
    }
}
resp = client.inference.put(
    task_type="text_embedding",
    inference_id="amazon_sagemaker_embeddings",
    inference_config={
        "service": "amazon_sagemaker",
        "service_settings": {
            "access_key": "AWS-access-key",
            "secret_key": "AWS-secret-key",
            "region": "us-east-1",
            "api": "elastic",
            "endpoint_name": "my-endpoint",
            "dimensions": 384,
            "element_type": "float"
        }
    },
)
const response = await client.inference.put({
  task_type: "text_embedding",
  inference_id: "amazon_sagemaker_embeddings",
  inference_config: {
    service: "amazon_sagemaker",
    service_settings: {
      access_key: "AWS-access-key",
      secret_key: "AWS-secret-key",
      region: "us-east-1",
      api: "elastic",
      endpoint_name: "my-endpoint",
      dimensions: 384,
      element_type: "float",
    },
  },
});
response = client.inference.put(
  task_type: "text_embedding",
  inference_id: "amazon_sagemaker_embeddings",
  body: {
    "service": "amazon_sagemaker",
    "service_settings": {
      "access_key": "AWS-access-key",
      "secret_key": "AWS-secret-key",
      "region": "us-east-1",
      "api": "elastic",
      "endpoint_name": "my-endpoint",
      "dimensions": 384,
      "element_type": "float"
    }
  }
)
$resp = $client->inference()->put([
    "task_type" => "text_embedding",
    "inference_id" => "amazon_sagemaker_embeddings",
    "body" => [
        "service" => "amazon_sagemaker",
        "service_settings" => [
            "access_key" => "AWS-access-key",
            "secret_key" => "AWS-secret-key",
            "region" => "us-east-1",
            "api" => "elastic",
            "endpoint_name" => "my-endpoint",
            "dimensions" => 384,
            "element_type" => "float",
        ],
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"service":"amazon_sagemaker","service_settings":{"access_key":"AWS-access-key","secret_key":"AWS-secret-key","region":"us-east-1","api":"elastic","endpoint_name":"my-endpoint","dimensions":384,"element_type":"float"}}' "$ELASTICSEARCH_URL/_inference/text_embedding/amazon_sagemaker_embeddings"
Run `PUT _inference/text_embedding/amazon_sagemaker_embeddings` to create an inference endpoint that performs a text embedding task.
{
    "service": "amazon_sagemaker",
    "service_settings": {
        "access_key": "AWS-access-key",
        "secret_key": "AWS-secret-key",
        "region": "us-east-1",
        "api": "elastic",
        "endpoint_name": "my-endpoint",
        "dimensions": 384,
        "element_type": "float"
    }
}
Run `PUT _inference/completion/amazon_sagemaker_completion` to create an inference endpoint that performs a completion task.
{
    "service": "amazon_sagemaker",
    "service_settings": {
        "access_key": "AWS-access-key",
        "secret_key": "AWS-secret-key",
        "region": "us-east-1",
        "api": "elastic",
        "endpoint_name": "my-endpoint"
    }
}
Run `PUT _inference/chat_completion/amazon_sagemaker_chat_completion` to create an inference endpoint that performs a chat completion task.
{
    "service": "amazon_sagemaker",
    "service_settings": {
        "access_key": "AWS-access-key",
        "secret_key": "AWS-secret-key",
        "region": "us-east-1",
        "api": "elastic",
        "endpoint_name": "my-endpoint"
    }
}
Run `PUT _inference/sparse_embedding/amazon_sagemaker_sparse_embedding` to create an inference endpoint that performs a sparse embedding task.
{
    "service": "amazon_sagemaker",
    "service_settings": {
        "access_key": "AWS-access-key",
        "secret_key": "AWS-secret-key",
        "region": "us-east-1",
        "api": "elastic",
        "endpoint_name": "my-endpoint"
    }
}
Run `PUT _inference/rerank/amazon_sagemaker_rerank` to create an inference endpoint that performs a rerank task.
{
    "service": "amazon_sagemaker",
    "service_settings": {
        "access_key": "AWS-access-key",
        "secret_key": "AWS-secret-key",
        "region": "us-east-1",
        "api": "elastic",
        "endpoint_name": "my-endpoint"
    }
}








Create an Azure OpenAI inference endpoint Generally available; Added in 8.14.0

PUT /_inference/{task_type}/{azureopenai_inference_id}

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

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

The list of embeddings models that you can choose from in your deployment can be found in the Azure models documentation.

Required authorization

  • Cluster privileges: manage_inference

Path parameters

  • task_type string

    The type of the inference task that the model will perform. NOTE: The chat_completion task type only supports streaming and only through the _stream API.

    Values are completion or text_embedding.

  • azureopenai_inference_id string Required

    The unique identifier of the inference endpoint.

Query parameters

  • timeout string

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

    Values are -1 or 0.

application/json

Body

  • chunking_settings object

    Chunking configuration object

    Hide chunking_settings attributes Show chunking_settings attributes object
    • max_chunk_size number

      The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).

      Default value is 250.

    • overlap number

      The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.

      Default value is 100.

    • sentence_overlap number

      The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.

      Default value is 1.

    • strategy string

      The chunking strategy: sentence or word.

      Default value is sentence.

  • service string Required

    Value is azureopenai.

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

      A valid API key for your Azure OpenAI account. You must specify either api_key or entra_id. If you do not provide either or you provide both, you will receive an error when you try to create your model.

      IMPORTANT: You need to provide the API key only once, during the inference model creation. The get inference endpoint API does not retrieve your API key. After creating the inference model, you cannot change the associated API key. If you want to use a different API key, delete the inference model and recreate it with the same name and the updated API key.

      External documentation
    • api_version string Required

      The Azure API version ID to use. It is recommended to use the latest supported non-preview version.

    • deployment_id string Required

      The deployment name of your deployed models. Your Azure OpenAI deployments can be found though the Azure OpenAI Studio portal that is linked to your subscription.

      External documentation
    • entra_id string

      A valid Microsoft Entra token. You must specify either api_key or entra_id. If you do not provide either or you provide both, you will receive an error when you try to create your model.

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

        The number of requests allowed per minute.

    • resource_name string Required

      The name of your Azure OpenAI resource. You can find this from the list of resources in the Azure Portal for your subscription.

      External documentation
  • task_settings object
    Hide task_settings attribute Show task_settings attribute object
    • user string

      For a completion or text_embedding task, specify the user issuing the request. This information can be used for abuse detection.

Responses

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

      Chunking configuration object

      Hide chunking_settings attributes Show chunking_settings attributes object
      • max_chunk_size number

        The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).

        Default value is 250.

      • overlap number

        The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.

        Default value is 100.

      • sentence_overlap number

        The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.

        Default value is 1.

      • strategy string

        The chunking strategy: sentence or word.

        Default value is sentence.

    • service string Required

      The service type

    • service_settings object Required
    • task_settings object
    • inference_id string Required

      The inference Id

    • task_type string Required

      Values are text_embedding or completion.

PUT /_inference/{task_type}/{azureopenai_inference_id}
PUT _inference/text_embedding/azure_openai_embeddings
{
    "service": "azureopenai",
    "service_settings": {
        "api_key": "Api-Key",
        "resource_name": "Resource-name",
        "deployment_id": "Deployment-id",
        "api_version": "2024-02-01"
    }
}
resp = client.inference.put(
    task_type="text_embedding",
    inference_id="azure_openai_embeddings",
    inference_config={
        "service": "azureopenai",
        "service_settings": {
            "api_key": "Api-Key",
            "resource_name": "Resource-name",
            "deployment_id": "Deployment-id",
            "api_version": "2024-02-01"
        }
    },
)
const response = await client.inference.put({
  task_type: "text_embedding",
  inference_id: "azure_openai_embeddings",
  inference_config: {
    service: "azureopenai",
    service_settings: {
      api_key: "Api-Key",
      resource_name: "Resource-name",
      deployment_id: "Deployment-id",
      api_version: "2024-02-01",
    },
  },
});
response = client.inference.put(
  task_type: "text_embedding",
  inference_id: "azure_openai_embeddings",
  body: {
    "service": "azureopenai",
    "service_settings": {
      "api_key": "Api-Key",
      "resource_name": "Resource-name",
      "deployment_id": "Deployment-id",
      "api_version": "2024-02-01"
    }
  }
)
$resp = $client->inference()->put([
    "task_type" => "text_embedding",
    "inference_id" => "azure_openai_embeddings",
    "body" => [
        "service" => "azureopenai",
        "service_settings" => [
            "api_key" => "Api-Key",
            "resource_name" => "Resource-name",
            "deployment_id" => "Deployment-id",
            "api_version" => "2024-02-01",
        ],
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"service":"azureopenai","service_settings":{"api_key":"Api-Key","resource_name":"Resource-name","deployment_id":"Deployment-id","api_version":"2024-02-01"}}' "$ELASTICSEARCH_URL/_inference/text_embedding/azure_openai_embeddings"
client.inference().put(p -> p
    .inferenceId("azure_openai_embeddings")
    .taskType(TaskType.TextEmbedding)
    .inferenceConfig(i -> i
        .service("azureopenai")
        .serviceSettings(JsonData.fromJson("{\"api_key\":\"Api-Key\",\"resource_name\":\"Resource-name\",\"deployment_id\":\"Deployment-id\",\"api_version\":\"2024-02-01\"}"))
    )
);
Request examples
Run `PUT _inference/text_embedding/azure_openai_embeddings` to create an inference endpoint that performs a `text_embedding` task. You do not specify a model, as it is defined already in the Azure OpenAI deployment.
{
    "service": "azureopenai",
    "service_settings": {
        "api_key": "Api-Key",
        "resource_name": "Resource-name",
        "deployment_id": "Deployment-id",
        "api_version": "2024-02-01"
    }
}
Run `PUT _inference/completion/azure_openai_completion` to create an inference endpoint that performs a `completion` task.
{
    "service": "azureopenai",
    "service_settings": {
        "api_key": "Api-Key",
        "resource_name": "Resource-name",
        "deployment_id": "Deployment-id",
        "api_version": "2024-02-01"
    }
}






















































































Delete GeoIP database configurations Generally available; Added in 8.15.0

DELETE /_ingest/geoip/database/{id}

Delete one or more IP geolocation database configurations.

Path parameters

  • id string | array[string] Required

    A comma-separated list of geoip database configurations to delete

Query parameters

  • master_timeout string

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

    Values are -1 or 0.

  • timeout string

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

    Values are -1 or 0.

Responses

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

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

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

































































Start a trial Generally available; Added in 6.1.0

POST /_license/start_trial

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

NOTE: You are allowed to start a trial only if your cluster has not already activated a trial for the current major product version. For example, if you have already activated a trial for v8.0, you cannot start a new trial until v9.0. You can, however, request an extended trial at https://www.elastic.co/trialextension.

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

Required authorization

  • Cluster privileges: manage

Query parameters

  • acknowledge boolean

    whether the user has acknowledged acknowledge messages (default: false)

  • type string

    The type of trial license to generate (default: "trial")

  • master_timeout string

    Period to wait for a connection to the master node.

    Values are -1 or 0.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • acknowledged boolean Required
    • error_message string
    • trial_was_started boolean Required
    • type string

      Values are missing, trial, basic, standard, dev, silver, gold, platinum, or enterprise.

POST /_license/start_trial?acknowledge=true
resp = client.license.post_start_trial(
    acknowledge=True,
)
const response = await client.license.postStartTrial({
  acknowledge: "true",
});
response = client.license.post_start_trial(
  acknowledge: "true"
)
$resp = $client->license()->postStartTrial([
    "acknowledge" => "true",
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_license/start_trial?acknowledge=true"
client.license().postStartTrial(p -> p
    .acknowledge(true)
);
Response examples (200)
A successful response from `POST /_license/start_trial?acknowledge=true`.
{
  "trial_was_started": true,
  "acknowledged": true
}





Create or update a Logstash pipeline Generally available; Added in 7.12.0

PUT /_logstash/pipeline/{id}

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

Required authorization

  • Cluster privileges: manage_logstash_pipelines
External documentation

Path parameters

  • id string Required

    An identifier for the pipeline.

application/json

Body Required

  • description string Required

    A description of the pipeline. This description is not used by Elasticsearch or Logstash.

  • last_modified string | number Required

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

    One of:
  • pipeline string Required

    The configuration for the pipeline.

    External documentation
  • pipeline_metadata object Required
    Hide pipeline_metadata attributes Show pipeline_metadata attributes object
    • type string Required
    • version string Required
  • pipeline_settings object Required
    Hide pipeline_settings attributes Show pipeline_settings attributes object
    • pipeline.workers number Required

      The number of workers that will, in parallel, execute the filter and output stages of the pipeline.

    • pipeline.batch.size number Required

      The maximum number of events an individual worker thread will collect from inputs before attempting to execute its filters and outputs.

    • pipeline.batch.delay number Required

      When creating pipeline event batches, how long in milliseconds to wait for each event before dispatching an undersized batch to pipeline workers.

    • queue.type string Required

      The internal queuing model to use for event buffering.

    • queue.max_bytes string Required

      The total capacity of the queue (queue.type: persisted) in number of bytes.

    • queue.checkpoint.writes number Required

      The maximum number of written events before forcing a checkpoint when persistent queues are enabled (queue.type: persisted).

  • username string Required

    The user who last updated the pipeline.

Responses

  • 200 application/json
PUT _logstash/pipeline/my_pipeline
{
  "description": "Sample pipeline for illustration purposes",
  "last_modified": "2021-01-02T02:50:51.250Z",
  "pipeline_metadata": {
    "type": "logstash_pipeline",
    "version": 1
  },
  "username": "elastic",
  "pipeline": "input {}\\n filter { grok {} }\\n output {}",
  "pipeline_settings": {
    "pipeline.workers": 1,
    "pipeline.batch.size": 125,
    "pipeline.batch.delay": 50,
    "queue.type": "memory",
    "queue.max_bytes": "1gb",
    "queue.checkpoint.writes": 1024
  }
}
resp = client.logstash.put_pipeline(
    id="my_pipeline",
    pipeline={
        "description": "Sample pipeline for illustration purposes",
        "last_modified": "2021-01-02T02:50:51.250Z",
        "pipeline_metadata": {
            "type": "logstash_pipeline",
            "version": 1
        },
        "username": "elastic",
        "pipeline": "input {}\\n filter { grok {} }\\n output {}",
        "pipeline_settings": {
            "pipeline.workers": 1,
            "pipeline.batch.size": 125,
            "pipeline.batch.delay": 50,
            "queue.type": "memory",
            "queue.max_bytes": "1gb",
            "queue.checkpoint.writes": 1024
        }
    },
)
const response = await client.logstash.putPipeline({
  id: "my_pipeline",
  pipeline: {
    description: "Sample pipeline for illustration purposes",
    last_modified: "2021-01-02T02:50:51.250Z",
    pipeline_metadata: {
      type: "logstash_pipeline",
      version: 1,
    },
    username: "elastic",
    pipeline: "input {}\\n filter { grok {} }\\n output {}",
    pipeline_settings: {
      "pipeline.workers": 1,
      "pipeline.batch.size": 125,
      "pipeline.batch.delay": 50,
      "queue.type": "memory",
      "queue.max_bytes": "1gb",
      "queue.checkpoint.writes": 1024,
    },
  },
});
response = client.logstash.put_pipeline(
  id: "my_pipeline",
  body: {
    "description": "Sample pipeline for illustration purposes",
    "last_modified": "2021-01-02T02:50:51.250Z",
    "pipeline_metadata": {
      "type": "logstash_pipeline",
      "version": 1
    },
    "username": "elastic",
    "pipeline": "input {}\\n filter { grok {} }\\n output {}",
    "pipeline_settings": {
      "pipeline.workers": 1,
      "pipeline.batch.size": 125,
      "pipeline.batch.delay": 50,
      "queue.type": "memory",
      "queue.max_bytes": "1gb",
      "queue.checkpoint.writes": 1024
    }
  }
)
$resp = $client->logstash()->putPipeline([
    "id" => "my_pipeline",
    "body" => [
        "description" => "Sample pipeline for illustration purposes",
        "last_modified" => "2021-01-02T02:50:51.250Z",
        "pipeline_metadata" => [
            "type" => "logstash_pipeline",
            "version" => 1,
        ],
        "username" => "elastic",
        "pipeline" => "input {}\\n filter { grok {} }\\n output {}",
        "pipeline_settings" => [
            "pipeline.workers" => 1,
            "pipeline.batch.size" => 125,
            "pipeline.batch.delay" => 50,
            "queue.type" => "memory",
            "queue.max_bytes" => "1gb",
            "queue.checkpoint.writes" => 1024,
        ],
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"description":"Sample pipeline for illustration purposes","last_modified":"2021-01-02T02:50:51.250Z","pipeline_metadata":{"type":"logstash_pipeline","version":1},"username":"elastic","pipeline":"input {}\\n filter { grok {} }\\n output {}","pipeline_settings":{"pipeline.workers":1,"pipeline.batch.size":125,"pipeline.batch.delay":50,"queue.type":"memory","queue.max_bytes":"1gb","queue.checkpoint.writes":1024}}' "$ELASTICSEARCH_URL/_logstash/pipeline/my_pipeline"
client.logstash().putPipeline(p -> p
    .id("my_pipeline")
    .pipeline(pi -> pi
        .description("Sample pipeline for illustration purposes")
        .lastModified(DateTime.of("2021-01-02T02:50:51.250Z"))
        .pipeline("input {}\n filter { grok {} }\n output {}")
        .pipelineMetadata(pip -> pip
            .type("logstash_pipeline")
            .version("1")
        )
        .pipelineSettings(pip -> pip
            .pipelineWorkers(1)
            .pipelineBatchSize(125)
            .pipelineBatchDelay(50)
            .queueType("memory")
            .queueMaxBytes("1gb")
            .queueCheckpointWrites(1024)
        )
        .username("elastic")
    )
);
Request example
Run `PUT _logstash/pipeline/my_pipeline` to create a pipeline.
{
  "description": "Sample pipeline for illustration purposes",
  "last_modified": "2021-01-02T02:50:51.250Z",
  "pipeline_metadata": {
    "type": "logstash_pipeline",
    "version": 1
  },
  "username": "elastic",
  "pipeline": "input {}\\n filter { grok {} }\\n output {}",
  "pipeline_settings": {
    "pipeline.workers": 1,
    "pipeline.batch.size": 125,
    "pipeline.batch.delay": 50,
    "queue.type": "memory",
    "queue.max_bytes": "1gb",
    "queue.checkpoint.writes": 1024
  }
}













Set upgrade_mode for ML indices Generally available; Added in 6.7.0

POST /_ml/set_upgrade_mode

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

Required authorization

  • Cluster privileges: manage_ml

Query parameters

  • enabled boolean

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

  • timeout string

    The time to wait for the request to be completed.

    Values are -1 or 0.

Responses

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

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

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





Create a calendar Generally available; Added in 6.2.0

PUT /_ml/calendars/{calendar_id}

Required authorization

  • Cluster privileges: manage_ml

Path parameters

  • calendar_id string Required

    A string that uniquely identifies a calendar.

application/json

Body

  • job_ids array[string]

    An array of anomaly detection job identifiers.

  • description string

    A description of the calendar.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
PUT /_ml/calendars/{calendar_id}
PUT _ml/calendars/planned-outages
resp = client.ml.put_calendar(
    calendar_id="planned-outages",
)
const response = await client.ml.putCalendar({
  calendar_id: "planned-outages",
});
response = client.ml.put_calendar(
  calendar_id: "planned-outages"
)
$resp = $client->ml()->putCalendar([
    "calendar_id" => "planned-outages",
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ml/calendars/planned-outages"
client.ml().putCalendar(p -> p
    .calendarId("planned-outages")
);








Delete events from a calendar Generally available; Added in 6.2.0

DELETE /_ml/calendars/{calendar_id}/events/{event_id}

Path parameters

  • calendar_id string Required

    A string that uniquely identifies a calendar.

  • event_id string Required

    Identifier for the scheduled event. You can obtain this identifier by using the get calendar events API.

Responses

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

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

DELETE /_ml/calendars/{calendar_id}/events/{event_id}
DELETE _ml/calendars/planned-outages/events/LS8LJGEBMTCMA-qz49st
resp = client.ml.delete_calendar_event(
    calendar_id="planned-outages",
    event_id="LS8LJGEBMTCMA-qz49st",
)
const response = await client.ml.deleteCalendarEvent({
  calendar_id: "planned-outages",
  event_id: "LS8LJGEBMTCMA-qz49st",
});
response = client.ml.delete_calendar_event(
  calendar_id: "planned-outages",
  event_id: "LS8LJGEBMTCMA-qz49st"
)
$resp = $client->ml()->deleteCalendarEvent([
    "calendar_id" => "planned-outages",
    "event_id" => "LS8LJGEBMTCMA-qz49st",
]);
curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ml/calendars/planned-outages/events/LS8LJGEBMTCMA-qz49st"
client.ml().deleteCalendarEvent(d -> d
    .calendarId("planned-outages")
    .eventId("LS8LJGEBMTCMA-qz49st")
);
Response examples (200)
A successful response when deleting a calendar event.
{
  "acknowledged": true
}