---
title: "Get Documents by ID"
description: "Use this endpoint with the GET* method to retrieve documents from the database according to their document IDs:"
url: "https://docs.ravendb.net/6.2/client-api/rest-api/document-commands/get-documents-by-id"
version: "6.2"
---

# Get Documents by ID

> RavenDB publishes an official agent skill for coding assistants at https://docs.ravendb.net/skills/ravendb/SKILL.md (also installable with `npx skills add ravendb/skills`). The skill describes itself as: "Read this before writing any RavenDB query, client call or /databases/ request. Covers server setup, document modelling, the Node.js, .NET and Python clients, RQL, indexes, vector search and AI agents. Code written from recall tends to run and return the wrong rows, because RQL resembles SQL and the clients take field names as plain strings."

## Get Documents by ID

> **Note**
>
> - Use this endpoint with the **`GET`** method to retrieve documents from the database according to their document IDs:  
>   `<server URL>/databases/<database name>/docs?id=<document ID>`
>
> - Query parameters can be used to include [related documents](https://docs.ravendb.net/6.2/client-api/how-to/handle-document-relationships.md#includes) and
>   [counters](https://docs.ravendb.net/6.2/document-extensions/counters/overview.md).
>
> - In this page:
>   - [Basic Example](#basic-example)
>   - [Request Format](#request-format)
>   - [Response Format](#response-format)
>   - [More Examples](#more-examples)
>     - [Get Multiple Documents](#get-multiple-documents)
>     - [Get Related Documents](#get-related-documents)
>     - [Get Document Metadata Only](#get-document-metadata-only)
>     - [Get Document Counters](#get-document-counters)

## Basic Example

This is a cURL request to retrieve one document named "products/48-A" from a database named "Example" on our
[playground server](http://live-test.ravendb.net):

```bash
curl -X GET "http://live-test.ravendb.net/databases/Example/docs?id=products/48-A"
```

Response:

```http
HTTP/1.1 200 OK
Server: nginx
Date: Tue, 10 Sep 2019 10:33:04 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
ETag: "A:285-k50KTOC5G0mfVXKjomTNFQ"
Vary: Accept-Encoding
Raven-Server-Version: 4.2.4.42

{
  "Results": [
      {
          "Name": "Chocolade",
          "Supplier": "suppliers/22-A",
          "Category": "categories/3-A",
          "QuantityPerUnit": "10 pkgs.",
          "PricePerUnit": 12.7500,
          "UnitsInStock": 22,
          "UnitsOnOrder": 15,
          "Discontinued": false,
          "ReorderLevel": 25,
          "@metadata": {
              "@collection": "Products",
              "@change-vector": "A:285-k50KTOC5G0mfVXKjomTNFQ",
              "@id": "products/48-A",
              "@last-modified": "2018-07-27T12:11:53.0300420Z"
          }
      }
  ],
  "Includes": {}
}
```

## Request Format

This is the general format of a cURL request that uses all parameters:

```text
curl -X GET "<server URL>/databases/<database name>/docs?
          id=<document ID>
          &include=<path>
          &counter=<counter name>
          &metadataOnly=<boolean>"
--header "If-None-Match:<hash>"
```

Linebreaks are added for clarity.

#### Query String Parameters

| Parameter | Description | Required / # |
| - | - | - |
| **id** | ID of a document to retrieve. <br /> If no IDs are specified, all the documents in the database are retrieved in descending order of their [change vectors](https://docs.ravendb.net/6.2/server/clustering/replication/change-vector.md). | Yes; <br /> Can be used more than once |
| **include** | Path to a field containing the ID of another, 'related' document. [See: How to Handle Document Relationships](https://docs.ravendb.net/6.2/client-api/how-to/handle-document-relationships.md#includes). | No; <br /> Can be used more than once |
| **counter** | Name of a [counter](https://docs.ravendb.net/6.2/document-extensions/counters/overview.md) to retrieve. Set this parameter to `@all_counters` to retrieve all counters of the specified documents. Counters of *included* documents, however, will not be retrieved. | No; <br /> Can be used more than once |
| **metadataOnly** | Set this parameter to `true` to retrieve only the metadata of each document. This does not apply to included documents which are retrieved with their complete contents. | No; <br /> Used once |

#### Headers

| Header | Description | Required |
| - | - | - |
| **If-None-Match** | This header takes a hash representing the previous results of an **identical** request. The hash is found in the response header `ETag`. If the results were not modified since the previous request, the server responds with http status code `304` and the requested documents are retrieved from a local cache rather than over the network. | No |

## Response Format

#### Http Status Codes

| Code | Description |
| - | - |
| `200` | Results are successfully retrieved. If a requested document could not be found, the result returned is `null`. |
| `304` | In response to an `If-None-Match` check: none of the requested documents were modified since they were last loaded, so they were not retrieved from the server. |
| `404` | No document with the specified ID was found. This code is only sent when *one* document was requested. Otherwise, see status code `200`. |

#### Headers

| Header | Description |
| - | - |
| **Content-Type** | MIME media type and character encoding. This should always be: `application/json; charset=utf-8`. |
| **ETag** | Hash representing the state of these results. If another, **identical** request is made, this hash can be sent in the `If-None-Match` header to check whether the retrieved documents have been modified since the last response. If none were modified, they are not retrieved. |
| **Raven-Server-Version** | Version of RavenDB that the responding server is running. |

#### Body

A retrieved document is identical in contents and format to the document stored on the server (unless the `metadataOnly`
parameter is set to `true`).

This is the general JSON format of the response body:

```javascript
{
  "Results": [ 
      { 
          <document contents>
      },
      { },
      ...
  ],
  "Includes":
      "<document ID>": {
          <document contents>
      },
      "<document ID>": { },
      ...
  }
  "CounterIncludes": {
      "<document ID>": [
          {
              "DocumentId": "<document ID>",
              "CounterName": "<counter name>",
              "TotalValue": <integer>
          },
          { },
          ...
      ],
      "<document ID>": [ ],
      ...
  }
}
```

Linebreaks are added for clarity.

## More Examples

[About Northwind](https://docs.ravendb.net/6.2/start/about-examples.md), the database used in our examples.

In this section:

- [Get Multiple Documents](#get-multiple-documents)
- [Get Related Documents](#get-related-documents)
- [Get Document Metadata Only](#get-document-metadata-only)
- [Get Document Counters](#get-document-counters)

### Get Multiple Documents

Example cURL request:

```bash
curl -X GET "http://live-test.ravendb.net/databases/Example/docs?
          id=shippers/1-A
          &id=shippers/2-A"
```

Linebreaks are added for clarity.

Response:

```http
HTTP/1.1 200 OK
Server: nginx
Date: Thu, 12 Sep 2019 09:23:49 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
ETag: "Hash-auWLG9xq3imTfRdJvlKIL32LhEM0IwJ20eiibWse0X8="
Vary: Accept-Encoding
Raven-Server-Version: 4.2.4.42

{
  "Results": [
      {
          "Name": "Speedy Express",
          "Phone": "(503) 555-9831",
          "@metadata": {
              "@collection": "Shippers",
              "@change-vector": "A:349-k50KTOC5G0mfVXKjomTNFQ",
              "@id": "shippers/1-A",
              "@last-modified": "2018-07-27T12:11:53.0317375Z"
          }
      },
      {
          "Name": "United Package",
          "Phone": "(503) 555-3199",
          "@metadata": {
              "@collection": "Shippers",
              "@change-vector": "A:351-k50KTOC5G0mfVXKjomTNFQ",
              "@id": "shippers/2-A",
              "@last-modified": "2018-07-27T12:11:53.0317596Z"
          }
      }
  ],
  "Includes": {}
}
```

### Get Related Documents

Example cURL request:

```bash
curl -X GET "http://live-test.ravendb.net/databases/Demo/docs?
          id=products/48-A
          &include=Supplier
          &include=Category"
```

Linebreaks are added for clarity.

Response:

```http
HTTP/1.1 200 OK
Server: nginx
Date: Tue, 10 Sep 2019 10:40:27 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
ETag: "Hash-9oK1ZcWmNa9SD9hP8m0vT355ztQuFnF/vKD5ILyI/KY="
Vary: Accept-Encoding
Raven-Server-Version: 4.2.4.42

{
  "Results": [
      {
          "Name": "Chocolade",
          "Supplier": "suppliers/22-A",
          "Category": "categories/3-A",
          "QuantityPerUnit": "10 pkgs.",
          "PricePerUnit": 12.7500,
          "UnitsInStock": 22,
          "UnitsOnOrder": 15,
          "Discontinued": false,
          "ReorderLevel": 25,
          "@metadata": {
              "@collection": "Products",
              "@change-vector": "A:285-k50KTOC5G0mfVXKjomTNFQ",
              "@id": "products/48-A",
              "@last-modified": "2018-07-27T12:11:53.0300420Z"
          }
      }
  ],
  "Includes": {
      "suppliers/22-A": {
          "Contact": {
              "Name": "Dirk Luchte",
              "Title": "Accounting Manager"
          },
          "Name": "Zaanse Snoepfabriek",
          "Address": {
              "Line1": "Verkoop Rijnweg 22",
              "Line2": null,
              "City": "Zaandam",
              "Region": null,
              "PostalCode": "9999 ZZ",
              "Country": "Netherlands",
              "Location": null
          },
          "Phone": "(12345) 1212",
          "Fax": "(12345) 1210",
          "HomePage": null,
          "@metadata": {
              "@collection": "Suppliers",
              "@change-vector": "A:399-k50KTOC5G0mfVXKjomTNFQ",
              "@id": "suppliers/22-A",
              "@last-modified": "2018-07-27T12:11:53.0335729Z"
          }
      },
      "categories/3-A": {
          "Name": "Confections",
          "Description": "Desserts, candies, and sweet breads",
          "@metadata": {
              "@attachments": [
                  {
                      "Name": "image.jpg",
                      "Hash": "1QxSMa3tBr+y8wQYNre7E9UJFFVTNWGjVoC+IC+gSSs=",
                      "ContentType": "image/jpeg",
                      "Size": 47955
                  }
              ],
              "@collection": "Categories",
              "@change-vector": "A:2092-k50KTOC5G0mfVXKjomTNFQ",
              "@flags": "HasAttachments",
              "@id": "categories/3-A",
              "@last-modified": "2018-07-27T12:16:44.1738714Z"
          }
      }
  }
}
```

### Get Document Metadata Only

Example cURL request:

```bash
curl -X GET "http://live-test.ravendb.net/databases/Example/docs?
          id=orders/19-A
          &metadataOnly=true"
```

Linebreaks are added for clarity.

Response:

```http
HTTP/1.1 200 OK
Server: nginx
Date: Tue, 10 Sep 2019 10:52:28 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
ETag: "A:453-k50KTOC5G0mfVXKjomTNFQ"
Vary: Accept-Encoding
Raven-Server-Version: 4.2.4.42

{
  "Results": [
      {
          "@metadata": {
              "@collection": "Orders",
              "@change-vector": "A:453-k50KTOC5G0mfVXKjomTNFQ",
              "@flags": "HasRevisions",
              "@id": "orders/19-A",
              "@last-modified": "2018-07-27T12:11:53.0476121Z"
          }
      }
  ],
  "Includes": {}
}
```

### Get Document Counters

Example cURL request:

```bash
curl -X GET "http://live-test.ravendb.net/databases/Example/docs?
          id=products/48-A
          &counter=MoLtUaE"
```

Linebreaks are added for clarity.

Response:

```http
HTTP/1.1 200 OK
Server: nginx
Date: Tue, 10 Sep 2019 12:26:04 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
ETag: "A:5957-k50KTOC5G0mfVXKjomTNFQ"
Vary: Accept-Encoding
Raven-Server-Version: 4.2.4.42

{
  "Results": [
      {
          "Name": "Chocolade",
          "Supplier": "suppliers/22-A",
          "Category": "categories/3-A",
          "QuantityPerUnit": "10 pkgs.",
          "PricePerUnit": 12.7500,
          "UnitsInStock": 22,
          "UnitsOnOrder": 15,
          "Discontinued": false,
          "ReorderLevel": 25,
          "@metadata": {
              "@collection": "Products",
              "@counters": [
                  "#OfCounters",
                  "MoLtUaE"
              ],
              "@change-vector": "A:285-k50KTOC5G0mfVXKjomTNFQ",
              "@id": "products/48-A",
              "@flags": "HasRevisions, HasCounters",
              "@last-modified": "2019-09-10T12:25:44.1759382Z"
          }
      }
  ],
  "Includes": {},
  "CounterIncludes": {
      "orders/19-A": [
          {
              "DocumentId": "orders/19-A",
              "CounterName": "MoLtUaE",
              "TotalValue": 42
          }
      ]
  }
}
```

(Note that the standard [Northwind data](https://docs.ravendb.net/6.2/start/about-examples.md) does not contain any [counters](https://docs.ravendb.net/6.2/document-extensions/counters/overview.md)
when it is [generated in the studio](https://docs.ravendb.net/6.2/studio/database/document-extensions/counters.md) - counters were added to "products/48-A" for this example)
