Search with Marqo

This guide shows you how to search your product catalog using Marqo's ecommerce search API. Learn how to perform text searches, filter results, implement faceted search, and browse collections.

Prerequisites

A Marqo Cloud account
Your Marqo index ID (used for the x-marqo-index-id header)
An existing ecommerce index with products (add products guide)

Search Requests

Search requests are made via a POST /search request with a search body containing your query and search parameters.

Example

cURL
JavaScript

curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "x-marqo-index-id: {index_id}" \
-H "Content-Type: application/json" \
-d '{
  "q": "wireless headphones",
  "limit": 25
}'

fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search", {
  method: "POST",
  headers: {
    "x-marqo-index-id": "{index_id}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    q: "wireless headphones",
    limit: 25,
  }),
});

Note: Replace {index_name} with your actual index name and {index_id} with the ID provided for your ecommerce deployment.

Response

{
  "hits": [
    {
      "productTitle": "Premium Wireless Bluetooth Headphones",
      "variantTitle": "Premium Wireless Bluetooth Headphones - Black",
      "price": 199.99,
      "variantImageUrl": "https://cdn.example.com/headphones-black.jpg",
      "color": "Black",
      "collections": ["electronics", "audio"],
      "_id": "headphones-black-001",
      "_score": 1.23456
    },
    {
      "productTitle": "Wireless Earbuds Pro",
      "variantTitle": "Wireless Earbuds Pro - White",
      "price": 149.99,
      "variantImageUrl": "https://cdn.example.com/earbuds-white.jpg",
      "color": "White",
      "collections": ["electronics", "audio"],
      "_id": "earbuds-white-002",
      "_score": 1.15432
    }
  ],
  "limit": 10,
  "offset": 0,
  "query": "wireless headphones"
}

Search Parameters

Here is a full list of parameters available for /search:

Parameter	Type	Default	Description
`q`	String	`null`	Query string for product search
`limit`	Integer	`10`	Maximum number of products to return
`offset`	Integer	`0`	Number of products to skip (for pagination)
`filter`	String	`null`	Filter string using Marqo's query DSL to narrow search results
`attributesToRetrieve`	Array of strings	`["productTitle", "variantTitle", "price", "variantImageUrl", "collections", "_id", "_score"]`	Specific product fields to return. If not specified, returns the default core product fields
`facets`	Object	`null`	Facet configuration for aggregated results
`sortBy`	Object	`null`	Sort configuration for results ordering
`profileId`	String	`null`	(optional) The ID of a named configuration profile to use for the request. Profiles allow fine-tuned configurations tailored to specific use cases. If the specified profile does not exist, Marqo will fallback to the default configuration. Please contact your Marqo representative to set up profiles for your requirements. Example: `summer-sale-2026`
`userId`	String	`null`	User ID for personalization
`sessionId`	String	`null`	Session ID for personalization

Filtering

You can use Marqo's filter string DSL to refine search results. Filter strings can be used with all search methods and use a syntax based on Lucene with some differences. For complete filter syntax and examples, see our Filter DSL Guide.

Key Filter Features

Fielded searches - All term filters must be connected to a field, e.g., brand:Nike
Range filters - Efficient range filters for numeric types, e.g., price:[50 TO 300]
Boolean operators - Support for AND, OR, NOT with proper grouping
Array filtering - Filter over array fields like collections or tags

Examples

cURL
JavaScript

# Price range and availability filters
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "x-marqo-index-id: {index_id}" \
-H "Content-Type: application/json" \
-d '{
  "q": "headphones",
  "filter": "price:[50 TO 300] AND is_available:true"
}'

# Logical operators with grouping
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "x-marqo-index-id: {index_id}" \
-H "Content-Type: application/json" \
-d '{
  "q": "shoes",
  "filter": "(brand:Nike AND collections:athletic) OR (brand:Adidas AND price:[* TO 150])"
}'

# Array field filtering
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "x-marqo-index-id: {index_id}" \
-H "Content-Type: application/json" \
-d '{
  "q": "electronics",
  "filter": "collections:audio OR collections:wireless"
}'

# Boolean and exact match
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "x-marqo-index-id: {index_id}" \
-H "Content-Type: application/json" \
-d '{
  "q": "*",
  "filter": "is_featured:true AND brand:(Apple OR Samsung)"
}'

// Price range and availability filters
fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search", {
  method: "POST",
  headers: {
    "x-marqo-index-id": "{index_id}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    q: "headphones",
    filter: "price:[50 TO 300] AND is_available:true",
  }),
});

// Logical operators with grouping
fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search", {
  method: "POST",
  headers: {
    "x-marqo-index-id": "{index_id}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    q: "shoes",
    filter:
      "(brand:Nike AND collections:athletic) OR (brand:Adidas AND price:[* TO 150])",
  }),
});

// Array field filtering
fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search", {
  method: "POST",
  headers: {
    "x-marqo-index-id": "{index_id}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    q: "electronics",
    filter: "collections:audio OR collections:wireless",
  }),
});

// Boolean and exact match
fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search", {
  method: "POST",
  headers: {
    "x-marqo-index-id": "{index_id}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    q: "*",
    filter: "is_featured:true AND brand:(Apple OR Samsung)",
  }),
});

Common Filter Patterns

Filter Type	Example	Description
Price Range	`price:[50 TO 300]`	Products between $50-$300
Open Range	`price:[100 TO *]`	Products $100 and above
Exact Match	`brand:Nike`	Products with exact brand match
Boolean	`is_available:true`	Products that are available
Array Contains	`collections:electronics`	Products in electronics collection
Logical AND	`brand:Nike AND price:[* TO 200]`	Nike products under $200
Logical OR	`brand:(Nike OR Adidas)`	Products from either brand
Complex Expression	`(brand:Nike AND collections:athletic) OR (price:[* TO 50] AND is_sale:true)`	Nike athletic items OR sale items under $50
NOT Operator	`collections:electronics AND NOT brand:Apple`	Electronics excluding Apple products

Faceted Search

Facets allow you to aggregate data from your documents based on specific fields. This can be useful for creating filters, showing data distributions, or implementing drill-down search functionality.

Parameters

Parameter	Type	Default	Description
`fields`	Object	`null`	Fields to facet on and their configuration
`maxResults`	Integer	`100`	Maximum facet results per field (max: 10000)
`maxDepth`	Integer	`null`	Max documents to consider for aggregation
`order`	String	`"desc"`	Order of facet results: `asc` or `desc`

Field Parameters

Parameter	Type	Description
`type`	String	Facet type: `string`, `number`, or `array`
`ranges`	Array	For numeric fields: define value ranges
`excludeTerms`	Array	Exclude specific terms from this facet

Range Parameters (Numeric Fields)

Parameter	Type	Default	Description
`from`	Number	`null`	Lower bound (inclusive), `-Inf` if not specified
`to`	Number	`null`	Upper bound (exclusive), `Inf` if not specified
`name`	String	`null`	Custom range name (defaults to "from:to")

Examples

cURL
JavaScript

# Price ranges and category facets
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "x-marqo-index-id: {index_id}" \
-H "Content-Type: application/json" \
-d '{
  "q": "electronics",
  "facets": {
    "fields": {
      "price": {
        "type": "number",
        "ranges": [
          {"to": 50},
          {"from": 50, "to": 100},
          {"from": 100, "to": 200},
          {"from": 200, "name": "$200+"}
        ]
      },
      "brand": {"type": "string"},
      "collections": {"type": "array"}
    }
  }
}'

# Simple string facet
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "x-marqo-index-id: {index_id}" \
-H "Content-Type: application/json" \
-d '{
  "q": "shoes",
  "facets": {
    "fields": {
      "brand": {"type": "string", "maxResults": 10}
    }
  }
}'

// Price ranges and category facets
fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search", {
  method: "POST",
  headers: {
    "x-marqo-index-id": "{index_id}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    q: "electronics",
    facets: {
      fields: {
        price: {
          type: "number",
          ranges: [
            { to: 50 },
            { from: 50, to: 100 },
            { from: 100, to: 200 },
            { from: 200, name: "$200+" },
          ],
        },
        brand: { type: "string" },
        collections: { type: "array" },
      },
    },
  }),
});

// Simple string facet
fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search", {
  method: "POST",
  headers: {
    "x-marqo-index-id": "{index_id}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    q: "shoes",
    facets: {
      fields: {
        brand: { type: "string", maxResults: 10 },
      },
    },
  }),
});

Response

{
  "hits": [...],
  "facets": {
    "price": {
      "0.0:50.0": {
        "count": 15,
        "min": 19.99,
        "max": 49.99,
        "avg": 34.50,
        "sum": 517.50
      },
      "$200+": {
        "count": 8,
        "min": 200.00,
        "max": 599.99,
        "avg": 325.00
      }
    },
    "brand": {
      "Nike": {"count": 25},
      "Adidas": {"count": 18},
      "Apple": {"count": 12}
    },
    "collections": {
      "electronics": {"count": 120},
      "audio": {"count": 45}
    }
  }
}

Sorting

sortBy allows you to sort the search results based on specific numerical fields. This can be useful for ordering results by price, rating, or any other numerical attribute.

Parameters

Parameter	Type	Default	Description
`fields`	List[Dict]	No default	A list of fields to be sorted on, with sort order and missing policy
`sortDepth`	Integer	`null`	The number of documents to be sorted in the global phase
`minSortCandidates`	Integer	`null`	The minimum number of documents to be sorted on

Field Parameters

Parameter	Type	Default	Description
`fieldName`	String	No default	The field to be sorted on
`order`	String	`"desc"`	The sort order: `"desc"` or `"asc"`
`missing`	String	`"last"`	Missing value policy: `"first"` or `"last"`

Examples

cURL
JavaScript

# Sort by price descending
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "x-marqo-index-id: {index_id}" \
-H "Content-Type: application/json" \
-d '{
    "q": "shoes",
    "sortBy": {
        "fields": [{"fieldName": "price"}]
    }
}'

# Multi-field sort with missing value handling
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "x-marqo-index-id: {index_id}" \
-H "Content-Type: application/json" \
-d '{
    "q": "electronics",
    "sortBy": {
        "fields": [
            {"fieldName": "rating", "order": "desc", "missing": "last"},
            {"fieldName": "price", "order": "asc", "missing": "first"}
        ]
    }
}'

# Performance optimization with minSortCandidates
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "x-marqo-index-id: {index_id}" \
-H "Content-Type: application/json" \
-d '{
    "q": "laptops",
    "sortBy": {
        "fields": [{"fieldName": "price", "order": "desc"}],
        "minSortCandidates": 1000,
        "sortDepth": 60
    }
}'

// Sort by price descending
fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search", {
  method: "POST",
  headers: {
    "x-marqo-index-id": "{index_id}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    q: "shoes",
    sortBy: {
      fields: [{ fieldName: "price" }],
    },
  }),
});

// Multi-field sort with missing value handling
fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search", {
  method: "POST",
  headers: {
    "x-marqo-index-id": "{index_id}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    q: "electronics",
    sortBy: {
      fields: [
        { fieldName: "rating", order: "desc", missing: "last" },
        { fieldName: "price", order: "asc", missing: "first" },
      ],
    },
  }),
});

// Performance optimization with minSortCandidates
fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search", {
  method: "POST",
  headers: {
    "x-marqo-index-id": "{index_id}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    q: "laptops",
    sortBy: {
      fields: [{ fieldName: "price", order: "desc" }],
      minSortCandidates: 1000,
      sortDepth: 60,
    },
  }),
});

Pagination

Handle large result sets with pagination using limit and offset parameters.

Parameters

Parameter	Type	Default	Description
`limit`	Integer	`10`	Maximum number of documents to return
`offset`	Integer	`0`	Number of documents to skip

Examples

cURL
JavaScript

# Page 1 (first 20 results)
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "x-marqo-index-id: {index_id}" \
-H "Content-Type: application/json" \
-d '{
  "q": "laptops",
  "limit": 20,
  "offset": 0
}'

# Page 2 (results 21-40)
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "x-marqo-index-id: {index_id}" \
-H "Content-Type: application/json" \
-d '{
  "q": "laptops",
  "limit": 20,
  "offset": 20
}'

// Page 1 (first 20 results)
fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search", {
  method: "POST",
  headers: {
    "x-marqo-index-id": "{index_id}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    q: "laptops",
    limit: 20,
    offset: 0,
  }),
});

// Page 2 (results 21-40)
fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search", {
  method: "POST",
  headers: {
    "x-marqo-index-id": "{index_id}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    q: "laptops",
    limit: 20,
    offset: 20,
  }),
});

Search as You Type

Search as you type provides real-time search results as users input queries, creating an instant and responsive search experience. This feature leverages the same search endpoint with optimized parameters for real-time performance.

Implementation

Use the standard search endpoint with these considerations for optimal real-time performance:

Lower limits: Use smaller limit values (5-10) for faster response times
Minimal attributes: Only retrieve essential fields using attributesToRetrieve
Client-side debouncing: Implement 200-300ms delays between requests
Minimum query length: Consider requiring 2-3 characters before triggering search

Example

cURL
JavaScript

# Real-time search with optimized parameters
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "x-marqo-index-id: {index_id}" \
-H "Content-Type: application/json" \
-d '{
  "q": "iph",
  "limit": 5,
  "attributesToRetrieve": ["productTitle", "variantTitle", "price", "variantImageUrl"]
}'

fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search", {
  method: "POST",
  headers: {
    "x-marqo-index-id": "{index_id}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    q: "iph",
    limit: 5,
    attributesToRetrieve: [
      "productTitle",
      "variantTitle",
      "price",
      "variantImageUrl",
    ],
  }),
});

Best Practices

Debouncing: Implement client-side delays to prevent excessive API calls
Progressive loading: Start with minimal results and allow expansion
Caching: Cache recent results to improve perceived performance
Error handling: Gracefully handle timeouts and network issues
Accessibility: Ensure screen readers can navigate real-time results

Composite Search

Composite search enables multi-term queries where each search term can have a different weight.

Example

cURL
JavaScript

curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/composite-search \
-H "x-marqo-index-id: {index_id}" \
-H "Content-Type: application/json" \
-d '{
  "weightedQuery": {
    "wireless headphones": 1.0,
    "high quality": 0.5
  },
  "originalQuery": "wireless headphones",
  "limit": 20
}'

fetch(
  "https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/composite-search",
  {
    method: "POST",
    headers: {
      "x-marqo-index-id": "{index_id}",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      weightedQuery: {
        "wireless headphones": 1.0,
        "high quality": 0.5,
      },
      originalQuery: "wireless headphones",
      limit: 20,
    }),
  }
);

Parameters

Parameter	Type	Default	Description
`weightedQuery`	Object	required	Multi-term query as key-value pairs where keys are search terms and values are weights
`originalQuery`	String	`null`	The original user query string. Include this if the user entered a single string that was transformed into the `weightedQuery`
`limit`	Integer	`10`	Maximum number of products to return
`offset`	Integer	`0`	Number of products to skip (for pagination)
`filter`	String	`null`	Filter string using Marqo's query DSL
`attributesToRetrieve`	Array of strings	Default fields	Specific product fields to return
`facets`	Object	`null`	Facet configuration for aggregated results
`profileId`	String	`null`	(optional) The ID of a named configuration profile to use for the request. Profiles allow fine-tuned configurations tailored to specific use cases. If the specified profile does not exist, Marqo will fallback to the default configuration. Please contact your Marqo representative to set up profiles for your requirements. Example: `summer-sale-2026`

Response

{
  "hits": [
    {
      "productTitle": "Premium Noise-Cancelling Wireless Headphones",
      "variantTitle": "Premium Noise-Cancelling Wireless Headphones - Black",
      "price": 249.99,
      "variantImageUrl": "https://cdn.example.com/headphones-pro.jpg",
      "collections": ["electronics", "audio", "wireless"],
      "_id": "headphones-pro-001",
      "_score": 1.85432
    }
  ],
  "limit": 20,
  "offset": 0,
  "query": {
    "wireless headphones": 1.0,
    "noise cancelling": 0.5
  }
}

Prerequisites​

Search Requests​

Example​

Response​

Search Parameters​

Filtering​

Key Filter Features​

Examples​

Common Filter Patterns​

Faceted Search​

Parameters​

Field Parameters​

Range Parameters (Numeric Fields)​

Examples​

Response​

Sorting​

Parameters​

Field Parameters​

Examples​

Pagination​

Parameters​

Examples​

Search as You Type​

Implementation​

Example​

Best Practices​

Composite Search​

Example​

Parameters​

Response​

Prerequisites

Search Requests

Example

Response

Search Parameters

Filtering

Key Filter Features

Examples

Common Filter Patterns

Faceted Search

Parameters

Field Parameters

Range Parameters (Numeric Fields)

Examples

Response

Sorting

Parameters

Field Parameters

Examples

Pagination

Parameters

Examples

Search as You Type

Implementation

Example

Best Practices

Composite Search

Example

Parameters

Response