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.

POST /indexes/{indexUid}/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
  }'

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
}

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

indexUid · 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

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. Uses the same syntax as search filters. Only documents matching the filter will be included in the response. Example: "genres = action AND rating > 4" or as an array [["genres = action"], "rating > 4"].

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

The documents are 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