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

# Get Documents by Prefix

> 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 Prefix

> **Note**
>
> - Use this endpoint with the **`GET`** method to retrieve documents from the database by a common prefix in their document IDs:  
>   `<server URL>/databases/<database name>/docs?startsWith=<document ID prefix>`
>
> - Query parameters can be used to filter and page the results.
>
> - In this page:
>   - [Basic Example](#basic-example)
>   - [Request Format](#request-format)
>   - [Response Format](#response-format)
>   - [More Examples](#more-examples)
>     - [Get Using `matches`](#get-using)
>     - [Get Using `matches` and `exclude`](#get-usingand)
>     - [Get Using `startAfter`](#get-using-1)
>     - [Page Results](#page-results)
>     - [Get Document Metadata Only](#get-document-metadata-only)

## Basic Example

This is a cURL request to retrieve all documents whose IDs begin with the prefix "ship" 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?startsWith=ship"
```

Response:

```http
HTTP/1.1 200 OK
Server: nginx
Date: Tue, 10 Sep 2019 15:25:34 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
ETag: "A:2137-pIhs+72n6USJoZ5XIvTHvQ"
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"
          }
      },
      {
          "Name": "Federal Shipping",
          "Phone": "(503) 555-9931",
          "@metadata": {
              "@collection": "Shippers",
              "@change-vector": "A:353-k50KTOC5G0mfVXKjomTNFQ",
              "@id": "shippers/3-A",
              "@last-modified": "2018-07-27T12:11:53.0317858Z"
          }
      }
  ]
}
```

## 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?
          startsWith=<prefix>
          &matches=<suffix>|<suffix>|...
          &exclude=<suffix>|<suffix>|...
          &startAfter=<document ID>
          &start=<integer>
          &pageSize=<integer>
          &metadataOnly=<boolean>"
--header "If-None-Match: <hash>"
```

Linebreaks are added for clarity.

#### Query String Parameters

| Parameter | Description | Required |
| - | - | - |
| **startsWith** | Retrieve all documents whose IDs begin with this string. If the value of this parameter is left empty, all documents in the database are retrieved. | Yes |
| **matches** | Retrieve documents whose IDs are exactly `<startsWith>`+`<matches>`. Accepts multiple values separated by a pipe character: ' \| ' . Use `?` to represent any single character, and `*` to represent any string. | No |
| **exclude** | *Exclude* documents whose IDs are exactly `<startsWith>`+`<exclude>`. Accepts multiple values separated by a pipe character: ' \| ' . Use `?` to represent any single character, and `*` to represent any string. | No |
| **startAfter** | Retrieve only the results after the first document ID that begins with this prefix. | No |
| **start** | Number of results to skip. | No |
| **pageSize** | Maximum number of results to retrieve. | No |
| **metadataOnly** | Set this parameter to `true` to retrieve only the document metadata from each result. | No |

#### 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 were successfully retrieved. If no documents with the specified prefix could be found, the results array is empty. |
| `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. |

#### 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. |
| **Raven-Server-Version** | Version of RavenDB that the responding server is running |

#### Body

Retrieved documents are sorted in ascending [lexical order](https://en.wikipedia.org/wiki/Lexicographical_order) of their
document IDs. A retrieved document is identical in contents and format to the document stored in the server - unless the
`metadataOnly` parameter is set to `true`.

This is the general JSON format of the response body:

```javascript
{
  "Results": [ 
      { 
          "<field>":"<value>",
          ...
          "@metadata":{
              ...
          }
      },
      { <document contents> },
      ...
  ]
}
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 Using `matches`](#get-using)
- [Get Using `matches` and `exclude`](#get-usingand)
- [Get Using `startAfter`](#get-using-1)
- [Page Results](#page-results)
- [Get Document Metadata Only](#get-document-metadata-only)

### Get Using `matches`

cURL request:

```bash
curl -X GET "http://live-test.ravendb.net/databases/Example/docs?
          startsWith=shipp
          &matches=ers/3-A|ers/1-A"
```

Linebreaks are added for clarity.

Response:

```http
HTTP/1.1 200 OK
Server: nginx
Date: Thu, 12 Sep 2019 10:57:58 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
ETag: "A:5972-k50KTOC5G0mfVXKjomTNFQ"
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": "Federal Shipping",
          "Phone": "(503) 555-9931",
          "@metadata": {
              "@collection": "Shippers",
              "@change-vector": "A:353-k50KTOC5G0mfVXKjomTNFQ",
              "@id": "shippers/3-A",
              "@last-modified": "2018-07-27T12:11:53.0317858Z"
          }
      }
  ]
}
```

### Get Using `matches` and `exclude`

cURL request:

```bash
curl -X GET "http://live-test.ravendb.net/databases/Example/docs?
          startsWith=shipp
          &matches=ers/3-A|ers/1-A
          &exclude=ers/3-A"
```

Linebreaks are added for clarity.

Response:

```http
HTTP/1.1 200 OK
Server: nginx
Date: Thu, 12 Sep 2019 12:24:50 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
ETag: "A:5972-k50KTOC5G0mfVXKjomTNFQ"
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"
          }
      }
  ]
}
```

### Get Using `startAfter`

cURL request:

```bash
curl -X GET "http://live-test.ravendb.net/databases/Example/docs?
          startsWith=shipp
          startAfter=shippers/1-A"
```

Linebreaks are added for clarity.

Response:

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

{
  "Results": [
      {
          "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"
          }
      },
      {
          "Name": "Federal Shipping",
          "Phone": "(503) 555-9931",
          "@metadata": {
              "@collection": "Shippers",
              "@change-vector": "A:353-k50KTOC5G0mfVXKjomTNFQ",
              "@id": "shippers/3-A",
              "@last-modified": "2018-07-27T12:11:53.0317858Z"
          }
      }
  ]
}
```

### Page Results

cURL request:

```bash
curl -X GET "http://live-test.ravendb.net/databases/Example/docs?
          startsWith=product
          &start=50
          &pageSize=2"
```

Linebreaks are added for clarity.

Response:

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

{
  "Results": [
      {
          "Name": "Pâté chinois",
          "Supplier": "suppliers/25-A",
          "Category": "categories/6-A",
          "QuantityPerUnit": "24 boxes x 2 pies",
          "PricePerUnit": 24.0000,
          "UnitsInStock": 25,
          "UnitsOnOrder": 115,
          "Discontinued": false,
          "ReorderLevel": 20,
          "@metadata": {
              "@collection": "Products",
              "@change-vector": "A:8170-k50KTOC5G0mfVXKjomTNFQ, A:1887-0N64iiIdYUKcO+yq1V0cPA, A:6214-xwmnvG1KBkSNXfl7/0yJ1A",
              "@id": "products/55-A",
              "@last-modified": "2018-07-27T12:11:53.0303784Z"
          }
      },
      {
          "Name": "Gnocchi di nonna Alice",
          "Supplier": "suppliers/26-A",
          "Category": "categories/5-A",
          "QuantityPerUnit": "24 - 250 g pkgs.",
          "PricePerUnit": 38.0000,
          "UnitsInStock": 26,
          "UnitsOnOrder": 21,
          "Discontinued": false,
          "ReorderLevel": 30,
          "@metadata": {
              "@collection": "Products",
              "@change-vector": "A:8172-k50KTOC5G0mfVXKjomTNFQ, A:1887-0N64iiIdYUKcO+yq1V0cPA, A:6214-xwmnvG1KBkSNXfl7/0yJ1A",
              "@id": "products/56-A",
              "@last-modified": "2018-07-27T12:11:53.0304385Z"
          }
      }
  ]
}
```

Note that the document ID numbers are 55 and 56 rather than the expected 51 and 52 because results are sorted in lexical order.

### Get Document Metadata Only

cURL request:

```bash
curl -X GET "http://live-test.ravendb.net/databases/Example/docs?
          startsWith=regio
          &metadataOnly=true"
```

Linebreaks are added for clarity.

Response:

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

{
  "Results": [
      {
          "@metadata": {
              "@collection": "Regions",
              "@change-vector": "A:9948-k50KTOC5G0mfVXKjomTNFQ, A:1887-0N64iiIdYUKcO+yq1V0cPA, A:6214-xwmnvG1KBkSNXfl7/0yJ1A",
              "@id": "regions/1-A",
              "@last-modified": "2018-07-27T12:11:53.2016685Z"
          }
      },
      {
          "@metadata": {
              "@collection": "Regions",
              "@change-vector": "A:9954-k50KTOC5G0mfVXKjomTNFQ, A:1887-0N64iiIdYUKcO+yq1V0cPA, A:6214-xwmnvG1KBkSNXfl7/0yJ1A",
              "@id": "regions/2-A",
              "@last-modified": "2018-07-27T12:11:53.2021826Z"
          }
      },
      {
          "@metadata": {
              "@collection": "Regions",
              "@change-vector": "A:9950-k50KTOC5G0mfVXKjomTNFQ, A:1887-0N64iiIdYUKcO+yq1V0cPA, A:6214-xwmnvG1KBkSNXfl7/0yJ1A",
              "@id": "regions/3-A",
              "@last-modified": "2018-07-27T12:11:53.2018086Z"
          }
      },
      {
          "@metadata": {
              "@collection": "Regions",
              "@change-vector": "A:9952-k50KTOC5G0mfVXKjomTNFQ, A:1887-0N64iiIdYUKcO+yq1V0cPA, A:6214-xwmnvG1KBkSNXfl7/0yJ1A",
              "@id": "regions/4-A",
              "@last-modified": "2018-07-27T12:11:53.2019223Z"
          }
      }
  ]
}
```
