Search

Full-text search with support for filters, faceted search, sorting, highlighting, and hybrid vector search.

POST/v1/search

Search an index.

Auth admin or search keyReturns 200

Request body

{
  "index": "products",
  "q": "macbook",
  "limit": 10,
  "offset": 0,
  "filter": "price < 2000",
  "sort": ["price:asc"],
  "facets": ["category"],
  "attributesToHighlight": ["title"],
  "attributesToRetrieve": ["id", "title", "price"]
}

Response

{
  "hits": [
    {
      "id": 1,
      "title": "MacBook Pro",
      "price": 1999,
      "_formatted": {
        "title": "<em>MacBook</em> Pro"
      }
    }
  ],
  "query": "macbook",
  "processingTimeMs": 2,
  "estimatedTotalHits": 42,
  "facetDistribution": {
    "category": { "laptops": 12, "phones": 30 }
  }
}

Parameter	Type	Default	Description
`index`	string	Required	The index uid to search.
`q`	string	""	The search query string. Empty string returns all documents.
`limit`	number	10	Maximum number of hits to return.
`offset`	number	0	Number of hits to skip (for pagination).
`filter`	string	""	Filter expression, e.g. "price < 2000 AND category = laptops".
`sort`	string[]	[]	Sort order, e.g. ["price:asc", "title:desc"].
`facets`	string[]	[]	Attributes to compute facet distributions for.
`attributesToHighlight`	string[]	[]	Attributes to wrap matches with <em> tags.
`attributesToRetrieve`	string[]	["*"]	Attributes to include in each hit. Defaults to all.
`attributesToCrop`	string[]	[]	Attributes whose values will be cropped around matches.
`cropLength`	number	10	Number of words around a match when cropping.
`showMatchesPosition`	boolean	false	Include match position information in each hit.
`showRankingScore`	boolean	false	Include the ranking score in each hit.
`matchingStrategy`	string	"last"	"last", "all", or "frequency".
`hybrid`	object	null	Enable hybrid search. Example: { semanticRatio: 0.5, embedder: "default" }.
`vector`	number[]	null	Vector for nearest-neighbor search (used with hybrid or standalone).

Filters

Filter expressions let you narrow search results. Attributes must be listed in filterableAttributes in your index settings before they can be used in filters.

filter syntax

// Simple comparison
"price < 2000"

// Equality
"category = laptops"

// Combined with AND / OR
"price < 2000 AND category = laptops"
"category = laptops OR category = phones"

// IN operator
"category IN [laptops, phones, tablets]"

// Negation
"NOT category = accessories"

// Nested with parentheses
"(price < 500 OR price > 2000) AND category = laptops"

Facets

Pass attribute names in the facets array to receive a distribution of values for each attribute. Useful for building filter UIs with counts.

response

"facetDistribution": {
  "category": {
    "laptops": 12,
    "phones": 30,
    "tablets": 8
  }
}

Sorting

Sort results by one or more attributes. Attributes must be listed in sortableAttributes. Use the format attribute:direction where direction is asc or desc.

example

"sort": ["price:asc", "title:desc"]

Highlighting

Request highlighted versions of attributes to show which parts of the text matched the query. Matched text is wrapped in <em> tags.

response

"_formatted": {
  "title": "<em>MacBook</em> Pro 16-inch"
}