---
type: api
title: Run multiple templated searches
description: **All methods and paths for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch/v8/operation/operation-msearch-template
resource: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch/v8/operation/operation-msearch-template
products:
  - Elasticsearch
---

# Run multiple templated searches


Availability: Generally available since 5.0

## Paths

- `POST` (also `GET`) `/{index}/_msearch/template`
- `POST` (also `GET`) `/_msearch/template`

#### Path parameters

- `index` (union string | string[]) — optional, leave it out to use `/_msearch/template`
  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 `*`.

## Description

Run multiple templated searches with a single request.
If you are providing a text file or text input to `curl`, use the `--data-binary` flag instead of `-d` to preserve newlines.
For example:

```
$ cat requests
{ "index": "my-index" }
{ "id": "my-search-template", "params": { "query_string": "hello world", "from": 0, "size": 10 }}
{ "index": "my-other-index" }
{ "id": "my-other-search-template", "params": { "query_type": "match_all" }}

$ curl -H "Content-Type: application/x-ndjson" -XGET localhost:9200/_msearch/template --data-binary "@requests"; echo
```

[Read the reference documentation](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/search-template.html)

## Required authorization

- Index privileges: `read`

## Authentication

- Api key: `Authorization: <value>`
  Elasticsearch APIs support key-based authentication.
  You must create an API key and use the encoded value in the request header.
  For example:
  
  
  ```
  curl -X GET "${ES_URL}/_cat/indices?v=true" \
    -H "Authorization: ApiKey ${API_KEY}"
  ```
  
  To get API keys, use the `/_security/api_key` APIs.
- Basic: `Authorization: Basic <credentials>`
- Bearer: `Authorization: Bearer <token>`
  Elasticsearch APIs support the use of bearer tokens in the `Authorization` HTTP header to authenticate with the API.
  For examples, refer to [Token-based authentication services](https://www.elastic.co/guide/en/elasticsearch/reference/current/token-authentication-services.html)

## Query string parameters

- `ccs_minimize_roundtrips` (boolean · default: true) — optional
  If `true`, network round-trips are minimized for cross-cluster search requests.
- `max_concurrent_searches` (number) — optional
  The maximum number of concurrent searches the API can run.
- `search_type` (enum) — optional
  The type of the search operation.

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: `query_then_fetch`, `dfs_query_then_fetch`
- `rest_total_hits_as_int` (boolean · default: false) — optional
  If `true`, the response returns `hits.total` as an integer.
If `false`, it returns `hits.total` as an object.
- `typed_keys` (boolean · default: false) — optional
  If `true`, the response prefixes aggregation and suggester names with their respective types.

## Request body

`application/json`

An array; each item is one of:
- **{ allow_no_indices, expand_wildcards, ignore_unavailable, … }**
  Contains parameters used to limit or change the subsequent search body request.
  - `allow_no_indices` (boolean) — optional
  - `expand_wildcards` (string) — optional
    

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: `all`, `open`, `closed`, `hidden`, `none`
  - `ignore_unavailable` (boolean) — optional
  - `index` (string) — optional
  - `preference` (string) — optional
  - `request_cache` (boolean) — optional
  - `routing` (string) — optional
  - `search_type` (enum) — optional
    

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: `query_then_fetch`, `dfs_query_then_fetch`
  - `ccs_minimize_roundtrips` (boolean) — optional
  - `allow_partial_search_results` (boolean) — optional
  - `ignore_throttled` (boolean) — optional
- **{ explain, id, params, … }**
  - `explain` (boolean · default: false) — optional
    If `true`, returns detailed information about score calculation as part of each hit.
  - `id` (string) — optional
    The ID of the search template to use. If no `source` is specified,
this parameter is required.
  - `params` (map string to object) — optional
    Key-value pairs used to replace Mustache variables in the template.
The key is the variable name.
The value is the variable value.
  - `profile` (boolean · default: false) — optional
    If `true`, the query execution is profiled.
  - `source` (string) — optional
    An inline search template. Supports the same parameters as the search API's
request body. It also supports Mustache variables. If no `id` is specified, this
parameter is required.

## Response

`application/json`

- `took` (number)
- `responses` (union oneOf[])
  - **{ took, timed_out, _shards, … }**
    - `took` (number)
      The number of milliseconds it took Elasticsearch to run the request.
This value is calculated by measuring the time elapsed between receipt of a request on the coordinating node and the time at which the coordinating node is ready to send the response.
It includes:

* Communication time between the coordinating node and data nodes
* Time the request spends in the search thread pool, queued for execution
* Actual run time

It does not include:

* Time needed to send the request to Elasticsearch
* Time needed to serialize the JSON response
* Time needed to send the response to a client
    - `timed_out` (boolean)
      If `true`, the request timed out before completion; returned results may be partial or empty.
    - `_shards` (object)
      A count of shards used for the request.
      - `failed` (number)
        The number of shards the operation or search attempted to run on but failed.
      - `successful` (number)
        The number of shards the operation or search succeeded on.
      - `total` (number)
        The number of shards the operation or search will run on overall.
      - `failures` (object[])
        - `index` (string)
        - `node` (string)
        - `reason` (object)
          - `type` (string)
            The type of error
          - `reason` (union string) — nullable
            A human-readable explanation of the error, in English.
            One of: `string`
          - `stack_trace` (string)
            The server stack trace. Present only if the `error_trace=true` parameter was sent with the request.
          - `caused_by` (object) — recursive
            Same fields as `reason` in `failures`
          - `root_cause` (object[]) — recursive
            Same fields as `reason` in `failures`
          - `suppressed` (object[]) — recursive
            Same fields as `reason` in `failures`
        - `shard` (number)
        - `status` (string)
        - `primary` (boolean)
      - `skipped` (number)
    - `hits` (object)
      The returned documents and metadata.
      - `total` (union oneOf)
        Total hit count information, present only if `track_total_hits` wasn't `false` in the search request.
        - **{ relation, value }**
          - `relation` (enum)
            

Supported values include:
  - `eq`: Accurate
  - `gte`: Lower bound, including returned events or sequences
            Values: `eq`, `gte`
          - `value` (number)
        - **number**
      - `hits` (object[])
        - `_index` (string)
        - `_id` (string)
        - `_score` (union number | string) — nullable
        - `_explanation` (object)
          - `description` (string)
          - `details` (object[])
            - `description` (string)
            - `details` (object[]) — recursive
              Same fields as `details` in `_explanation`
            - `value` (number)
          - `value` (number)
        - `fields` (map string to object)
        - `highlight` (map string to string)
        - `inner_hits` (map string to object)
          Map values (object)
          - `hits` (object) — recursive
            Same fields as `hits` in `{ took, timed_out, _shards, … }`
        - `matched_queries` (union oneOf)
          One of: `string[]` or `string to number`
        - `_nested` (object)
          - `field` (string)
          - `offset` (number)
          - `_nested` (object) — recursive
            Same fields as `_nested` in `hits`
        - `_ignored` (string[])
        - `ignored_field_values` (map string to oneOf)
        - `_shard` (string)
        - `_node` (string)
        - `_routing` (string)
        - `_source` (object)
        - `_rank` (number)
        - `_seq_no` (number)
        - `_primary_term` (number)
        - `_version` (number)
        - `sort` (union[])
      - `max_score` (union number | string) — nullable
    - `aggregations` (map string to {} Aggregation result)
      See [Aggregation result](https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch/v8/types/_types-aggregations-aggregate)
    - `_clusters` (object)
      - `skipped` (number)
      - `successful` (number)
      - `total` (number)
      - `running` (number)
      - `partial` (number)
      - `failed` (number)
      - `details` (map string to object)
        Map values (object)
        - `status` (enum)
          Values: `running`, `successful`, `partial`, `skipped`, `failed`
        - `indices` (string)
        - `took` (number)
        - `timed_out` (boolean)
        - `_shards` (object)
          Same fields as `_shards` in `{ took, timed_out, _shards, … }`
        - `failures` (object[])
          Same fields as `failures` in `_shards`
    - `fields` (map string to object)
    - `max_score` (number)
    - `num_reduce_phases` (number)
    - `profile` (object)
      - `shards` (object[])
        - `aggregations` (object[])
          - `breakdown` (object)
            - `build_aggregation` (number)
            - `build_aggregation_count` (number)
            - `build_leaf_collector` (number)
            - `build_leaf_collector_count` (number)
            - `collect` (number)
            - `collect_count` (number)
            - `initialize` (number)
            - `initialize_count` (number)
            - `post_collection` (number)
            - `post_collection_count` (number)
            - `reduce` (number)
            - `reduce_count` (number)
          - `description` (string)
          - `time_in_nanos` (number)
          - `type` (string)
          - `debug` (object)
            - `segments_with_multi_valued_ords` (number)
            - `collection_strategy` (string)
            - `segments_with_single_valued_ords` (number)
            - `total_buckets` (number)
            - `built_buckets` (number)
            - `result_strategy` (string)
            - `has_filter` (boolean)
            - `delegate` (string)
            - `delegate_debug` (object) — recursive
              Same fields as `debug` in `aggregations`
            - `chars_fetched` (number)
            - `extract_count` (number)
            - `extract_ns` (number)
            - `values_fetched` (number)
            - `collect_analyzed_ns` (number)
            - `collect_analyzed_count` (number)
            - `surviving_buckets` (number)
            - `ordinals_collectors_used` (number)
            - `ordinals_collectors_overhead_too_high` (number)
            - `string_hashing_collectors_used` (number)
            - `numeric_collectors_used` (number)
            - `empty_collectors_used` (number)
            - `deferred_aggregators` (string[])
            - `segments_with_doc_count_field` (number)
            - `segments_with_deleted_docs` (number)
            - `filters` (object[])
              - `results_from_metadata` (number)
              - `query` (string)
              - `specialized_for` (string)
              - `segments_counted_in_constant_time` (number)
            - `segments_counted` (number)
            - `segments_collected` (number)
            - `map_reducer` (string)
            - `brute_force_used` (number)
            - `dynamic_pruning_attempted` (number)
            - `dynamic_pruning_used` (number)
            - `skipped_due_to_no_data` (number)
          - `children` (object[]) — recursive
            Same fields as `aggregations` in `shards`
        - `cluster` (string)
        - `dfs` (object)
          - `statistics` (object)
            - `type` (string)
            - `description` (string)
            - `time` (string)
            - `time_in_nanos` (number)
            - `breakdown` (object)
              - `collection_statistics` (number)
              - `collection_statistics_count` (number)
              - `create_weight` (number)
              - `create_weight_count` (number)
              - `rewrite` (number)
              - `rewrite_count` (number)
              - `term_statistics` (number)
              - `term_statistics_count` (number)
            - `debug` (map string to object)
            - `children` (object[]) — recursive
              Same fields as `statistics` in `dfs`
          - `knn` (object[])
            - `vector_operations_count` (number)
            - `query` (object[])
              - `type` (string)
              - `description` (string)
              - `time` (string)
              - `time_in_nanos` (number)
              - `breakdown` (object)
                - `advance` (number)
                - `advance_count` (number)
                - `build_scorer` (number)
                - `build_scorer_count` (number)
                - `compute_max_score` (number)
                - `compute_max_score_count` (number)
                - `count_weight` (number)
                - `count_weight_count` (number)
                - `create_weight` (number)
                - `create_weight_count` (number)
                - `match` (number)
                - `match_count` (number)
                - `next_doc` (number)
                - `next_doc_count` (number)
                - `score` (number)
                - `score_count` (number)
                - `set_min_competitive_score` (number)
                - `set_min_competitive_score_count` (number)
                - `shallow_advance` (number)
                - `shallow_advance_count` (number)
              - `debug` (map string to object)
              - `children` (object[]) — recursive
                Same fields as `query` in `knn`
            - `rewrite_time` (number)
            - `collector` (object[])
              - `name` (string)
              - `reason` (string)
              - `time` (string)
              - `time_in_nanos` (number)
              - `children` (object[]) — recursive
                Same fields as `collector` in `knn`
        - `fetch` (object)
          - `type` (string)
          - `description` (string)
          - `time_in_nanos` (number)
          - `breakdown` (object)
            - `load_source` (number)
            - `load_source_count` (number)
            - `load_stored_fields` (number)
            - `load_stored_fields_count` (number)
            - `next_reader` (number)
            - `next_reader_count` (number)
            - `process_count` (number)
            - `process` (number)
          - `debug` (object)
            - `stored_fields` (string[])
            - `fast_path` (number)
          - `children` (object[]) — recursive
            Same fields as `fetch` in `shards`
        - `id` (string)
        - `index` (string)
        - `node_id` (string)
        - `searches` (object[])
          - `collector` (object[])
            - `name` (string)
            - `reason` (string)
            - `time_in_nanos` (number)
            - `children` (object[]) — recursive
              Same fields as `collector` in `searches`
          - `query` (object[])
            - `breakdown` (object)
              - `advance` (number)
              - `advance_count` (number)
              - `build_scorer` (number)
              - `build_scorer_count` (number)
              - `create_weight` (number)
              - `create_weight_count` (number)
              - `match` (number)
              - `match_count` (number)
              - `shallow_advance` (number)
              - `shallow_advance_count` (number)
              - `next_doc` (number)
              - `next_doc_count` (number)
              - `score` (number)
              - `score_count` (number)
              - `compute_max_score` (number)
              - `compute_max_score_count` (number)
              - `count_weight` (number)
              - `count_weight_count` (number)
              - `set_min_competitive_score` (number)
              - `set_min_competitive_score_count` (number)
            - `description` (string)
            - `time_in_nanos` (number)
            - `type` (string)
            - `children` (object[]) — recursive
              Same fields as `query` in `searches`
          - `rewrite_time` (number)
        - `shard_id` (number)
    - `pit_id` (string)
    - `_scroll_id` (string)
      The identifier for the search and its search context.
You can use this scroll ID with the scroll API to retrieve the next batch of search results for the request.
This property is returned only if the `scroll` query parameter is specified in the request.
    - `suggest` (map string to oneOf)
    - `terminated_early` (boolean)
    - `status` (number)
  - **{ error }**
    The response returned by Elasticsearch when request execution did not succeed.
    - `error` (object)
      - `type` (string)
        The type of error
      - `reason` (union string) — nullable
        A human-readable explanation of the error, in English.
        One of: `string`
      - `stack_trace` (string)
        The server stack trace. Present only if the `error_trace=true` parameter was sent with the request.
      - `caused_by` (object) — recursive
        Same fields as `error` in `{ error }`
      - `root_cause` (object[]) — recursive
        Same fields as `error` in `{ error }`
      - `suppressed` (object[]) — recursive
        Same fields as `error` in `{ error }`
    - `status` (number)
## Code examples

#### Console

```console
POST my-index/_msearch/template
{ }
{ "id": "my-search-template", "params": { "query_string": "hello world", "from": 0, "size": 10 }}
{ }
{ "id": "my-other-search-template", "params": { "query_type": "match_all" }}
```

#### JavaScript

```javascript
const response = await client.msearchTemplate({
  index: "my-index",
  search_templates: [
    {},
    {
      id: "my-search-template",
      params: {
        query_string: "hello world",
        from: 0,
        size: 10,
      },
    },
    {},
    {
      id: "my-other-search-template",
      params: {
        query_type: "match_all",
      },
    },
  ],
});
```

#### Python

```python
resp = client.msearch_template(
    index="my-index",
    search_templates=[
        {},
        {
            "id": "my-search-template",
            "params": {
                "query_string": "hello world",
                "from": 0,
                "size": 10
            }
        },
        {},
        {
            "id": "my-other-search-template",
            "params": {
                "query_type": "match_all"
            }
        }
    ],
)
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/my-index/_msearch/template" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/x-ndjson" \
  -d $'{}\n{"id":"my-search-template","params":{"query_string":"hello \
  world","from":0,"size":10}}\n{}\n{"id":"my-other-search-template","params":{"query_type":"match_all"}}\n'
```

#### C#

```c#
var response = await client
    .MultiSearchTemplateAsync<MyDocument>(d1 => d1
        .Indices(new[] { "my-index" })
        .SearchTemplates([new SearchTemplateRequestItem(new MultisearchHeader(), new TemplateConfig()
        {
            Id = "my-search-template",
            Params = new Dictionary<string, object>()
            {
                { "query_string", "hello world" },
                { "from", 0 },
                { "size", 10 }
            }
        }), new SearchTemplateRequestItem(new MultisearchHeader(), new TemplateConfig()
        {
            Id = "my-other-search-template",
            Params = new Dictionary<string, object>()
            {
                { "query_type", "match_all" }
            }
        })])
    );
```

#### PHP

```php
$resp = $client->msearchTemplate([
    "index" => "my-index",
    "body" => array(
        new ArrayObject([]),
        [
            "id" => "my-search-template",
            "params" => [
                "query_string" => "hello world",
                "from" => 0,
                "size" => 10,
            ],
        ],
        new ArrayObject([]),
        [
            "id" => "my-other-search-template",
            "params" => [
                "query_type" => "match_all",
            ],
        ],
    ),
]);
```

#### Ruby

```ruby
response = client.msearch_template(
  index: "my-index",
  body: [
    {},
    {
      "id": "my-search-template",
      "params": {
        "query_string": "hello world",
        "from": 0,
        "size": 10
      }
    },
    {},
    {
      "id": "my-other-search-template",
      "params": {
        "query_type": "match_all"
      }
    }
  ]
)
```