Get shard information

GET /_cat/shards

Get information about the shards in a cluster. For data streams, the API returns information about the backing indices. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications.

Query parameters

  • bytes string

    The unit used to display byte values.

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

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

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

  • time string

    Unit used to display time values.

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

Responses

GET /_cat/shards
curl \
 --request GET http://api.example.com/_cat/shards \
 --header "Authorization: $API_KEY"
Response examples (200)
[
  {
    "index": "string",
    "shard": "string",
    "prirep": "string",
    "state": "string",
    "docs": "string",
    "store": "string",
    "dataset": "string",
    "ip": "string",
    "id": "string",
    "node": "string",
    "sync_id": "string",
    "unassigned.reason": "string",
    "unassigned.at": "string",
    "unassigned.for": "string",
    "unassigned.details": "string",
    "recoverysource.type": "string",
    "completion.size": "string",
    "fielddata.memory_size": "string",
    "fielddata.evictions": "string",
    "query_cache.memory_size": "string",
    "query_cache.evictions": "string",
    "flush.total": "string",
    "flush.total_time": "string",
    "get.current": "string",
    "get.time": "string",
    "get.total": "string",
    "get.exists_time": "string",
    "get.exists_total": "string",
    "get.missing_time": "string",
    "get.missing_total": "string",
    "indexing.delete_current": "string",
    "indexing.delete_time": "string",
    "indexing.delete_total": "string",
    "indexing.index_current": "string",
    "indexing.index_time": "string",
    "indexing.index_total": "string",
    "indexing.index_failed": "string",
    "merges.current": "string",
    "merges.current_docs": "string",
    "merges.current_size": "string",
    "merges.total": "string",
    "merges.total_docs": "string",
    "merges.total_size": "string",
    "merges.total_time": "string",
    "refresh.total": "string",
    "refresh.time": "string",
    "refresh.external_total": "string",
    "refresh.external_time": "string",
    "refresh.listeners": "string",
    "search.fetch_current": "string",
    "search.fetch_time": "string",
    "search.fetch_total": "string",
    "search.open_contexts": "string",
    "search.query_current": "string",
    "search.query_time": "string",
    "search.query_total": "string",
    "search.scroll_current": "string",
    "search.scroll_time": "string",
    "search.scroll_total": "string",
    "segments.count": "string",
    "segments.memory": "string",
    "segments.index_writer_memory": "string",
    "segments.version_map_memory": "string",
    "segments.fixed_bitset_memory": "string",
    "seq_no.max": "string",
    "seq_no.local_checkpoint": "string",
    "seq_no.global_checkpoint": "string",
    "warmer.current": "string",
    "warmer.total": "string",
    "warmer.total_time": "string",
    "path.data": "string",
    "path.state": "string",
    "bulk.total_operations": "string",
    "bulk.total_time": "string",
    "bulk.total_size_in_bytes": "string",
    "bulk.avg_time": "string",
    "bulk.avg_size_in_bytes": "string"
  }
]





















































































































































































Path parameters

  • node_id string | array[string] Required

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

Query parameters

  • timeout string

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

Responses

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

      Additional properties are allowed.

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

          The type of error

        • reason string

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

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

        • Additional properties are allowed.

        • root_cause array[object]

          Additional properties are allowed.

        • suppressed array[object]

          Additional properties are allowed.

      • total number Required

        Total number of nodes selected by the request.

      • successful number Required

        Number of nodes that responded successfully to the request.

      • failed number Required

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

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

        Additional properties are allowed.

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

          Time unit for milliseconds

        • Time unit for milliseconds

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

            Additional properties are allowed.

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




































































































































































































































































































































































































































































































































































Get tokens from text analysis

POST /_analyze

The analyze API performs analysis on a text string and returns the resulting tokens.

Generating excessive amount of tokens may cause a node to run out of memory. The index.analyze.max_token_count setting enables you to limit the number of tokens that can be produced. If more than this limit of tokens gets generated, an error occurs. The _analyze endpoint without a specified index will always use 10000 as its limit.

application/json

Body

Responses

POST /_analyze
curl \
 --request POST http://api.example.com/_analyze \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"text":"this is a test","analyzer":"standard"}'
Request example
You can apply any of the built-in analyzers to the text string without specifying an index.
{
  "text": "this is a test",
  "analyzer": "standard"
}
Response examples (200)
{
  "detail": {
    "analyzer": {
      "name": "string",
      "tokens": [
        {
          "bytes": "string",
          "end_offset": 42.0,
          "keyword": true,
          "position": 42.0,
          "positionLength": 42.0,
          "start_offset": 42.0,
          "termFrequency": 42.0,
          "token": "string",
          "type": "string"
        }
      ]
    },
    "charfilters": [
      {
        "filtered_text": [
          "string"
        ],
        "name": "string"
      }
    ],
    "custom_analyzer": true,
    "tokenfilters": [
      {
        "name": "string",
        "tokens": [
          {
            "bytes": "string",
            "end_offset": 42.0,
            "keyword": true,
            "position": 42.0,
            "positionLength": 42.0,
            "start_offset": 42.0,
            "termFrequency": 42.0,
            "token": "string",
            "type": "string"
          }
        ]
      }
    ],
    "tokenizer": {
      "name": "string",
      "tokens": [
        {
          "bytes": "string",
          "end_offset": 42.0,
          "keyword": true,
          "position": 42.0,
          "positionLength": 42.0,
          "start_offset": 42.0,
          "termFrequency": 42.0,
          "token": "string",
          "type": "string"
        }
      ]
    }
  },
  "tokens": [
    {
      "end_offset": 42.0,
      "position": 42.0,
      "positionLength": 42.0,
      "start_offset": 42.0,
      "token": "string",
      "type": "string"
    }
  ]
}




































































































































Get field usage stats Technical preview

GET /{index}/_field_usage_stats

Get field usage information for each shard and field of an index. Field usage statistics are automatically captured when queries are running on a cluster. A shard-level search request that accesses a given field, even if multiple times during that request, is counted as a single use.

The response body reports the per-shard usage count of the data structures that back the fields in the index. A given request will increment each count by a maximum value of 1, even if the request accesses the same field multiple times.

Path parameters

  • index string | array[string] Required

    Comma-separated list or wildcard expression of index names used to limit the request.

Query parameters

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

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

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

  • fields string | array[string]

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

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

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • _shards object Required

      Additional properties are allowed.

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

          Additional properties are allowed.

          Hide reason attributes Show reason attributes object
          • type string Required

            The type of error

          • reason string

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

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

          • Additional properties are allowed.

          • root_cause array[object]

            Additional properties are allowed.

          • suppressed array[object]

            Additional properties are allowed.

        • shard number Required
        • status string
      • skipped number
GET /{index}/_field_usage_stats
curl \
 --request GET http://api.example.com/{index}/_field_usage_stats \
 --header "Authorization: $API_KEY"
Response examples (200)
{
  "_shards": {
    "failed": 42.0,
    "successful": 42.0,
    "total": 42.0,
    "failures": [
      {
        "index": "string",
        "node": "string",
        "reason": {
          "type": "string",
          "reason": "string",
          "stack_trace": "string",
          "caused_by": {},
          "root_cause": [
            {}
          ],
          "suppressed": [
            {}
          ]
        },
        "shard": 42.0,
        "status": "string"
      }
    ],
    "skipped": 42.0
  }
}





















































































































































































































































































































































































































































Update the license

PUT /_license

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

NOTE: If Elasticsearch security features are enabled and you are installing a gold or higher license, you must enable TLS on the transport networking layer before you install the license. If the operator privileges feature is enabled, only operator users can use this API.

Query parameters

  • Specifies whether you acknowledge the license changes.

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

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

application/json

Body

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
PUT /_license
curl \
 --request PUT http://api.example.com/_license \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"licenses\": [\n    {\n      \"uid\":\"893361dc-9749-4997-93cb-802e3d7fa4xx\",\n      \"type\":\"basic\",\n      \"issue_date_in_millis\":1411948800000,\n      \"expiry_date_in_millis\":1914278399999,\n      \"max_nodes\":1,\n      \"issued_to\":\"issuedTo\",\n      \"issuer\":\"issuer\",\n      \"signature\":\"xx\"\n    }\n    ]\n}"'
Request example
Run `PUT _license` to update to a basic license. NOTE: These values are invalid; you must substitute the appropriate contents from your license file.
{
  "licenses": [
    {
      "uid":"893361dc-9749-4997-93cb-802e3d7fa4xx",
      "type":"basic",
      "issue_date_in_millis":1411948800000,
      "expiry_date_in_millis":1914278399999,
      "max_nodes":1,
      "issued_to":"issuedTo",
      "issuer":"issuer",
      "signature":"xx"
    }
    ]
}
Response examples (200)
If you update to a basic license and you previously had a license with more features, you receive this type of response. You must re-submit the API request and set the `acknowledge` parameter to `true`.
{
  "acknowledge": {
    "message": "\"\"\"This license update requires acknowledgement. To acknowledge the license, please read the following messages and update the license again, this time with the \"acknowledge=true\" parameter:\"\"\"",
    "watcher": [
      "Watcher will be disabled"
    ],
    "logstash": [
      "Logstash will no longer poll for centrally-managed pipelines"
    ],
    "security": [
      "The following X-Pack security functionality will be disabled ..."
    ]
  },
  "acknowledged": false,
  "license_status": "valid"
}



















































































































































































































































































































Revert to a snapshot Added in 5.4.0

POST /_ml/anomaly_detectors/{job_id}/model_snapshots/{snapshot_id}/_revert

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

Path parameters

  • job_id string Required

    Identifier for the anomaly detection job.

  • snapshot_id string Required

    You can specify empty as the . Reverting to the empty snapshot means the anomaly detection job starts learning a new model from scratch when it is started.

Query parameters

  • If true, deletes the results in the time period between the latest results and the time of the reverted snapshot. It also resets the model to accept records for this time period. If you choose not to delete intervening results when reverting a snapshot, the job will not accept input data that is older than the current time. If you want to resend data, then delete the intervening results.

application/json

Body

Responses

POST /_ml/anomaly_detectors/{job_id}/model_snapshots/{snapshot_id}/_revert
curl \
 --request POST http://api.example.com/_ml/anomaly_detectors/{job_id}/model_snapshots/{snapshot_id}/_revert \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"delete_intervening_results":true}'
Request examples
{
  "delete_intervening_results": true
}
Response examples (200)
{
  "model": {
    "description": "string",
    "job_id": "string",
    "latest_record_time_stamp": 42.0,
    "latest_result_time_stamp": 42.0,
    "min_version": "string",
    "model_size_stats": {
      "bucket_allocation_failures_count": 42.0,
      "job_id": "string",
      "": 42.0,
      "memory_status": "ok",
      "assignment_memory_basis": "string",
      "result_type": "string",
      "total_by_field_count": 42.0,
      "total_over_field_count": 42.0,
      "total_partition_field_count": 42.0,
      "categorization_status": "ok",
      "categorized_doc_count": 42.0,
      "dead_category_count": 42.0,
      "failed_category_count": 42.0,
      "frequent_category_count": 42.0,
      "rare_category_count": 42.0,
      "total_category_count": 42.0,
      "timestamp": 42.0
    },
    "retain": true,
    "snapshot_doc_count": 42.0,
    "snapshot_id": "string",
    "timestamp": 42.0
  }
}

















































































































































































































































































































































































































































































































































Run a search

POST /_search

Get search hits that match the query defined in the request. You can provide search queries using the q query string parameter or the request body. If both are specified, only the query parameter is used.

If the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias. For cross-cluster search, refer to the documentation about configuring CCS privileges. To search a point in time (PIT) for an alias, you must have the read index privilege for the alias's data streams or indices.

Search slicing

When paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently with the slice and pit properties. By default the splitting is done first on the shards, then locally on each shard. The local splitting partitions the shard into contiguous ranges based on Lucene document IDs.

For instance if the number of shards is equal to 2 and you request 4 slices, the slices 0 and 2 are assigned to the first shard and the slices 1 and 3 are assigned to the second shard.

IMPORTANT: The same point-in-time ID should be used for all slices. If different PIT IDs are used, slices can overlap and miss documents. This situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index.

Query parameters

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

  • If true and there are shard request timeouts or shard failures, the request returns partial results. If false, it returns an error with no partial results.

    To override the default behavior, you can set the search.default_allow_partial_results cluster setting to false.

  • analyzer string

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

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

  • The number of shard results that should be reduced at once on the coordinating node. If the potential number of shards in the request can be large, this value should be used as a protection mechanism to reduce the memory overhead per search request.

  • If true, network round-trips between the coordinating node and the remote clusters are minimized when running cross-cluster search (CCS) requests.

  • The default operator for the 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 a default when no field prefix is given in the query string. This parameter can be used only when the q query string parameter is specified.

  • docvalue_fields string | array[string]

    A comma-separated list of fields to return as the docvalue representation of a field for each hit.

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

  • explain boolean

    If true, the request returns detailed information about score computation as part of a hit.

  • ignore_throttled boolean Deprecated

    If true, concrete, expanded or aliased indices will be ignored when frozen.

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

  • If true, the response includes the score contribution from any named queries.

    This functionality reruns each named query on every hit in a search response. Typically, this adds a small overhead to a request. However, using computationally expensive named queries on a large number of hits may add significant overhead.

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

  • The number of concurrent shard requests per node that the search runs concurrently. This value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests.

  • The nodes and shards used for the search. By default, Elasticsearch selects from eligible nodes and shards using adaptive replica selection, accounting for allocation awareness. Valid values are:

    • _only_local to run the search only on shards on the local node.
    • _local to, if possible, run the search on shards on the local node, or if not, select shards using the default method.
    • _only_nodes:<node-id>,<node-id> to run the search on only the specified nodes IDs. If suitable shards exist on more than one selected node, use shards on those nodes using the default method. If none of the specified nodes are available, select shards from any available node using the default method.
    • _prefer_nodes:<node-id>,<node-id> to if possible, run the search on the specified nodes IDs. If not, select shards using the default method. _shards:<shard>,<shard> to run the search only on the specified shards. You can combine this value with other preference values. However, the _shards value must come first. For example: _shards:2,3|_local. <custom-string> (any string that does not start with _) to route searches with the same <custom-string> to the same shards in the same order.
  • A threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method (if date filters are mandatory to match but the shard bounds and the query are disjoint). When unspecified, the pre-filter phase is executed if any of these conditions is met:

    • The request targets more than 128 shards.
    • The request targets one or more read-only index.
    • The primary sort of the query targets an indexed field.
  • If true, the caching of search results is enabled for requests where size is 0. It defaults to index level settings.

  • routing string

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

  • scroll string

    The period to retain the search context for scrolling. By default, this value cannot exceed 1d (24 hours). You can change this limit by using the search.max_keep_alive cluster-level setting.

  • Indicates how distributed term frequencies are calculated for relevance scoring.

    Values are query_then_fetch or dfs_query_then_fetch.

  • stats array[string]

    Specific tag of the request for logging and statistical purposes.

  • stored_fields string | array[string]

    A comma-separated list of stored fields to return as part of a hit. If no fields are specified, no stored fields are included in the response. If this field is specified, the _source parameter defaults to false. You can pass _source: true to return both source fields and stored fields in the search response.

  • The field to use for suggestions.

  • The suggest mode. This parameter can be used only when the suggest_field and suggest_text query string parameters are specified.

    Values are missing, popular, or always.

  • The number of suggestions to return. This parameter can be used only when the suggest_field and suggest_text query string parameters are specified.

  • The source text for which the suggestions should be returned. This parameter can be used only when the suggest_field and suggest_text query string parameters are specified.

  • 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. If set to 0 (default), the query does not terminate early.

  • timeout string

    The period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. It defaults to no timeout.

  • track_total_hits boolean | number

    The number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query.

  • If true, the request calculates and returns document scores, even if the scores are not used for sorting.

  • typed_keys boolean

    If true, aggregation and suggester names are be prefixed by their respective types in the response.

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

  • version boolean

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

  • _source boolean | string | array[string]

    The source fields that are returned for matching documents. These fields are returned in the hits._source property of the search response. Valid values are:

    • true to return the entire document source.
    • false to not return the document source.
    • <string> to return the source fields that are specified as a comma-separated list that supports wildcard (*) patterns.
  • _source_excludes string | array[string]

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

  • _source_includes string | array[string]

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

  • If true, the request returns the sequence number and primary term of the last modification of each hit.

  • q string

    A query in the Lucene query string syntax. Query parameter searches do not support the full Elasticsearch Query DSL but are handy for testing.

    IMPORTANT: This parameter overrides the query parameter in the request body. If both parameters are specified, documents matching the query request body parameter are not returned.

  • size number

    The number of hits to return. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.

  • from number

    The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.

  • sort string | array[string]

    A comma-separated list of <field>:<direction> pairs.

  • Should this request force synthetic _source? Use this to test if the mapping supports synthetic _source and to get a sense of the worst case performance. Fetches with this enabled will be slower the enabling synthetic source natively in the index.

application/json

Body

  • Defines the aggregations that are run as part of the search request.

  • collapse object

    Additional properties are allowed.

  • explain boolean

    If true, the request returns detailed information about score computation as part of a hit.

  • ext object

    Configuration of search extensions defined by Elasticsearch plugins.

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

      Additional properties are allowed.

  • from number

    The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.

  • Additional properties are allowed.

    Hide highlight attributes Show highlight attributes object
    • A string that contains each boundary character.

    • How far to scan for boundary characters.

    • Values are chars, sentence, or word.

    • Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".

    • force_source boolean Deprecated
    • Values are simple or span.

    • The size of the highlighted fragment in characters.

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

      Additional properties are allowed.

    • If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.

    • The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.

    • The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.

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

        Additional properties are allowed.

    • order string

      Value is score.

    • Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.

    • post_tags array[string]

      Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in <em> and </em> tags.

    • pre_tags array[string]

      Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in <em> and </em> tags.

    • By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.

    • Value is styled.

    • encoder string

      Values are default or html.

    • fields object Required
  • track_total_hits boolean | number

    Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.

  • indices_boost array[object]

    Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.

    Hide indices_boost attribute Show indices_boost attribute object
    • * number Additional properties
  • docvalue_fields array[object]

    An array of wildcard (*) field patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.

    Hide docvalue_fields attributes Show docvalue_fields attributes object
    • field string Required

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

    • format string

      The format in which the values are returned.

  • knn object | array[object]

    The approximate kNN search to run.

    One of:
    Hide attributes Show attributes
    • field string Required

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

    • query_vector array[number]
    • Additional properties are allowed.

      Hide query_vector_builder attribute Show query_vector_builder attribute object
    • k number

      The final number of nearest neighbors to return as top hits

    • The number of nearest neighbor candidates to consider per shard

    • boost number

      Boost value to apply to kNN scores

    • filter object | array[object]

      Filters for the kNN search query

      One of:

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

      Additional properties are allowed.

    • The minimum similarity for a vector to be considered a match

    • Additional properties are allowed.

      Hide inner_hits attributes Show inner_hits attributes object
      • name string
      • size number

        The maximum number of hits to return per inner_hits.

      • from number

        Inner hit starting document offset.

      • collapse object

        Additional properties are allowed.

      • docvalue_fields array[object]
        Hide docvalue_fields attributes Show docvalue_fields attributes object
        • field string Required

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

        • format string

          The format in which the values are returned.

      • explain boolean
      • Additional properties are allowed.

        Hide highlight attributes Show highlight attributes object
        • A string that contains each boundary character.

        • How far to scan for boundary characters.

        • Values are chars, sentence, or word.

        • Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".

        • force_source boolean Deprecated
        • Values are simple or span.

        • The size of the highlighted fragment in characters.

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

          Additional properties are allowed.

        • If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.

        • The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.

        • The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.

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

            Additional properties are allowed.

        • order string

          Value is score.

        • Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.

        • post_tags array[string]

          Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in <em> and </em> tags.

        • pre_tags array[string]

          Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in <em> and </em> tags.

        • By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.

        • Value is styled.

        • encoder string

          Values are default or html.

        • fields object Required
      • Hide script_fields attribute Show script_fields attribute object
        • * object Additional properties

          Additional properties are allowed.

          Hide * attributes Show * attributes object
          • script object Required

            Additional properties are allowed.

            Hide script attributes Show script attributes object
            • source string

              The script source.

            • id string
            • params object

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

            • options object
      • fields string | array[string]
      • sort string | object | array[string | object]

        One of:

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

      • _source boolean | object

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

        One of:
      • stored_fields string | array[string]
      • version boolean
    • Additional properties are allowed.

      Hide rescore_vector attribute Show rescore_vector attribute object
      • oversample number Required

        Applies the specified oversample factor to k on the approximate kNN search

  • rank object

    Additional properties are allowed.

    Hide rank attribute Show rank attribute object
    • rrf object

      Additional properties are allowed.

      Hide rrf attributes Show rrf attributes object
      • How much influence documents in individual result sets per query have over the final ranked result set

      • Size of the individual result sets per query

  • The minimum _score for matching documents. Documents with a lower _score are not included in the search results.

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

    Additional properties are allowed.

  • profile boolean

    Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.

  • query object

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

    Additional properties are allowed.

  • rescore object | array[object]

    Can be used to improve precision by reordering just the top (for example 100 - 500) documents returned by the query and post_filter phases.

    One of:
    Hide attributes Show attributes
    • query object

      Additional properties are allowed.

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

      Hide learning_to_rank attributes Show learning_to_rank attributes object
      • model_id string Required

        The unique identifier of the trained model uploaded to Elasticsearch

      • params object

        Named parameters to be passed to the query templates used for feature

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

          Additional properties are allowed.

  • Additional properties are allowed.

    Hide retriever attributes Show retriever attributes object
    • standard object

      Additional properties are allowed.

      Hide standard attributes Show standard attributes object
    • knn object

      Additional properties are allowed.

      Hide knn attributes Show knn attributes object
      • filter object | array[object]

        Query to filter the documents that can match.

        One of:

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

        Additional properties are allowed.

      • Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.

      • field string Required

        The name of the vector field to search against.

      • query_vector array[number]
      • Additional properties are allowed.

        Hide query_vector_builder attribute Show query_vector_builder attribute object
      • k number Required

        Number of nearest neighbors to return as top hits.

      • num_candidates number Required

        Number of nearest neighbor candidates to consider per shard.

      • The minimum similarity required for a document to be considered a match.

      • Additional properties are allowed.

        Hide rescore_vector attribute Show rescore_vector attribute object
        • oversample number Required

          Applies the specified oversample factor to k on the approximate kNN search

    • rrf object

      Additional properties are allowed.

      Hide rrf attributes Show rrf attributes object
      • filter object | array[object]

        Query to filter the documents that can match.

        One of:

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

        Additional properties are allowed.

      • Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.

      • retrievers array[object] Required

        A list of child retrievers to specify which sets of returned top documents will have the RRF formula applied to them.

        Additional properties are allowed.

      • This value determines how much influence documents in individual result sets per query have over the final ranked result set.

      • This value determines the size of the individual result sets per query.

    • Additional properties are allowed.

      Hide text_similarity_reranker attributes Show text_similarity_reranker attributes object
      • filter object | array[object]

        Query to filter the documents that can match.

        One of:

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

        Additional properties are allowed.

      • Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.

      • retriever object Required

        Additional properties are allowed.

      • This value determines how many documents we will consider from the nested retriever.

      • Unique identifier of the inference endpoint created using the inference API.

      • The text snippet used as the basis for similarity comparison

      • field string

        The document field to be used for text similarity comparisons. This field should contain the text that will be evaluated against the inference_text

    • rule object

      Additional properties are allowed.

      Hide rule attributes Show rule attributes object
      • filter object | array[object]

        Query to filter the documents that can match.

        One of:

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

        Additional properties are allowed.

      • Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.

      • ruleset_ids array[string] Required

        The ruleset IDs containing the rules this retriever is evaluating against.

      • match_criteria object Required

        The match criteria that will determine if a rule in the provided rulesets should be applied.

        Additional properties are allowed.

      • retriever object Required

        Additional properties are allowed.

      • This value determines the size of the individual result set.

  • Retrieve a script evaluation (based on different fields) for each hit.

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

      Additional properties are allowed.

      Hide * attributes Show * attributes object
      • script object Required

        Additional properties are allowed.

        Hide script attributes Show script attributes object
        • source string

          The script source.

        • id string
        • params object

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

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

            Additional properties are allowed.

        • lang string

          Any of:

          Values are painless, expression, mustache, or java.

        • options object
          Hide options attribute Show options attribute object
          • * string Additional properties
  • search_after array[number | string | boolean | null]

    A field value.

  • size number

    The number of hits to return, which must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after property.

  • slice object

    Additional properties are allowed.

    Hide slice attributes Show slice attributes object
    • field string

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

    • id string Required
    • max number Required
  • sort string | object | array[string | object]

    One of:

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

  • _source boolean | object

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

    One of:
  • fields array[object]

    An array of wildcard (*) field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.

    Hide fields attributes Show fields attributes object
    • field string Required

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

    • format string

      The format in which the values are returned.

  • suggest object

    Additional properties are allowed.

    Hide suggest attribute Show suggest attribute object
    • text string

      Global suggest text, to avoid repetition when the same text is used in several suggesters

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

    IMPORTANT: Use with caution. Elasticsearch applies this property to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this property for requests that target data streams with backing indices across multiple data tiers.

    If set to 0 (default), the query does not terminate early.

  • timeout string

    The period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.

  • If true, calculate and return document scores, even if the scores are not used for sorting.

  • version boolean

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

  • If true, the request returns sequence number and primary term of the last modification of each hit.

  • stored_fields string | array[string]
  • pit object

    Additional properties are allowed.

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

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

      Additional properties are allowed.

      Hide * attributes Show * attributes object
      • fields object

        For type composite

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

          Additional properties are allowed.

          Hide * attribute Show * attribute object
          • type string Required

            Values are boolean, composite, date, double, geo_point, 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.

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

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

      • script object

        Additional properties are allowed.

        Hide script attributes Show script attributes object
        • source string

          The script source.

        • id string
        • params object

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

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

            Additional properties are allowed.

        • lang string

          Any of:

          Values are painless, expression, mustache, or java.

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

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

  • stats array[string]

    The stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.

Responses

POST /_search
curl \
 --request POST http://api.example.com/_search \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"query\": {\n    \"term\": {\n      \"user.id\": \"kimchy\"\n    }\n  }\n}"'
Run `GET /my-index-000001/_search?from=40&size=20` to run a search.
{
  "query": {
    "term": {
      "user.id": "kimchy"
    }
  }
}
Run `POST /_search` to run a point in time search. The `id` parameter tells Elasticsearch to run the request using contexts from this open point in time. The `keep_alive` parameter tells Elasticsearch how long it should extend the time to live of the point in time.
{
    "size": 100,  
    "query": {
        "match" : {
            "title" : "elasticsearch"
        }
    },
    "pit": {
      "id":  "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA==", 
      "keep_alive": "1m"  
    }
}
When paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently. The result from running the first `GET /_search` request returns documents belonging to the first slice (`id: 0`). If you run a second request with `id` set to `1', it returns documents in the second slice. Since the maximum number of slices is set to `2`, the union of the results is equivalent to the results of a point-in-time search without slicing.
{
  "slice": {
    "id": 0,                      
    "max": 2                      
  },
  "query": {
    "match": {
      "message": "foo"
    }
  },
  "pit": {
    "id": "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA=="
  }
}
Response examples (200)
An abbreviated response from `GET /my-index-000001/_search?from=40&size=20` with a simple term query.
{
  "took": 5,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 20,
      "relation": "eq"
    },
    "max_score": 1.3862942,
    "hits": [
      {
        "_index": "my-index-000001",
        "_id": "0",
        "_score": 1.3862942,
        "_source": {
          "@timestamp": "2099-11-15T14:12:12",
          "http": {
            "request": {
              "method": "get"
            },
            "response": {
              "status_code": 200,
              "bytes": 1070000
            },
            "version": "1.1"
          },
          "source": {
            "ip": "127.0.0.1"
          },
          "message": "GET /search HTTP/1.1 200 1070000",
          "user": {
            "id": "kimchy"
          }
        }
      }
    ]
  }
}




























Get the search shards

POST /{index}/_search_shards

Get the indices and shards that a search request would be run against. This information can be useful for working out issues or planning optimizations with routing and shard preferences. When filtered aliases are used, the filter is returned as part of the indices section.

If the Elasticsearch security features are enabled, you must have the view_index_metadata or manage index privilege for the target data stream, index, or alias.

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 and indices, omit this parameter or use * or _all.

Query parameters

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

  • expand_wildcards string | array[string]

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

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

  • local boolean

    If true, the request retrieves information from the local node only.

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

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

  • routing string

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

Responses

POST /{index}/_search_shards
curl \
 --request POST http://api.example.com/{index}/_search_shards \
 --header "Authorization: $API_KEY"
Response examples (200)
An abbreviated response from `GET /my-index-000001/_search_shards`.
{
  "nodes": {},
  "indices": {
      "my-index-000001": { }
  },
  "shards": [
      [
      {
          "index": "my-index-000001",
          "node": "JklnKbD7Tyqi9TP3_Q_tBg",
          "relocating_node": null,
          "primary": true,
          "shard": 0,
          "state": "STARTED",
          "allocation_id": {"id":"0TvkCyF7TAmM1wHP4a42-A"},
          "relocation_failure_info" : {
          "failed_attempts" : 0
          }
      }
      ],
      [
      {
          "index": "my-index-000001",
          "node": "JklnKbD7Tyqi9TP3_Q_tBg",
          "relocating_node": null,
          "primary": true,
          "shard": 1,
          "state": "STARTED",
          "allocation_id": {"id":"fMju3hd1QHWmWrIgFnI4Ww"},
          "relocation_failure_info" : {
          "failed_attempts" : 0
          }
      }
      ],
      [
      {
          "index": "my-index-000001",
          "node": "JklnKbD7Tyqi9TP3_Q_tBg",
          "relocating_node": null,
          "primary": true,
          "shard": 2,
          "state": "STARTED",
          "allocation_id": {"id":"Nwl0wbMBTHCWjEEbGYGapg"},
          "relocation_failure_info" : {
          "failed_attempts" : 0
          }
      }
      ],
      [
      {
          "index": "my-index-000001",
          "node": "JklnKbD7Tyqi9TP3_Q_tBg",
          "relocating_node": null,
          "primary": true,
          "shard": 3,
          "state": "STARTED",
          "allocation_id": {"id":"bU_KLGJISbW0RejwnwDPKw"},
          "relocation_failure_info" : {
          "failed_attempts" : 0
          }
      }
      ],
      [
      {
          "index": "my-index-000001",
          "node": "JklnKbD7Tyqi9TP3_Q_tBg",
          "relocating_node": null,
          "primary": true,
          "shard": 4,
          "state": "STARTED",
          "allocation_id": {"id":"DMs7_giNSwmdqVukF7UydA"},
          "relocation_failure_info" : {
          "failed_attempts" : 0
          }
      }
      ]
    ]
  }






























































Clear the cache Technical preview

POST /_searchable_snapshots/cache/clear

Clear indices and data streams from the shared cache for partially mounted indices.

Query parameters

  • expand_wildcards string | array[string]

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

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

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

Responses

  • 200 application/json

    Additional properties are allowed.

POST /_searchable_snapshots/cache/clear
curl \
 --request POST http://api.example.com/_searchable_snapshots/cache/clear \
 --header "Authorization: $API_KEY"
Response examples (200)
{}

































































Clear the user cache

POST /_security/realm/{realms}/_clear_cache

Evict users from the user cache. You can completely clear the cache or evict specific users.

User credentials are cached in memory on each node to avoid connecting to a remote authentication service or hitting the disk for every incoming request. There are realm settings that you can use to configure the user cache. For more information, refer to the documentation about controlling the user cache.

Path parameters

  • realms string | array[string] Required

    A comma-separated list of realms. To clear all realms, use an asterisk (*). It does not support other wildcard patterns.

Query parameters

  • usernames array[string]

    A comma-separated list of the users to clear from the cache. If you do not specify this parameter, the API evicts all users from the user cache.

Responses

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

      Additional properties are allowed.

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

          The type of error

        • reason string

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

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

        • Additional properties are allowed.

        • root_cause array[object]

          Additional properties are allowed.

        • suppressed array[object]

          Additional properties are allowed.

      • total number Required

        Total number of nodes selected by the request.

      • successful number Required

        Number of nodes that responded successfully to the request.

      • failed number Required

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

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

        Additional properties are allowed.

        Hide * attribute Show * attribute object
POST /_security/realm/{realms}/_clear_cache
curl \
 --request POST http://api.example.com/_security/realm/{realms}/_clear_cache \
 --header "Authorization: $API_KEY"
Response examples (200)
{
  "_nodes": {
    "failures": [
      {
        "type": "string",
        "reason": "string",
        "stack_trace": "string",
        "caused_by": {},
        "root_cause": [
          {}
        ],
        "suppressed": [
          {}
        ]
      }
    ],
    "total": 42.0,
    "successful": 42.0,
    "failed": 42.0
  },
  "cluster_name": "string",
  "nodes": {
    "additionalProperty1": {
      "name": "string"
    },
    "additionalProperty2": {
      "name": "string"
    }
  }
}
















Create an API key Added in 6.7.0

POST /_security/api_key

Create an API key for access without requiring basic authentication.

IMPORTANT: If the credential that is used to authenticate this request is an API key, the derived API key cannot have any privileges. If you specify privileges, the API returns an error.

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

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

The API keys are created by the Elasticsearch API key service, which is automatically enabled. To configure or turn off the API key service, refer to API key service setting documentation.

Query parameters

  • refresh string

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

    Values are true, false, or wait_for.

application/json

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

  • name string
  • An array of role descriptors for this API key. When it is not specified or it is an empty array, the API key will have a point in time snapshot of permissions of the authenticated user. If you supply role descriptors, the resultant permissions are an intersection of API keys permissions and the authenticated user's permissions thereby limiting the access scope for API keys. The structure of role descriptor is the same as the request for the create role API. For more details, refer to the create or update roles API.

    NOTE: Due to the way in which this permission intersection is calculated, it is not possible to create an API key that is a child of another API key, unless the derived key is created without any privileges. In this case, you must explicitly specify a role descriptor with no privileges. The derived API key can be used for authentication; it will not have authority to call Elasticsearch APIs.

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

      Additional properties are allowed.

      Hide * attributes Show * attributes object
      • cluster array[string]

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

      • indices array[object]

        A list of indices permissions entries.

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

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

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

        • privileges array[string] Required

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

        • query string | object

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

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

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

      • remote_indices array[object]

        A list of indices permissions for remote clusters.

        Hide remote_indices attributes Show remote_indices attributes object
        • clusters string | array[string] Required
        • Additional properties are allowed.

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

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

        • privileges array[string] Required

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

        • query string | object

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

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

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

      • remote_cluster array[object]

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

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

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

          Values are monitor_enrich or monitor_stats.

      • global array[object] | object

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

        One of:
        Hide attribute Show attribute object
        • application object Required

          Additional properties are allowed.

          Hide application attribute Show application attribute object
          • manage object Required

            Additional properties are allowed.

      • applications array[object]

        A list of application privilege entries

        Hide applications attributes Show applications attributes object
        • application string Required

          The name of the application to which this entry applies.

        • privileges array[string] Required

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

        • resources array[string] Required

          A list resources to which the privileges are applied.

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

          Additional properties are allowed.

      • run_as array[string]

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

      • Optional description of the role descriptor

      • Additional properties are allowed.

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

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

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

          Additional properties are allowed.

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

      Additional properties are allowed.

Responses

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

      Generated API key.

    • Expiration in milliseconds for the API key.

    • id string Required
    • name string Required
    • encoded string Required

      API key credentials which is the base64-encoding of the UTF-8 representation of id and api_key joined by a colon (:).

POST /_security/api_key
curl \
 --request POST http://api.example.com/_security/api_key \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"expiration":"string","name":"string","role_descriptors":{"additionalProperty1":{"cluster":["string"],"indices":[{"field_security":{"except":"string","grant":"string"},"names":"string","privileges":["string"],"":"string","allow_restricted_indices":true}],"remote_indices":[{"clusters":"string","field_security":{"except":"string","grant":"string"},"names":"string","privileges":["string"],"":"string","allow_restricted_indices":true}],"remote_cluster":[{"clusters":"string","privileges":["monitor_enrich"]}],"global":[{"application":{"manage":{}}}],"applications":[{"application":"string","privileges":["string"],"resources":["string"]}],"metadata":{"additionalProperty1":{},"additionalProperty2":{}},"run_as":["string"],"description":"string","restriction":{"workflows":["string"]},"transient_metadata":{"additionalProperty1":{},"additionalProperty2":{}}},"additionalProperty2":{"cluster":["string"],"indices":[{"field_security":{"except":"string","grant":"string"},"names":"string","privileges":["string"],"":"string","allow_restricted_indices":true}],"remote_indices":[{"clusters":"string","field_security":{"except":"string","grant":"string"},"names":"string","privileges":["string"],"":"string","allow_restricted_indices":true}],"remote_cluster":[{"clusters":"string","privileges":["monitor_enrich"]}],"global":[{"application":{"manage":{}}}],"applications":[{"application":"string","privileges":["string"],"resources":["string"]}],"metadata":{"additionalProperty1":{},"additionalProperty2":{}},"run_as":["string"],"description":"string","restriction":{"workflows":["string"]},"transient_metadata":{"additionalProperty1":{},"additionalProperty2":{}}}},"metadata":{"additionalProperty1":{},"additionalProperty2":{}}}'
Request examples
{
  "expiration": "string",
  "name": "string",
  "role_descriptors": {
    "additionalProperty1": {
      "cluster": [
        "string"
      ],
      "indices": [
        {
          "field_security": {
            "except": "string",
            "grant": "string"
          },
          "names": "string",
          "privileges": [
            "string"
          ],
          "": "string",
          "allow_restricted_indices": true
        }
      ],
      "remote_indices": [
        {
          "clusters": "string",
          "field_security": {
            "except": "string",
            "grant": "string"
          },
          "names": "string",
          "privileges": [
            "string"
          ],
          "": "string",
          "allow_restricted_indices": true
        }
      ],
      "remote_cluster": [
        {
          "clusters": "string",
          "privileges": [
            "monitor_enrich"
          ]
        }
      ],
      "global": [
        {
          "application": {
            "manage": {}
          }
        }
      ],
      "applications": [
        {
          "application": "string",
          "privileges": [
            "string"
          ],
          "resources": [
            "string"
          ]
        }
      ],
      "metadata": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      },
      "run_as": [
        "string"
      ],
      "description": "string",
      "restriction": {
        "workflows": [
          "string"
        ]
      },
      "transient_metadata": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      }
    },
    "additionalProperty2": {
      "cluster": [
        "string"
      ],
      "indices": [
        {
          "field_security": {
            "except": "string",
            "grant": "string"
          },
          "names": "string",
          "privileges": [
            "string"
          ],
          "": "string",
          "allow_restricted_indices": true
        }
      ],
      "remote_indices": [
        {
          "clusters": "string",
          "field_security": {
            "except": "string",
            "grant": "string"
          },
          "names": "string",
          "privileges": [
            "string"
          ],
          "": "string",
          "allow_restricted_indices": true
        }
      ],
      "remote_cluster": [
        {
          "clusters": "string",
          "privileges": [
            "monitor_enrich"
          ]
        }
      ],
      "global": [
        {
          "application": {
            "manage": {}
          }
        }
      ],
      "applications": [
        {
          "application": "string",
          "privileges": [
            "string"
          ],
          "resources": [
            "string"
          ]
        }
      ],
      "metadata": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      },
      "run_as": [
        "string"
      ],
      "description": "string",
      "restriction": {
        "workflows": [
          "string"
        ]
      },
      "transient_metadata": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      }
    }
  },
  "metadata": {
    "additionalProperty1": {},
    "additionalProperty2": {}
  }
}
Response examples (200)
{
  "api_key": "string",
  "expiration": 42.0,
  "id": "string",
  "name": "string",
  "encoded": "string"
}