Overview#

The msearch API endpoint enables clients to execute multiple independent search queries in a single request, leveraging Elasticsearch's multi-search (msearch) functionality. This is useful for batch querying where results do not depend on each other and can be processed in parallel.

Endpoint Specification#

HTTP Method and URL#

• POST /api/v2/msearch

Request Body#

The request body must be a JSON object containing a searches array. Each element in the array is an object describing an individual search.

Example Request#

{
  "searches": [
    {
      "query": "tax_rank(species)",
      "result": "taxon",
      "taxonomy": "ncbi",
      "fields": "taxon_id,scientific_name",
      "limit": 100
    },
    {
      "query": "tax_rank(genus)",
      "result": "taxon",
      "taxonomy": "ncbi",
      "limit": 50
    }
  ]
}

Search Object Parameters#

• query (string, required): The search query string.
• result (string, optional): The result type (e.g., taxon, assembly). Defaults to taxon.
• taxonomy (string, optional): The taxonomy to search (e.g., ncbi).
• fields (string, optional): Comma-separated list of fields to include in the result.
• limit (integer, optional): Maximum number of results to return for this search (default: 100, max: 10,000).
• offset (integer, optional): Number of results to skip (default: 0).
• sortBy, sortOrder, sortMode (optional): Sorting options.
• includeEstimates, includeDescendants, includeRawValues (optional): Flags to control inclusion of additional data.

Each search object must include a query parameter. If any search is missing this, the endpoint returns a 400 error.

Request Limits#

• Maximum of 100 searches per request. Exceeding this returns a 400 error.

Response#

The response is a JSON object with a status field and a results array. Each element in results corresponds to a search in the request.

Example Response#

{
  "status": {
    "success": true,
    "hits": 150
  },
  "results": [
    {
      "status": "success",
      "count": 100,
      "total": 100,
      "hits": [
        {
          "taxon_id": 12345,
          "scientific_name": "Example species"
        }
        // ...more hits
      ],
      "search": {
        "query": "tax_rank(species)",
        "result": "taxon",
        "taxonomy": "ncbi",
        "fields": "taxon_id,scientific_name",
        "limit": 100
      }
    },
    {
      "status": "success",
      "count": 50,
      "total": 50,
      "hits": [
        // ...hits for genus search
      ],
      "search": {
        "query": "tax_rank(genus)",
        "result": "taxon",
        "taxonomy": "ncbi",
        "limit": 50
      }
    }
  ]
}

If a search fails to build or execute, its result will have status: "error" and an error message.

Error Handling#

• If any search object is missing the query parameter, the endpoint returns a 400 error with a descriptive message.
• If more than 100 searches are submitted, the endpoint returns a 400 error.
• If an internal error occurs during execution, the endpoint returns a 500 error with a failure message.
• If a specific search fails to build, its result in the results array will have status: "error" and an error message, but other searches will still be processed.

Downloading Batch Results#

A GET variant of the endpoint allows downloading batch search results in JSON, CSV, or TSV formats. This uses query parameters to specify multiple searches and internally uses the same msearch logic.

Example GET Request#

GET /api/v2/msearch/download?originalQueries[0]=canis&originalQueries[1]=rosa&result=taxon&fields=taxon_id,scientific_name&format=csv

• originalQueries[n]: Individual search terms.
• result, taxonomy, fields, format, and other parameters as described above.
• format: Desired output format (json, csv, tsv).

Additional Notes#

• The endpoint builds Elasticsearch queries for each search and executes them in a single msearch call.
• If a search query is invalid, the endpoint logs the error and returns a placeholder result for that search, ensuring the response array aligns with the request order.
• The endpoint is designed for parallel, independent searches and is not suitable for queries that depend on each other's results.

For further details, see the msearch.js implementation.