List documents with POST

Retrieve a set of documents with optional filtering, sorting, and pagination. Use the request body to specify filters, sort order, and which fields to return.

Note: Sending an empty payload ({}) returns all documents in the index.

Note: Documents are not returned following the order of their primary keys.

POST /indexes/{index_uid}/documents/fetch

cURL

cURL

curl \
  -X POST MEILISEARCH_URL/indexes/books/documents/fetch \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "filter": "(rating > 3 AND (genres = Adventure OR genres = Fiction)) AND language = English",
    "fields": ["title", "genres", "rating", "language"],
    "limit": 3
  }'

import requests

url = "http://localhost:7700/indexes/{index_uid}/documents/fetch"

payload = {
    "offset": 150,
    "limit": 1,
    "fields": ["title, description"],
    "retrieveVectors": True,
    "ids": ["cody", "finn", "brandy", "gambit"],
    "filter": "<unknown>",
    "sort": ["title:asc", "rating:desc"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    offset: 150,
    limit: 1,
    fields: ['title, description'],
    retrieveVectors: true,
    ids: ['cody', 'finn', 'brandy', 'gambit'],
    filter: '<unknown>',
    sort: ['title:asc', 'rating:desc']
  })
};

fetch('http://localhost:7700/indexes/{index_uid}/documents/fetch', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "7700",
  CURLOPT_URL => "http://localhost:7700/indexes/{index_uid}/documents/fetch",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'offset' => 150,
    'limit' => 1,
    'fields' => [
        'title, description'
    ],
    'retrieveVectors' => true,
    'ids' => [
        'cody',
        'finn',
        'brandy',
        'gambit'
    ],
    'filter' => '<unknown>',
    'sort' => [
        'title:asc',
        'rating:desc'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:7700/indexes/{index_uid}/documents/fetch"

	payload := strings.NewReader("{\n  \"offset\": 150,\n  \"limit\": 1,\n  \"fields\": [\n    \"title, description\"\n  ],\n  \"retrieveVectors\": true,\n  \"ids\": [\n    \"cody\",\n    \"finn\",\n    \"brandy\",\n    \"gambit\"\n  ],\n  \"filter\": \"<unknown>\",\n  \"sort\": [\n    \"title:asc\",\n    \"rating:desc\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:7700/indexes/{index_uid}/documents/fetch")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"offset\": 150,\n  \"limit\": 1,\n  \"fields\": [\n    \"title, description\"\n  ],\n  \"retrieveVectors\": true,\n  \"ids\": [\n    \"cody\",\n    \"finn\",\n    \"brandy\",\n    \"gambit\"\n  ],\n  \"filter\": \"<unknown>\",\n  \"sort\": [\n    \"title:asc\",\n    \"rating:desc\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:7700/indexes/{index_uid}/documents/fetch")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"offset\": 150,\n  \"limit\": 1,\n  \"fields\": [\n    \"title, description\"\n  ],\n  \"retrieveVectors\": true,\n  \"ids\": [\n    \"cody\",\n    \"finn\",\n    \"brandy\",\n    \"gambit\"\n  ],\n  \"filter\": \"<unknown>\",\n  \"sort\": [\n    \"title:asc\",\n    \"rating:desc\"\n  ]\n}"

response = http.request(request)
puts response.read_body

200

{
  "results": [
    {
      "title": "The Travels of Ibn Battuta",
      "genres": [
        "Travel",
        "Adventure"
      ],
      "language": "English",
      "rating": 4.5
    },
    {
      "title": "Pride and Prejudice",
      "genres": [
        "Classics",
        "Fiction",
        "Romance",
        "Literature"
      ],
      "language": "English",
      "rating": 4
    }
  ],
  "offset": 0,
  "limit": 2,
  "total": 5
}

{
  "message": "The Authorization header is missing. It must use the bearer authorization method.",
  "code": "missing_authorization_header",
  "type": "auth",
  "link": "https://docs.meilisearch.com/errors#missing_authorization_header"
}

{
  "message": "Index `movies` not found.",
  "code": "index_not_found",
  "type": "invalid_request",
  "link": "https://docs.meilisearch.com/errors#index_not_found"
}

Authorizations

Authorization · string · header · required

An API key is a token that you provide when making API calls. Read more about how to secure your project.

Include the API key to the Authorization header, for instance:

-H 'Authorization: Bearer 6436fc5237b0d6e0d64253fbaac21d135012ecf1'

If you use a SDK, ensure you instantiate the client with the API key, for instance with JS SDK:

const client = new MeiliSearch({
  host: 'MEILISEARCH_URL',
  apiKey: '6436fc5237b0d6e0d64253fbaac21d135012ecf1'
});

Path Parameters

index_uid · string · required

Unique identifier of the index.

Body

application/json

Request body for browsing and retrieving documents from an index. Use this to fetch documents with optional filtering, sorting, and pagination. This is useful for displaying document lists, exporting data, or inspecting index contents.

offset · integer · default: 0

Number of documents to skip in the response. Use together with limit for pagination through large document sets. For example, to get documents 151-170, set offset=150 and limit=20. Defaults to 0.

Required range: x >= 0

Example:

150

limit · integer · default: 20

Maximum number of documents to return in a single response. Use together with offset for pagination. Higher values return more results but may increase response time and memory usage. Defaults to 20.

Required range: x >= 0

Example:

1

fields · string[] | null

Array of document attributes to include in the response. If not specified, all attributes listed in the displayedAttributes setting are returned. Use this to reduce response size by only requesting the fields you need. Example: ["title", "description", "price"].

Example:

["title, description"]

retrieveVectors · boolean

When true, includes the vector embeddings in the response for documents that have them. This is useful when you need to inspect or export vector data. Note that this can significantly increase response size. Defaults to false.

Example:

true

ids · string[] | null

Array of specific document IDs to retrieve. Only documents with matching primary key values will be returned. If not specified, all documents matching other criteria are returned. This is useful for fetching specific known documents.

Example:

["cody", "finn", "brandy", "gambit"]

filter · any

Filter expression to select which documents to return. Attributes must be added to the filterableAttributes index setting before they can be used in filters. Accepts a string or an array of arrays of strings for AND/OR combinations. Example string: "genres = action AND rating > 4". Example array: [["genres = action", "genres = comedy"], "rating > 4"] (inner array = OR, outer = AND).

sort · string[] | null

Array of attributes to sort the documents by. Each entry should be in the format attribute:direction where direction is either asc (ascending) or desc (descending). Example: ["price:asc", "rating:desc"] sorts by price ascending, then by rating descending.

Example:

["title:asc", "rating:desc"]

Response

200

application/json

Documents returned.

results · any[] · required

Items for the current page.

offset · integer · required

Number of items skipped.

Required range: x >= 0

limit · integer · required

Maximum number of items returned.

Required range: x >= 0

total · integer · required

Total number of items matching the query.

Required range: x >= 0