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

Required authorization

  • Index privileges: view_index_metadata

Query parameters

  • allow_no_indices boolean

    A setting that does two separate checks on the index expression. If false, the request returns an error (1) if any wildcard expression (including _all and *) resolves to zero matching indices or (2) if the complete set of resolved indices, aliases or data streams is empty after all expressions are evaluated. If true, index expressions that resolve to no indices are allowed and the request returns an empty result.

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

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

  • ignore_unavailable boolean

    If false, the request returns an error if it targets a concrete (non-wildcarded) index, alias, or data stream that is missing, closed, or otherwise unavailable. If true, unavailable concrete targets are silently ignored.

  • local boolean

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

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

    External documentation
  • preference string

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

  • routing string | array[string]

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

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • nodes object Required
      Hide nodes attribute Show nodes attribute object
      • * object Additional properties
        Hide * attributes Show * attributes object
        • name string Required

          The human-readable identifier of the node.

        • ephemeral_id string Required

          The ephemeral ID of the node.

        • transport_address string Required

          The host and port where transport HTTP connections are accepted.

        • external_id string Required Generally available; Added in 8.3.0
        • attributes object Required

          Lists node attributes.

          Hide attributes attribute Show attributes attribute object
          • * string Additional properties
        • roles array[string] Required

          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.

        • version string Required
        • min_index_version number Required
        • max_index_version number Required
    • shards array[array] Required
      Hide shards attributes Show shards attributes object
      • state string Required

        Values are UNASSIGNED, INITIALIZING, STARTED, or RELOCATING.

      • primary boolean Required
      • node string
      • shard number Required
      • index string Required
      • allocation_id object
        Hide allocation_id attribute Show allocation_id attribute object
        • * string
      • recovery_source object
        Hide recovery_source attribute Show recovery_source attribute object
        • * string
      • unassigned_info object
        Hide unassigned_info attributes Show unassigned_info attributes object
        • last_allocation_status string
        • details string
        • failed_allocation_attempts number
        • delayed boolean
        • allocation_status string

      • relocating_node string | null

        One of:
        NodeId string string-2 string | null
      • relocation_failure_info object
        Hide relocation_failure_info attribute Show relocation_failure_info attribute object
        • failed_attempts number Required
    • indices object Required
      Hide indices attribute Show indices attribute object
      • * object Additional properties
        Hide * attributes Show * attributes object
        • aliases array[string]
        • filter object

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

          External documentation
          Hide filter attributes Show filter attributes object
          • common object Deprecated
          • distance_feature
          • fuzzy object

            Returns documents that contain terms similar to the search term, as measured by a Levenshtein edit distance.

            External documentation
          • geo_grid object

            Matches geo_point and geo_shape values that intersect a grid cell from a GeoGrid aggregation.

          • intervals object

            Returns documents based on the order and proximity of matching terms.

            External documentation
          • match object

            Returns documents that match a provided text, number, date or boolean value. The provided text is analyzed before matching.

            External documentation
          • match_bool_prefix object

            Analyzes its input and constructs a bool query from the terms. Each term except the last is used in a term query. The last term is used in a prefix query.

            External documentation
          • match_phrase object

            Analyzes the text and creates a phrase query out of the analyzed text.

            External documentation
          • match_phrase_prefix object

            Returns documents that contain the words of a provided text, in the same order as provided. The last term of the provided text is treated as a prefix, matching any words that begin with that term.

            External documentation
          • prefix object

            Returns documents that contain a specific prefix in a provided field.

            External documentation
          • range object

            Returns documents that contain terms within a provided range.

            External documentation
          • regexp object

            Returns documents that contain terms matching a regular expression.

            External documentation
          • span_term object

            Matches spans containing a term.

            External documentation
          • term object

            Returns documents that contain an exact term in a provided field. To return a document, the query term must exactly match the queried field's value, including whitespace and capitalization.

            External documentation
          • terms_set object

            Returns documents that contain a minimum number of exact terms in a provided field. To return a document, a required number of terms must exactly match the field values, including whitespace and capitalization.

            External documentation
          • text_expansion object Deprecated Generally available; Added in 8.8.0

            Uses a natural language processing model to convert the query text into a list of token-weight pairs which are then used in a query against a sparse vector or rank features field.

            External documentation
          • weighted_tokens object Deprecated Generally available; Added in 8.13.0

            Supports returning text_expansion query results by sending in precomputed tokens with the query.

            External documentation
          • wildcard object

            Returns documents that contain terms matching a wildcard pattern.

            External documentation
GET /_search_shards 
curl \
 --request GET 'http://api.example.com/_search_shards'
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
          }
      }
      ]
    ]
  }