Getting Products in Marqo

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

Prerequisites

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

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

Parameters

Name	Type	Required	Description	Example
documentIds	array[string]	yes	Input document IDs to retrieve, max 100 ids.	["43207430723", "43207430724"]

The response has the following fields:

Field	Type	Description
results	Array	An array of objects, each representing a document. Each object contains the document's data.

A 200 response status does not necessarily imply that each individual document within the batch was processed without issues. 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 Code	Description
400	Bad request. Returned for invalid input (e.g., invalid field types). Inspect message for details.
404	The target document is not in the index.
429	Marqo index has received too many requests. Please try again later.
500	Internal error.

Example

cURL

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"]}'

JavaScript

fetch(
  "https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/get-documents",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer {api_key}",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      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",
        "collections": ["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",
        "collections": ["electronics", "audio"]
    }
]}

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