Skip to main content

Getting Products in Marqo

This guide shows you how to get existing product documents from your Marqo ecommerce search index.

Prerequisites​

Get Documents Request​

Get multiple documents via a POST /indexes/{index_name}/get-documents request.

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

Authentication: This endpoint accepts either credential. Use Authorization: Bearer {api_key} from server-side code, or x-marqo-index-id: {index_id} (the read-only credential used by the search endpoints) when calling it from a storefront.

Parameters​

ParameterTypeDefaultDescription
documentIdsarray of stringsrequiredThe IDs of the documents to retrieve. Between 1 and 100 non-empty strings. Example: ["43207430723", "43207430724"]
attributesToRetrievearray of stringsall fieldsOptional. Only these fields are returned for each document, which keeps the response small when you need a few attributes. Up to 100 non-empty strings. _id, _found, _score and _highlights are always returned. Example: ["productTitle", "price"]

Any other key in the request body is rejected with a 400.

Query parameters​

ParameterTypeDefaultDescription
flattenMapsBooleanfalseBy default, map fields are returned as nested objects ({"specs": {"weight": 1}}). Set ?flattenMaps=true on the request URL to receive dotted keys instead ({"specs.weight": 1}).

Response​

The response has the following fields:

FieldTypeDescription
resultsArrayAn array of objects, one per requested ID, in the order requested. Each object contains the document's data.

A 200 response status does not necessarily imply that each individual document within the batch was found. For each document in the batch, there will be an associated response code that specifies the status of that particular document's processing. These individual response codes provide granular feedback, allowing users to discern which documents were successfully processed, which encountered errors, and the nature of any issues encountered. If Marqo finds the document, the document will be returned with the _found field set to true in an object. For documents not found, the _found field will be set to false, with the document ID returned in the _id field and details of the error in the message field.

For this endpoint, a 200 status code is not used to indicate successful document retrieval, as we aim to avoid adding extra fields to the returned documents. Here is the HTTP status code of the individual document responses (non-exhaustive list of status codes):

Status CodeDescription
400Bad request. Returned for invalid input (e.g., invalid field types). Inspect message for details.
404The target document is not in the index.
429Marqo index has received too many requests. Please try again later.
500Internal error.

Response headers​

HeaderDescription
x-marqo-cache-hittrue when the response was served from the cache, false otherwise. Present on every response.

Request errors​

A request that fails validation returns 400 with an {"error": ...} body and no results:

errorWhen
"Parameter 'documentIds' is required and must be a non-empty array of document IDs"documentIds is missing, empty, longer than 100 entries, or contains a value that is not a non-empty string
"All attributesToRetrieve must be non-empty strings"attributesToRetrieve contains an empty string or a non-string value
"Number of 'attributesToRetrieve' must be less than or equal to 100"attributesToRetrieve has more than 100 entries
"Unrecognized param(s): 'limit'"The body contains a key that is not documentIds or attributesToRetrieve (the unknown keys are listed in the message)

Example​

curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/get-documents \
	-H "Authorization: Bearer {api_key}" \
	-H "Content-Type: application/json" \
	-d '{"documentIds": ["headphones-black-001", "headphones-blue-004", "earbuds-white-002"]}'

Response​

{
  "results": [
    {
      "_id": "headphones-black-001",
      "_found": true,
      "productTitle": "Premium Wireless Bluetooth Headphones",
      "variantTitle": "Premium Wireless Bluetooth Headphones - Black",
      "price": 199.99,
      "variantImageUrl": "https://cdn.example.com/headphones-black.jpg",
      "color": "Black",
      "productCollections": ["electronics", "audio"]
    },
    {
      "_id": "headphones-blue-004",
      "_found": false,
      "status": 404,
      "message": "Document does not exist in the index"
    },
    {
      "_id": "earbuds-white-002",
      "_found": true,
      "productTitle": "Wireless Earbuds Pro",
      "variantTitle": "Wireless Earbuds Pro - White",
      "price": 149.99,
      "variantImageUrl": "https://cdn.example.com/earbuds-white.jpg",
      "color": "White",
      "productCollections": ["electronics", "audio"]
    }
  ]
}

In this response, the index has no document with an ID of headphones-blue-004. As a result, the _found field is false.

Example with attributesToRetrieve​

Request only the title and price from a storefront, using the read-only index ID:

curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/get-documents \
	-H "x-marqo-index-id: {index_id}" \
	-H "Content-Type: application/json" \
	-d '{
  "documentIds": ["headphones-black-001"],
  "attributesToRetrieve": ["productTitle", "price"]
}'
{
  "results": [
    {
      "_id": "headphones-black-001",
      "_found": true,
      "productTitle": "Premium Wireless Bluetooth Headphones",
      "price": 199.99
    }
  ]
}