---
type: api
title: Get multiple documents
description: **All methods and paths for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch-serverless/operation/operation-mget
resource: https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch-serverless/operation/operation-mget
products:
  - Elasticsearch Serverless
---

# Get multiple documents

Authentication: required

## Paths

- `POST` (also `GET`) `/{index}/_mget`
- `POST` (also `GET`) `/_mget`

#### Path parameters

- `index` (string) — optional, leave it out to use `/_mget`
  Name of the index to retrieve documents from when `ids` are specified, or when a document in the `docs` array does not specify an index.

## Description

Get multiple JSON documents by ID from one or more indices.
If you specify an index in the request URI, you only need to specify the document IDs in the request body.
To ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.

**Filter source fields**

By default, the `_source` field is returned for every document (if stored).
Use the `_source` and `_source_include` or `source_exclude` attributes to filter what fields are returned for a particular document.
You can include the `_source`, `_source_includes`, and `_source_excludes` query parameters in the request URI to specify the defaults to use when there are no per-document instructions.

**Get stored fields**

Use the `stored_fields` attribute to specify the set of stored fields you want to retrieve.
Any requested fields that are not stored are ignored.
You can include the `stored_fields` query parameter in the request URI to specify the defaults to use when there are no per-document instructions.

## Required authorization

- Index privileges: `read`

## Query string parameters

- `preference` (string) — optional
  Specifies the node or shard the operation should be performed on. Random by default.
- `realtime` (boolean · default: true) — optional
  If `true`, the request is real-time as opposed to near-real-time.
- `refresh` (boolean · default: false) — optional
  If `true`, the request refreshes relevant shards before retrieving documents.
- `routing` (union string | string[]) — optional
  Custom value used to route operations to a specific shard.
Not allowed when `index.slice.enabled` is `true` for the target index; use `_slice` instead.
- `_source` (union oneOf) — optional
  True or false to return the `_source` field or not, or a list of fields to return.
  One of: `boolean` or `string`
- `_source_excludes` (union string | string[]) — optional
  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.
- `_source_includes` (union string | string[]) — optional
  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.
- `stored_fields` (union oneOf · default: false) — optional
  If `true`, retrieves the document fields stored in the index rather than the document `_source`.
  One of: `string[]` or `string`

## Request body

`application/json`

- `docs` (object[]) — optional
  The documents you want to retrieve. Required if no index is specified in the request URI.
  - `_id` (string) — required
    The unique document ID.
  - `_index` (string) — optional
    The index that contains the document.
  - `routing` (union oneOf) — optional
    The key for the primary shard the document resides on. Required if routing is used during indexing.
    One of: `string[]` or `string`
  - `_source` (union oneOf) — optional
    If `false`, excludes all _source fields.
    - **boolean**
    - **SourceFilter**
      - `exclude_vectors` (boolean) — optional
        If `true`, vector fields are excluded from the returned source.

This option takes precedence over `includes`: any vector field will
remain excluded even if it matches an `includes` rule.
      - `excludes` (union oneOf) — optional
        A list of fields to exclude from the returned source.
        One of: `string[]` or `string`
      - `includes` (union oneOf) — optional
        A list of fields to include in the returned source.
        One of: `string[]` or `string`
  - `stored_fields` (union oneOf) — optional
    The stored fields you want to retrieve.
    One of: `string[]` or `string`
  - `version` (number) — optional
  - `version_type` (enum) — optional
    

Supported values include:
  - `internal`: Use internal versioning that starts at 1 and increments with each update or delete.
  - `external`: Only index the document if the specified version is strictly higher than the version of the stored document or if there is no existing document.
  - `external_gte`: Only index the document if the specified version is equal or higher than the version of the stored document or if there is no existing document.
NOTE: The `external_gte` version type is meant for special use cases and should be used with care.
If used incorrectly, it can result in loss of data.
    Values: `internal`, `external`, `external_gte`
- `ids` (union oneOf) — optional
  The IDs of the documents you want to retrieve. Allowed when the index is specified in the request URI.
  One of: `string[]` or `string`

## Response

`application/json`

- `docs` (union oneOf[])
  The response includes a docs array that contains the documents in the order specified in the request.
The structure of the returned documents is similar to that returned by the get API.
If there is a failure getting a particular document, the error is included in place of the document.
  - **GetResult**
    - `_index` (string)
      The name of the index the document belongs to.
    - `fields` (map string to object)
      If the `stored_fields` parameter is set to `true` and `found` is `true`, it contains the document fields stored in the index.
    - `_ignored` (string[])
    - `found` (boolean)
      Indicates whether the document exists.
    - `_id` (string)
      The unique identifier for the document.
    - `_primary_term` (number)
      The primary term assigned to the document for the indexing operation.
    - `_routing` (string)
      The explicit routing, if set.
    - `_seq_no` (number)
      The sequence number assigned to the document for the indexing operation.
Sequence numbers are used to ensure an older version of a document doesn't overwrite a newer version.
    - `_source` (object)
      If `found` is `true`, it contains the document data formatted in JSON.
If the `_source` parameter is set to `false` or the `stored_fields` parameter is set to `true`, it is excluded.
    - `_version` (number)
      The document version, which is ncremented each time the document is updated.
  - **MultiGetError**
    - `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 `MultiGetError`
      - `root_cause` (object[]) — recursive
        Same fields as `error` in `MultiGetError`
      - `suppressed` (object[]) — recursive
        Same fields as `error` in `MultiGetError`
    - `_id` (string)
    - `_index` (string)
## Code examples

### Get documents by ID

#### Console

```console
POST /my-index-000001/_mget
{
  "docs": [
    {
      "_id": "1"
    },
    {
      "_id": "2"
    }
  ]
}
```

#### JavaScript

```javascript
const response = await client.mget({
  index: "my-index-000001",
  docs: [
    {
      _id: "1",
    },
    {
      _id: "2",
    },
  ],
});
```

#### Python

```python
resp = client.mget(
    index="my-index-000001",
    docs=[
        {
            "_id": "1"
        },
        {
            "_id": "2"
        }
    ],
)
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/my-index-000001/_mget" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "docs": [
      {
        "_id": "1"
      },
      {
        "_id": "2"
      }
    ]
  }'
```

#### Java

```java
client.mget(m -> m
    .docs(List.of(MultiGetOperation.of(mu -> mu
            .id("1")
        ),MultiGetOperation.of(mu -> mu
            .id("2")
        )))
    .index("my-index-000001")
);
```

#### C#

```c#
var response = await client
    .MultiGetAsync<MyDocument>(d1 => d1
        .Index("my-index-000001")
        .Docs(d2 => d2
            .Id("1"), d2 => d2
            .Id("2")
        )
    );
```

#### PHP

```php
$resp = $client->mget([
    "index" => "my-index-000001",
    "body" => [
        "docs" => array(
            [
                "_id" => "1",
            ],
            [
                "_id" => "2",
            ],
        ),
    ],
]);
```

#### Ruby

```ruby
response = client.mget(
  index: "my-index-000001",
  body: {
    "docs": [
      {
        "_id": "1"
      },
      {
        "_id": "2"
      }
    ]
  }
)
```

### Filter source fields

#### Console

```console
POST /_mget
{
  "docs": [
    {
      "_index": "test",
      "_id": "1",
      "_source": false
    },
    {
      "_index": "test",
      "_id": "2",
      "_source": [ "field3", "field4" ]
    },
    {
      "_index": "test",
      "_id": "3",
      "_source": {
        "include": [ "user" ],
        "exclude": [ "user.location" ]
      }
    }
  ]
}
```

#### JavaScript

```javascript
const response = await client.mget({
  docs: [
    {
      _index: "test",
      _id: "1",
      _source: false,
    },
    {
      _index: "test",
      _id: "2",
      _source: ["field3", "field4"],
    },
    {
      _index: "test",
      _id: "3",
      _source: {
        include: ["user"],
        exclude: ["user.location"],
      },
    },
  ],
});
```

#### Python

```python
resp = client.mget(
    docs=[
        {
            "_index": "test",
            "_id": "1",
            "_source": False
        },
        {
            "_index": "test",
            "_id": "2",
            "_source": [
                "field3",
                "field4"
            ]
        },
        {
            "_index": "test",
            "_id": "3",
            "_source": {
                "include": [
                    "user"
                ],
                "exclude": [
                    "user.location"
                ]
            }
        }
    ],
)
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/_mget" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "docs": [
      {
        "_index": "test",
        "_id": "1",
        "_source": false
      },
      {
        "_index": "test",
        "_id": "2",
        "_source": [
          "field3",
          "field4"
        ]
      },
      {
        "_index": "test",
        "_id": "3",
        "_source": {
          "include": [
            "user"
          ],
          "exclude": [
            "user.location"
          ]
        }
      }
    ]
  }'
```

#### Java

```java
client.mget(m -> m
    .docs(List.of(MultiGetOperation.of(mu -> mu
            .id("1")
            .index("test")
            .source(s -> s
                .fetch(false)
            )
        ),MultiGetOperation.of(mul -> mul
            .id("2")
            .index("test")
            .source(s -> s
                .filter(f -> f
                    .includes(List.of("field3","field4"))
                )
            )
        ),MultiGetOperation.of(mult -> mult
            .id("3")
            .index("test")
            .source(s -> s
                .filter(f -> f
                    .excludes("user.location")
                    .includes("user")
                )
            )
        )))
);
```

#### C#

```c#
var response = await client
    .MultiGetAsync<MyDocument>(d1 => d1
        .Docs(d2 => d2
            .Id("1")
            .Index("test")
            .Source(new SourceConfig(false)), d2 => d2
            .Id("2")
            .Index("test")
            .Source(new SourceConfig(new SourceFilter()
            {
                Includes = global::Elastic.Clients.Elasticsearch.Infer.Fields<MyDocument>(x => x.Field3, x => x.Field4)
            })), d2 => d2
            .Id("3")
            .Index("test")
            .Source(new SourceConfig(new SourceFilter()
            {
                Excludes = global::Elastic.Clients.Elasticsearch.Infer.Fields<MyDocument>(x => x.User.Location),
                Includes = global::Elastic.Clients.Elasticsearch.Infer.Fields<MyDocument>(x => x.User)
            }))
        )
    );
```

#### PHP

```php
$resp = $client->mget([
    "body" => [
        "docs" => array(
            [
                "_index" => "test",
                "_id" => "1",
                "_source" => false,
            ],
            [
                "_index" => "test",
                "_id" => "2",
                "_source" => array(
                    "field3",
                    "field4",
                ),
            ],
            [
                "_index" => "test",
                "_id" => "3",
                "_source" => [
                    "include" => array(
                        "user",
                    ),
                    "exclude" => array(
                        "user.location",
                    ),
                ],
            ],
        ),
    ],
]);
```

#### Ruby

```ruby
response = client.mget(
  body: {
    "docs": [
      {
        "_index": "test",
        "_id": "1",
        "_source": false
      },
      {
        "_index": "test",
        "_id": "2",
        "_source": [
          "field3",
          "field4"
        ]
      },
      {
        "_index": "test",
        "_id": "3",
        "_source": {
          "include": [
            "user"
          ],
          "exclude": [
            "user.location"
          ]
        }
      }
    ]
  }
)
```

### Get stored fields

#### Console

```console
POST /_mget
{
  "docs": [
    {
      "_index": "test",
      "_id": "1",
      "stored_fields": [ "field1", "field2" ]
    },
    {
      "_index": "test",
      "_id": "2",
      "stored_fields": [ "field3", "field4" ]
    }
  ]
}
```

#### JavaScript

```javascript
const response = await client.mget({
  docs: [
    {
      _index: "test",
      _id: "1",
      stored_fields: ["field1", "field2"],
    },
    {
      _index: "test",
      _id: "2",
      stored_fields: ["field3", "field4"],
    },
  ],
});
```

#### Python

```python
resp = client.mget(
    docs=[
        {
            "_index": "test",
            "_id": "1",
            "stored_fields": [
                "field1",
                "field2"
            ]
        },
        {
            "_index": "test",
            "_id": "2",
            "stored_fields": [
                "field3",
                "field4"
            ]
        }
    ],
)
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/_mget" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "docs": [
      {
        "_index": "test",
        "_id": "1",
        "stored_fields": [
          "field1",
          "field2"
        ]
      },
      {
        "_index": "test",
        "_id": "2",
        "stored_fields": [
          "field3",
          "field4"
        ]
      }
    ]
  }'
```

#### Java

```java
client.mget(m -> m
    .docs(List.of(MultiGetOperation.of(mu -> mu
            .id("1")
            .index("test")
            .storedFields(List.of("field1","field2"))
        ),MultiGetOperation.of(mu -> mu
            .id("2")
            .index("test")
            .storedFields(List.of("field3","field4"))
        )))
);
```

#### C#

```c#
var response = await client
    .MultiGetAsync<MyDocument>(d1 => d1
        .Docs(d2 => d2
            .Id("1")
            .Index("test")
            .StoredFields(x => x.Field1, x => x.Field2), d2 => d2
            .Id("2")
            .Index("test")
            .StoredFields(x => x.Field3, x => x.Field4)
        )
    );
```

#### PHP

```php
$resp = $client->mget([
    "body" => [
        "docs" => array(
            [
                "_index" => "test",
                "_id" => "1",
                "stored_fields" => array(
                    "field1",
                    "field2",
                ),
            ],
            [
                "_index" => "test",
                "_id" => "2",
                "stored_fields" => array(
                    "field3",
                    "field4",
                ),
            ],
        ),
    ],
]);
```

#### Ruby

```ruby
response = client.mget(
  body: {
    "docs": [
      {
        "_index": "test",
        "_id": "1",
        "stored_fields": [
          "field1",
          "field2"
        ]
      },
      {
        "_index": "test",
        "_id": "2",
        "stored_fields": [
          "field3",
          "field4"
        ]
      }
    ]
  }
)
```

### Document routing

#### Console

```console
POST /_mget?routing=key1
{
  "docs": [
    {
      "_index": "test",
      "_id": "1",
      "routing": "key2"
    },
    {
      "_index": "test",
      "_id": "2"
    }
  ]
}
```

#### JavaScript

```javascript
const response = await client.mget({
  routing: "key1",
  docs: [
    {
      _index: "test",
      _id: "1",
      routing: "key2",
    },
    {
      _index: "test",
      _id: "2",
    },
  ],
});
```

#### Python

```python
resp = client.mget(
    routing="key1",
    docs=[
        {
            "_index": "test",
            "_id": "1",
            "routing": "key2"
        },
        {
            "_index": "test",
            "_id": "2"
        }
    ],
)
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/_mget?routing=key1" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "docs": [
      {
        "_index": "test",
        "_id": "1",
        "routing": "key2"
      },
      {
        "_index": "test",
        "_id": "2"
      }
    ]
  }'
```

#### Java

```java
client.mget(m -> m
    .docs(List.of(MultiGetOperation.of(mu -> mu
            .id("1")
            .index("test")
            .routing("key2")
        ),MultiGetOperation.of(mu -> mu
            .id("2")
            .index("test")
        )))
    .routing("key1")
);
```

#### C#

```c#
var response = await client
    .MultiGetAsync<MyDocument>(d1 => d1
        .Routing("key1")
        .Docs(d2 => d2
            .Id("1")
            .Index("test")
            .Routing("key2"), d2 => d2
            .Id("2")
            .Index("test")
        )
    );
```

#### PHP

```php
$resp = $client->mget([
    "routing" => "key1",
    "body" => [
        "docs" => array(
            [
                "_index" => "test",
                "_id" => "1",
                "routing" => "key2",
            ],
            [
                "_index" => "test",
                "_id" => "2",
            ],
        ),
    ],
]);
```

#### Ruby

```ruby
response = client.mget(
  routing: "key1",
  body: {
    "docs": [
      {
        "_index": "test",
        "_id": "1",
        "routing": "key2"
      },
      {
        "_index": "test",
        "_id": "2"
      }
    ]
  }
)
```

## Response examples

#### 200

`application/json`

Generated from the API spec. Values are representative. Unions use the first variant; deeply nested or large bodies may omit fields.

```json
{
  "docs": [
    {
      "_index": "string",
      "fields": {
        "key": {}
      },
      "_ignored": [
        "string"
      ],
      "found": false,
      "_id": "string",
      "_primary_term": 0,
      "_routing": "string",
      "_seq_no": 0,
      "_source": {},
      "_version": 0
    }
  ]
}
```