Skip to 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

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 -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",
        "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.