POST /v1/indexes/products/query 🔒 Bearer

Your first search

A minimal but real example that actually returns useful results.

Assume you've followed the Quickstart: you have an index called products with a few documents in it. Now we'll search them.

The minimum query needs two fields — q (what to look for) and query_by (which fields to look in).

# Run it

query_by is a comma-separated list of fields. Weights are inherited from your index settings, but you can override them per request.

# The response

{
  "data": {
    "found": 12,
    "out_of": 54,
    "page": 1,
    "hits": [
      {
        "document": { "id": "14", "title": "Sony WH-1000XM5", "brand": "Sony", "price": 379 },
        "highlight": {
          "title": { "snippet": "Sony <mark>WH-1000XM5</mark>", "matched_tokens": ["WH-1000XM5"] }
        },
        "text_match": 578730054645712906,
        "relevance_bonus": 10
      }
    ],
    "search_time_ms": 8,
    "ai_context": null
  }
}

# What each field means

Field Meaning
found Total documents matched by the query.
out_of Documents in the index after any filters were applied.
hits[].document The original document you indexed.
hits[].highlight Field-by-field <mark>-wrapped snippets, plus the matched tokens.
hits[].text_match Internal relevance score — already sorted descending.
hits[].relevance_bonus Extra points from your ranking rules / scorer (prefix, brand, SKU).
search_time_ms Engine time only. Network round-trip is your client's responsibility.
ai_context Populated when AI Query Understanding rewrote the query — see AI features.

# Common follow-ups

  • Add a filter: pass filter_by: "in_stock:true".
  • Get a facet count: pass facet_by: "brand".
  • Page through results: pass per_page and page.
  • Limit returned fields: pass include_fields: "id,title,price" to shrink the response.

See the full parameter list on the query reference page.

esc
POST /v1/indexes/products/query