Search Profiles

A profile is a named, complete search configuration for your index. Every index has a default configuration that is used when a request does not name a profile. When a request includes a profileId, the profile's configuration replaces that default for the request. Profiles let you run different retrieval, ranking and presentation settings for different surfaces (for example a product detail page, a landing page or a seasonal campaign) without changing the index default.

Profiles are created by Marqo for you today. Contact your Marqo representative to set up profiles for your requirements. Once a profile exists you can discover its id with the list profiles endpoint and pass it as profileId on the endpoints below.

Profile types

There are two kinds of profile. Each endpoint reads one of them, so the same id can only be used where its type applies.

Type	Used by
search	Search (POST /search), Composite Search (POST /composite-search), Collections when the request includes q (POST /collections), and the Similar, Complementary, Complete the Look and For You recommendation endpoints.
collection	Collections browsing, that is GET or POST /collections without q.

A search profile replaces the index's search configuration in full. A collection profile replaces the index's collections configuration, including any per-collection settings.

Behaviour

• Unknown ids fall back silently. If profileId names a profile that does not exist, or a profile of the wrong type for the endpoint, the request runs with the index default configuration and returns a normal response. No error is returned, so check the id against the list profiles endpoint when results look unchanged.
• Merchandising rules. When merchandising is enabled for your index, the profileId sent to /search, /collections, /recommendations/complementary and /recommendations/complete-the-look also selects the merchandising rules profile of the same name, so the request is merchandised with that profile's rules. /recommendations/similar keeps the two separate: profileId selects the search profile and merchandisingProfileId selects the merchandising rules profile. On /composite-search a profileId selects the search profile only; profile-scoped merchandising rules are not applied there.
• Query-level rules take precedence. If a query-level rule matches the request's query and carries its own search configuration, that configuration is used and profileId is not applied for that request.
• Merchandising profile ids are not listed here. The list profiles endpoint returns search and collection profiles only. Merchandising profiles are created in the merchandising console and their ids come from there.

List profiles

Returns every profile defined for an index, with its type.

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

Authentication: Authorization: Bearer {api_key} only. This is a management endpoint; a request that authenticates with x-marqo-index-id is rejected with 401 {"error": "Unauthorized"}.

cURL

curl https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/profiles \
  -H "Authorization: Bearer {api_key}"

JavaScript

fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/profiles", {
  method: "GET",
  headers: {
    "Authorization": "Bearer {api_key}",
  },
});

Response: 200

{
  "profiles": [
    { "profileId": "pdp_default", "profileType": "search" },
    { "profileId": "summer-sale-2026", "profileType": "search" },
    { "profileId": "new-arrivals", "profileType": "collection" }
  ]
}

Field	Type	Description
profiles	Array	One entry per profile. Empty when the index has no profiles.
profiles[].profileId	String	The id to send as profileId on a request.
profiles[].profileType	String	search or collection. See Profile types for which endpoints read each type.

Using a profile

Send the id in the request body as profileId.

cURL

curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
  -H "x-marqo-index-id: {index_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "running shoes",
    "profileId": "summer-sale-2026"
  }'

JavaScript

fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search", {
  method: "POST",
  headers: {
    "x-marqo-index-id": "{index_id}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    q: "running shoes",
    profileId: "summer-sale-2026",
  }),
});