Skip to main content

Collections with Marqo

This guide shows you how to retrieve collections from your product catalog using Marqo's API. Learn how to build collection pages with filtering, faceted search, sorting, and pagination to create curated browsing experiences for your customers.

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)

Collections Requests​

Collections requests are made via a POST /indexes/{index_name}/collections request or via a GET /indexes/{index_name}/collections request. The latter may be preferred for SEO optimization on some sites, and requires first encoding the request body in base 64.

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

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

Example: POST​

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

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

Example: GET​

Base64 encoding: To submit a request via the GET endpoint, pass the base64-encoded request body as the body query parameter.

curl -X GET \
"https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/collections?body=eyJjb2xsZWN0aW9uTmFtZSI6InNoaXJ0cyJ9" \
-H "x-marqo-index-id: {index_id}"

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

Example encoding:

  • JSON: {"collectionName":"shirts"}
  • Base64: eyJjb2xsZWN0aW9uTmFtZSI6InNoaXJ0cyJ9

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:

ParameterTypeDefaultDescription
collectionNameStringnull (required)The name of the collection to browse
limitInteger10Maximum number of products to return
offsetInteger0Number of products to skip (for pagination)
filterStringnullFilter string using Marqo's query DSL to narrow search results
attributesToRetrieveArray of strings["productTitle", "variantTitle", "price", "variantImageUrl", "productCollections", "parentProductId", "_id", "_score"]Specific product fields to return. If not specified, returns the default core product fields
facetsObjectnullFacet configuration for aggregated results
sortByObjectnullSort configuration for results ordering
profileIdStringnull(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
userIdStringnullUser ID for personalization - generally optional but is required to enable personalized collection results.
sessionIdStringnullSession ID for personalization - note that it has no effect unless userId is also set.

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 "x-marqo-index-id: {index_id}" \
-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 "x-marqo-index-id: {index_id}" \
-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 "x-marqo-index-id: {index_id}" \
-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 "x-marqo-index-id: {index_id}" \
-H "Content-Type: application/json" \
-d '{
  "collectionName": "featured-electronics",
  "filter": "is_featured:true AND brand:(Apple OR Samsung)"
}'

Common Filter Patterns​

Filter TypeExampleDescription
Price Rangeprice:[50 TO 300]Products between $50-$300
Open Rangeprice:[100 TO *]Products $100 and above
Exact Matchbrand:NikeProducts with exact brand match
Booleanis_available:trueProducts that are available
Array Containscollections:electronicsProducts in electronics collection
Logical ANDbrand:Nike AND price:[* TO 200]Nike products under $200
Logical ORbrand:(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 Operatorcollections:electronics AND NOT brand:AppleElectronics excluding Apple products

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​

ParameterTypeDefaultDescription
fieldsObjectnullFields to facet on and their configuration
maxResultsInteger100Maximum facet results per field (max: 10000)
maxDepthIntegernullMax documents to consider for aggregation
orderString"desc"Order of facet results: asc or desc

Field Parameters​

ParameterTypeDescription
typeStringFacet type: string, number, or array
rangesArrayFor numeric fields: define value ranges
excludeTermsArrayExclude specific terms from this facet

Range Parameters (Numeric Fields)​

ParameterTypeDefaultDescription
fromNumbernullLower bound (inclusive), -Inf if not specified
toNumbernullUpper bound (exclusive), Inf if not specified
nameStringnullCustom 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 "x-marqo-index-id: {index_id}" \
-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 "x-marqo-index-id: {index_id}" \
-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​

ParameterTypeDefaultDescription
fieldsList[Dict]No defaultA list of fields to be sorted on, with sort order and missing policy
sortDepthIntegernullThe number of documents to be sorted in the global phase
minSortCandidatesIntegernullThe minimum number of documents to be sorted on

Field Parameters​

ParameterTypeDefaultDescription
fieldNameStringNo defaultThe field to be sorted on
orderString"desc"The sort order: "desc" or "asc"
missingString"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 "x-marqo-index-id: {index_id}" \
-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 "x-marqo-index-id: {index_id}" \
-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 "x-marqo-index-id: {index_id}" \
-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​

ParameterTypeDefaultDescription
limitInteger10Maximum number of documents to return
offsetInteger0Number 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 "x-marqo-index-id: {index_id}" \
-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 "x-marqo-index-id: {index_id}" \
-H "Content-Type: application/json" \
-d '{
  "collectionName": "laptops",
  "limit": 20,
  "offset": 20
}'