Perform a multi-search

Run multiple search queries in a single API request.

Each query can target a different index, so you can search across several indexes at once and get one combined response.

Warning: If Meilisearch encounters an error processing any query in the request, it immediately stops and returns an error message for the first error encountered. Partial results are not returned.

POST /multi-search

cURL

cURL

curl \
  -X POST 'MEILISEARCH_URL/multi-search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "queries": [
      {
        "indexUid": "movies",
        "q": "pooh",
        "limit": 5
      },
      {
        "indexUid": "movies",
        "q": "nemo",
        "limit": 5
      },
      {
        "indexUid": "movie_ratings",
        "q": "us"
      }
    ]
  }'

import requests

url = "http://localhost:7700/multi-search"

payload = {
    "queries": [
        {
            "indexUid": "movies",
            "q": "<string>",
            "offset": 1,
            "limit": 1,
            "page": 1,
            "hitsPerPage": 1,
            "attributesToRetrieve": ["<string>"],
            "attributesToCrop": ["<string>"],
            "cropLength": 1,
            "cropMarker": "<string>",
            "attributesToHighlight": ["<string>"],
            "highlightPreTag": "<string>",
            "highlightPostTag": "<string>",
            "showMatchesPosition": True,
            "filter": "<unknown>",
            "sort": ["<string>"],
            "distinct": "<string>",
            "facets": ["<string>"],
            "attributesToSearchOn": ["<string>"],
            "rankingScoreThreshold": 123,
            "locales": [],
            "hybrid": {
                "embedder": "default",
                "semanticRatio": 0.5
            },
            "vector": [123],
            "retrieveVectors": True,
            "media": "<unknown>",
            "personalize": { "userContext": "<string>" },
            "useNetwork": True,
            "showRankingScore": True,
            "showRankingScoreDetails": True,
            "showPerformanceDetails": True,
            "federationOptions": {
                "weight": 123,
                "remote": "<string>",
                "queryPosition": 1
            }
        }
    ],
    "federation": {
        "limit": 1,
        "offset": 1,
        "page": 1,
        "hitsPerPage": 1,
        "facetsByIndex": {},
        "mergeFacets": { "maxValuesPerFacet": 1 },
        "distinct": "<string>",
        "showPerformanceDetails": True,
        "personalize": { "userContext": "<string>" }
    }
}
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({
    queries: [
      {
        indexUid: 'movies',
        q: '<string>',
        offset: 1,
        limit: 1,
        page: 1,
        hitsPerPage: 1,
        attributesToRetrieve: ['<string>'],
        attributesToCrop: ['<string>'],
        cropLength: 1,
        cropMarker: '<string>',
        attributesToHighlight: ['<string>'],
        highlightPreTag: '<string>',
        highlightPostTag: '<string>',
        showMatchesPosition: true,
        filter: '<unknown>',
        sort: ['<string>'],
        distinct: '<string>',
        facets: ['<string>'],
        attributesToSearchOn: ['<string>'],
        rankingScoreThreshold: 123,
        locales: [],
        hybrid: {embedder: 'default', semanticRatio: 0.5},
        vector: [123],
        retrieveVectors: true,
        media: '<unknown>',
        personalize: {userContext: '<string>'},
        useNetwork: true,
        showRankingScore: true,
        showRankingScoreDetails: true,
        showPerformanceDetails: true,
        federationOptions: {weight: 123, remote: '<string>', queryPosition: 1}
      }
    ],
    federation: {
      limit: 1,
      offset: 1,
      page: 1,
      hitsPerPage: 1,
      facetsByIndex: {},
      mergeFacets: {maxValuesPerFacet: 1},
      distinct: '<string>',
      showPerformanceDetails: true,
      personalize: {userContext: '<string>'}
    }
  })
};

fetch('http://localhost:7700/multi-search', 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/multi-search",
  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([
    'queries' => [
        [
                'indexUid' => 'movies',
                'q' => '<string>',
                'offset' => 1,
                'limit' => 1,
                'page' => 1,
                'hitsPerPage' => 1,
                'attributesToRetrieve' => [
                                '<string>'
                ],
                'attributesToCrop' => [
                                '<string>'
                ],
                'cropLength' => 1,
                'cropMarker' => '<string>',
                'attributesToHighlight' => [
                                '<string>'
                ],
                'highlightPreTag' => '<string>',
                'highlightPostTag' => '<string>',
                'showMatchesPosition' => true,
                'filter' => '<unknown>',
                'sort' => [
                                '<string>'
                ],
                'distinct' => '<string>',
                'facets' => [
                                '<string>'
                ],
                'attributesToSearchOn' => [
                                '<string>'
                ],
                'rankingScoreThreshold' => 123,
                'locales' => [
                                
                ],
                'hybrid' => [
                                'embedder' => 'default',
                                'semanticRatio' => 0.5
                ],
                'vector' => [
                                123
                ],
                'retrieveVectors' => true,
                'media' => '<unknown>',
                'personalize' => [
                                'userContext' => '<string>'
                ],
                'useNetwork' => true,
                'showRankingScore' => true,
                'showRankingScoreDetails' => true,
                'showPerformanceDetails' => true,
                'federationOptions' => [
                                'weight' => 123,
                                'remote' => '<string>',
                                'queryPosition' => 1
                ]
        ]
    ],
    'federation' => [
        'limit' => 1,
        'offset' => 1,
        'page' => 1,
        'hitsPerPage' => 1,
        'facetsByIndex' => [
                
        ],
        'mergeFacets' => [
                'maxValuesPerFacet' => 1
        ],
        'distinct' => '<string>',
        'showPerformanceDetails' => true,
        'personalize' => [
                'userContext' => '<string>'
        ]
    ]
  ]),
  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/multi-search"

	payload := strings.NewReader("{\n  \"queries\": [\n    {\n      \"indexUid\": \"movies\",\n      \"q\": \"<string>\",\n      \"offset\": 1,\n      \"limit\": 1,\n      \"page\": 1,\n      \"hitsPerPage\": 1,\n      \"attributesToRetrieve\": [\n        \"<string>\"\n      ],\n      \"attributesToCrop\": [\n        \"<string>\"\n      ],\n      \"cropLength\": 1,\n      \"cropMarker\": \"<string>\",\n      \"attributesToHighlight\": [\n        \"<string>\"\n      ],\n      \"highlightPreTag\": \"<string>\",\n      \"highlightPostTag\": \"<string>\",\n      \"showMatchesPosition\": true,\n      \"filter\": \"<unknown>\",\n      \"sort\": [\n        \"<string>\"\n      ],\n      \"distinct\": \"<string>\",\n      \"facets\": [\n        \"<string>\"\n      ],\n      \"attributesToSearchOn\": [\n        \"<string>\"\n      ],\n      \"rankingScoreThreshold\": 123,\n      \"locales\": [],\n      \"hybrid\": {\n        \"embedder\": \"default\",\n        \"semanticRatio\": 0.5\n      },\n      \"vector\": [\n        123\n      ],\n      \"retrieveVectors\": true,\n      \"media\": \"<unknown>\",\n      \"personalize\": {\n        \"userContext\": \"<string>\"\n      },\n      \"useNetwork\": true,\n      \"showRankingScore\": true,\n      \"showRankingScoreDetails\": true,\n      \"showPerformanceDetails\": true,\n      \"federationOptions\": {\n        \"weight\": 123,\n        \"remote\": \"<string>\",\n        \"queryPosition\": 1\n      }\n    }\n  ],\n  \"federation\": {\n    \"limit\": 1,\n    \"offset\": 1,\n    \"page\": 1,\n    \"hitsPerPage\": 1,\n    \"facetsByIndex\": {},\n    \"mergeFacets\": {\n      \"maxValuesPerFacet\": 1\n    },\n    \"distinct\": \"<string>\",\n    \"showPerformanceDetails\": true,\n    \"personalize\": {\n      \"userContext\": \"<string>\"\n    }\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/multi-search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"queries\": [\n    {\n      \"indexUid\": \"movies\",\n      \"q\": \"<string>\",\n      \"offset\": 1,\n      \"limit\": 1,\n      \"page\": 1,\n      \"hitsPerPage\": 1,\n      \"attributesToRetrieve\": [\n        \"<string>\"\n      ],\n      \"attributesToCrop\": [\n        \"<string>\"\n      ],\n      \"cropLength\": 1,\n      \"cropMarker\": \"<string>\",\n      \"attributesToHighlight\": [\n        \"<string>\"\n      ],\n      \"highlightPreTag\": \"<string>\",\n      \"highlightPostTag\": \"<string>\",\n      \"showMatchesPosition\": true,\n      \"filter\": \"<unknown>\",\n      \"sort\": [\n        \"<string>\"\n      ],\n      \"distinct\": \"<string>\",\n      \"facets\": [\n        \"<string>\"\n      ],\n      \"attributesToSearchOn\": [\n        \"<string>\"\n      ],\n      \"rankingScoreThreshold\": 123,\n      \"locales\": [],\n      \"hybrid\": {\n        \"embedder\": \"default\",\n        \"semanticRatio\": 0.5\n      },\n      \"vector\": [\n        123\n      ],\n      \"retrieveVectors\": true,\n      \"media\": \"<unknown>\",\n      \"personalize\": {\n        \"userContext\": \"<string>\"\n      },\n      \"useNetwork\": true,\n      \"showRankingScore\": true,\n      \"showRankingScoreDetails\": true,\n      \"showPerformanceDetails\": true,\n      \"federationOptions\": {\n        \"weight\": 123,\n        \"remote\": \"<string>\",\n        \"queryPosition\": 1\n      }\n    }\n  ],\n  \"federation\": {\n    \"limit\": 1,\n    \"offset\": 1,\n    \"page\": 1,\n    \"hitsPerPage\": 1,\n    \"facetsByIndex\": {},\n    \"mergeFacets\": {\n      \"maxValuesPerFacet\": 1\n    },\n    \"distinct\": \"<string>\",\n    \"showPerformanceDetails\": true,\n    \"personalize\": {\n      \"userContext\": \"<string>\"\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:7700/multi-search")

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  \"queries\": [\n    {\n      \"indexUid\": \"movies\",\n      \"q\": \"<string>\",\n      \"offset\": 1,\n      \"limit\": 1,\n      \"page\": 1,\n      \"hitsPerPage\": 1,\n      \"attributesToRetrieve\": [\n        \"<string>\"\n      ],\n      \"attributesToCrop\": [\n        \"<string>\"\n      ],\n      \"cropLength\": 1,\n      \"cropMarker\": \"<string>\",\n      \"attributesToHighlight\": [\n        \"<string>\"\n      ],\n      \"highlightPreTag\": \"<string>\",\n      \"highlightPostTag\": \"<string>\",\n      \"showMatchesPosition\": true,\n      \"filter\": \"<unknown>\",\n      \"sort\": [\n        \"<string>\"\n      ],\n      \"distinct\": \"<string>\",\n      \"facets\": [\n        \"<string>\"\n      ],\n      \"attributesToSearchOn\": [\n        \"<string>\"\n      ],\n      \"rankingScoreThreshold\": 123,\n      \"locales\": [],\n      \"hybrid\": {\n        \"embedder\": \"default\",\n        \"semanticRatio\": 0.5\n      },\n      \"vector\": [\n        123\n      ],\n      \"retrieveVectors\": true,\n      \"media\": \"<unknown>\",\n      \"personalize\": {\n        \"userContext\": \"<string>\"\n      },\n      \"useNetwork\": true,\n      \"showRankingScore\": true,\n      \"showRankingScoreDetails\": true,\n      \"showPerformanceDetails\": true,\n      \"federationOptions\": {\n        \"weight\": 123,\n        \"remote\": \"<string>\",\n        \"queryPosition\": 1\n      }\n    }\n  ],\n  \"federation\": {\n    \"limit\": 1,\n    \"offset\": 1,\n    \"page\": 1,\n    \"hitsPerPage\": 1,\n    \"facetsByIndex\": {},\n    \"mergeFacets\": {\n      \"maxValuesPerFacet\": 1\n    },\n    \"distinct\": \"<string>\",\n    \"showPerformanceDetails\": true,\n    \"personalize\": {\n      \"userContext\": \"<string>\"\n    }\n  }\n}"

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

200

{
  "hits": [
    {
      "id": 42,
      "title": "Batman returns",
      "overview": "The overview of batman returns",
      "_federation": {
        "indexUid": "movies",
        "queriesPosition": 0
      }
    },
    {
      "comicsId": "batman-killing-joke",
      "description": "This comic is really awesome",
      "title": "Batman: the killing joke",
      "_federation": {
        "indexUid": "comics",
        "queriesPosition": 1
      }
    }
  ],
  "processingTimeMs": 0,
  "limit": 20,
  "offset": 0,
  "estimatedTotalHits": 2,
  "semanticHitCount": 0
}

{
  "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"
}

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'
});

Body

application/json

Request body for federated multi-search across multiple indexes. This allows you to execute multiple search queries in a single request and optionally combine their results into a unified response. Use this for cross-index search scenarios or to reduce network round-trips.

queries · object[] · required

An array of search queries to execute. Each query can target a different index and have its own parameters. When federation is null, results are returned separately for each query. When federation is set, results are merged.

Each query object must include indexUid to specify which index to search.

Show child attributes

federation · null | object

Configuration for combining results from multiple queries into a single response. When set, results are merged and ranked together. When null, each query's results are returned separately in an array.

Show child attributes

Response

200

application/json

Federated multi-search.

Option 1

Option 2

Response from a federated multi-search query

hitsPerPage · integer · required

Number of results per page.

Required range: x >= 0

page · integer · required

Current page index (1-based).

Required range: x >= 0

totalPages · integer · required

Exhaustive total number of result pages.

Required range: x >= 0

totalHits · integer · required

Exhaustive total number of matching documents.

Required range: x >= 0

hits · object[] · required

Combined search results from all queries

Show child attributes

processingTimeMs · integer · required

Total processing time in milliseconds

Required range: x >= 0

queryVectors · object | null

Show child attributes

facetDistribution · object | null

Show child attributes

facetStats · object | null

Merged facet statistics across all indexes

Show child attributes

facetsByIndex · object

Facets grouped by index

Show child attributes

requestUid · string<uuid> | null

Unique identifier for the request

metadata · object[] | null

Metadata for each query

Show child attributes

remoteErrors · object | null

Errors from remote servers

Show child attributes

semanticHitCount · integer<u-int32> | null

Required range: x >= 0

performanceDetails · any