Browse with Marqo

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

Prerequisites

A Marqo Cloud account
Your Marqo API key (find your API key guide)
An existing ecommerce index with products (add products guide)

Collections Requests

Collections requests are made via a POST /indexes/{index_name}/collections request.

Endpoint: POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/collections

Example

curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/collections \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "collectionName": "shirts"
}'

Note: Replace {index_name} with your actual index name and {api_key} with your API key.

Response

{
  "hits": [
    {
      "productCollections": ["shirts"],
      "price": 300,
      "_id": "red-shirt",
      "productTitle": "Shirt",
      "parentProductId": "parent-shirt",
      "variantTitle": "Shirt - Red",
      "variantImageUrl": "https://cdn.shopify.com/s/files/1/0705/8276/3687/files/red-tshirt.jpg?v=1754569578",
      "color": "Red",
      "_score": 0
    },
    {
      "productCollections": ["shirts"],
      "price": 200,
      "_id": "blue-shirt",
      "productTitle": "Shirt",
      "parentProductId": "parent-shirt",
      "variantTitle": "Shirt - Blue",
      "variantImageUrl": "https://cdn.shopify.com/s/files/1/0705/8276/3687/files/blue-tshirt.jpg?v=1754569578",
      "color": "Blue",
      "_score": 0
    },
    {
      "productCollections": ["shirts"],
      "price": 100,
      "_id": "light-blue-shirt",
      "productTitle": "Shirt",
      "parentProductId": "parent-shirt",
      "variantTitle": "Shirt - Light Blue",
      "variantImageUrl": "https://cdn.shopify.com/s/files/1/0705/8276/3687/files/light-blue-tshirt.jpg?v=1754569578",
      "color": "Light Blue",
      "_score": 0
    }
  ],
  "processingTimeMs": 31,
  "query": "*",
  "limit": 100,
  "offset": 0,
  "totalHits": 3,
  "facets": {
    "variantOption2": {},
    "variantOption3": {},
    "variantWeight": {},
    "variantPrice": {},
    "productCollections": {
      "shirts": {"count": 3}
    },
    "variantOption1": {},
    "productType": {},
    "productVendor": {},
    "productCategory": {},
    "productTags": {}
  }
}

Collection Parameters

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

Parameter	Type	Default	Description
`collectionName`	String	`null` (required)	The name of the collection to browse
`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", "productCollections", "parentProductId", "_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
`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

# Price range and availability filters
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/collections \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "collectionName": "audio-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}/collections \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "collectionName": "athletic-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}/collections \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "collectionName": "electronics",
  "filter": "collections:audio OR collections:wireless"
}'

# Boolean and exact match
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/collections \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "collectionName": "featured-electronics",
  "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

# Price ranges and category facets
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/collections \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "collectionName": "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}/collections \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "collectionName": "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. This feature is only available for HYBRID search on unstructured indexes created with Marqo 2.22.0 or later.

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

# Sort by price descending
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/collections \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
    "collectionName": "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}/collections \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
    "collectionName": "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}/collections \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
    "collectionName": "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

# Page 1 (first 20 results)
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/collections \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "collectionName": "laptops",
  "limit": 20,
  "offset": 0
}'

# Page 2 (results 21-40)
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/collections \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "collectionName": "laptops",
  "limit": 20,
  "offset": 20
}'