Reverse Image Search

Reverse image search finds the products in your catalog that look most like a query image. It uses AI to assess visual similarity and order the results so the closest matches come first, which makes it well suited to "find this exact product" experiences. Because of the additional AI processing, it is a bit slower than a plain Search by Image request, but is able to get better results for "in-the-wild" images that users upload.

note

Reverse image search must be enabled for your index before it can be used. If it is not enabled, the endpoint returns 404. Contact your Marqo account manager to enable this feature.

Prerequisites

• A Marqo Cloud account (sign up here)
• Your Marqo index ID (used for the x-marqo-index-id header)
• Reverse image search enabled for your index — contact your Marqo account manager to enable this feature

Endpoint

Requests are made via a POST to the reverse-image-search endpoint. The query image is provided in q, either as a URL to an image or as a data URL containing a base64-encoded image.

cURL

# With a URL to an image
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/reverse-image-search \
-H "x-marqo-index-id: {index_id}" \
-H "Content-Type: application/json" \
-d '{
  "q": "https://example.com/image.jpg",
  "limit": 10
}'

# With a base64 data URL
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/reverse-image-search \
-H "x-marqo-index-id: {index_id}" \
-H "Content-Type: application/json" \
-d '{
  "q": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD//gAMQX..."
}'

JavaScript

fetch(
  "https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/reverse-image-search",
  {
    method: "POST",
    headers: {
      "x-marqo-index-id": "{index_id}",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      q: "https://example.com/image.jpg",
      limit: 10,
    }),
  }
);

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

Response

Hits are returned best-first, ordered by visual similarity to the query image. Each hit has the same shape as a regular /search hit.

{
  "hits": [
    {
      "productTitle": "Premium Wireless Bluetooth Headphones",
      "variantTitle": "Premium Wireless Bluetooth Headphones - Black",
      "price": 199.99,
      "variantImageUrl": "https://cdn.example.com/headphones-black.jpg",
      "collections": ["electronics", "audio"],
      "_id": "headphones-black-001"
    }
  ],
  "limit": 10,
  "processingTimeMs": 1830
}

Response fields

Field	Type	Description
hits	Array	Matching products, ordered best-first by visual similarity to the query image
limit	Integer	The effective number of results requested (after clamping)
processingTimeMs	Integer	Total server-side processing time for the request, in milliseconds

Parameters

Parameter	Type	Default	Description
q	String	required	The query image, as an image URL or a base64 data URL. Text queries are not accepted.
limit	Integer	10	Maximum number of products to return. Clamped to the range 1–10.
filter	String	null	Filter string using Marqo's query DSL. Only products matching the filter are returned.
attributesToRetrieve	Array of strings	Default fields	Specific product fields to return on each hit. If not specified, returns the default core product fields.

Image requirements

When q is a URL, the path must end in one of these image extensions: .jpg, .jpeg, .png, .webp, .tiff, .avif. When q is a data URL, any image/* MIME type is accepted.

Filtering

You can narrow the results with a filter string. Only products matching the filter are returned.

cURL

curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/reverse-image-search \
-H "x-marqo-index-id: {index_id}" \
-H "Content-Type: application/json" \
-d '{
  "q": "https://example.com/sneaker.jpg",
  "filter": "brand:Nike AND price:[* TO 200]"
}'

JavaScript

fetch(
  "https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/reverse-image-search",
  {
    method: "POST",
    headers: {
      "x-marqo-index-id": "{index_id}",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      q: "https://example.com/sneaker.jpg",
      filter: "brand:Nike AND price:[* TO 200]",
    }),
  }
);

For the full filter syntax, see the Filter DSL Guide.

Error responses

Status	Body	Condition
400	{ "error": "q must be an image URL or base64 data URI" }	q is missing or is not a valid image URL or data URL
400	{ "error": "filter must be a string" }	filter was provided but is not a string
400	{ "error": "attributesToRetrieve must be an array of strings" }	attributesToRetrieve was provided but is not an array of strings
401	{ "error": "Unauthorized" }	Missing or invalid credentials
404	{ "error": "reverse image search is not enabled for this index" }	Reverse image search is not enabled for the index