​
Overview

The Agentic Search API facilitates deep, intent-focused search patterns. A user’s query is comprehended by a generative AI agent, which designs a set of search queries around it. The agent retrieves items from a Marqo index and returns a collection of result categories. Clients can then render these categories and offer relevant options to the user. The API streams responses in real-time, providing immediate feedback to the user. Developers can override features like the number of results per category, max number of categories, agent parameters, and search settings.
Note: Agentic Search is not publicly available at this time. Please contact us to request access.

​
Use Cases

This API is ideal for situations where a user’s query could span multiple, potentially non-overlapping product categories. The system interprets a high-level query and generates sub-queries (“head queries”) that organize results by category. Best suited for:
  • Marqo users with diverse product catalogs
  • Applications handling ambiguous or broad user queries

​
API Endpoint

​
Paths

  • GET /indexes/{index_name}/agentic-search

​
Authentication

  • Include the x-marqo-index-id header (copy it from the Quick Start code snippets for your index in the Marqo Console).

​
Request Format

Use GET with URL query parameters due to SSE constraints.

​
Agentic Search Parameters

ParameterTypeDefaultDescription
qString(required)The user’s query
categoryResultLimitInteger12Number of results per category (distinct from searchSettings.limit)
maxCategoriesInteger5Maximum number of categories the agent will attempt to return
clickableSummaryBooleantrueDefines if the summary will contain markdown content for interaction
searchSettingsDictsee belowConfiguration used during search (see below)
userIdStringnullUser ID for personalization
sessionIdStringnullSession ID for personalization

​
Clickable Summary

The agent will incorporate suggested follow-up queries in its summary. If this is set to true, the agent will implant this pattern in the summary: [[button:query=<your_query>]]. Custom markdown renderers can then display that text as a button or other element.

​
Search Settings

ParameterTypeDefaultDescription
limitInteger10Maximum number of products to return
offsetInteger0Number of products to skip (for pagination)
filterStringnullFilter string using Marqo’s query DSL to narrow search results
attributesToRetrieveList[String]["productTitle", "variantTitle", "price", "variantImageUrl", "collections", "_id", "_score"]Specific product fields to return. If not specified, returns the default core product fields
facetsDictnullFacet configuration for aggregated results
sortByDictnullSort configuration for results ordering

​
Example Request

Step 1: Compose JSON payload (pretty-printed here for readability) 
{
  "q": "I need something to wear to a wedding",
  "sessionId": "session-abc123",
  "userId": "user-456",
  "categoryResultLimit": 10,
  "maxCategories": 4,
  "clickableSummary": true,
  "searchSettings": {
    "limit": 24,
    "offset": 0,
    "filter": "availability:true",
    "attributesToRetrieve": [
      "productTitle",
      "variantTitle",
      "price",
      "variantImageUrl",
      "collections",
      "_id",
      "_score"
    ],
    "facets": null,
    "sortBy": null
  }
}
Step 2: Base64 encode this JSON (URL-safe, no padding) 
eyJjYXRlZ29yeVJlc3VsdExpbWl0IjoxMCwiY2xpY2thYmxlU3VtbWFyeSI6dHJ1ZSwibWF4Q2F0ZWdvcmllcyI6NCwicSI6IkkgbmVlZCBzb21ldGhpbmcgdG8gd2VhciB0byBhIHdlZGRpbmciLCJzZWFyY2hTZXR0aW5ncyI6eyJhdHRyaWJ1dGVzVG9SZXRyaWV2ZSI6WyJwcm9kdWN0VGl0bGUiLCJ2YXJpYW50VGl0bGUiLCJwcmljZSIsInZhcmlhbnRJbWFnZVVybCIsImNvbGxlY3Rpb25zIiwiX2lkIiwiX3Njb3JlIl0sImZhY2V0cyI6bnVsbCwiZmlsdGVyIjoiYXZhaWxhYmlsaXR5OnRydWUiLCJsaW1pdCI6MjQsIm9mZnNldCI6MCwic2Vzc2lvbklkIjoic2Vzc2lvbi1hYmMxMjMiLCJzb3J0QnkiOm51bGwsInVzZXJJZCI6InVzZXItNDU2In0sInNlc3Npb25JZCI6InNlc3Npb24tYWJjMTIzIiwic3VnZ2VzdEZpbHRlcnMiOnRydWUsInVzZXJJZCI6InVzZXItNDU2In0=
Step 3: Use in the URL query param payload 
GET /indexes/my-first-index/agentic-search?payload=eyJjYXRlZ29yeVJlc3VsdExpbWl0IjoxMCwiY2xpY2thYmxlU3VtbWFyeSI6dHJ1ZSwibWF4Q2F0ZWdvcmllcyI6NCwicSI6IkkgbmVlZCBzb21ldGhpbmcgdG8gd2VhciB0byBhIHdlZGRpbmciLCJzZWFyY2hTZXR0aW5ncyI6eyJhdHRyaWJ1dGVzVG9SZXRyaWV2ZSI6WyJwcm9kdWN0VGl0bGUiLCJ2YXJpYW50VGl0bGUiLCJwcmljZSIsInZhcmlhbnRJbWFnZVVybCIsImNvbGxlY3Rpb25zIiwiX2lkIiwiX3Njb3JlIl0sImZhY2V0cyI6bnVsbCwiZmlsdGVyIjoiYXZhaWxhYmlsaXR5OnRydWUiLCJsaW1pdCI6MjQsIm9mZnNldCI6MCwic2Vzc2lvbklkIjoic2Vzc2lvbi1hYmMxMjMiLCJzb3J0QnkiOm51bGwsInVzZXJJZCI6InVzZXItNDU2In0sInNlc3Npb25JZCI6InNlc3Npb24tYWJjMTIzIiwic3VnZ2VzdEZpbHRlcnMiOnRydWUsInVzZXJJZCI6InVzZXItNDU2In0= HTTP/1.1
Host: api.example.com
Accept: text/event-stream
x-marqo-index-id: abc123-my-first-index

​
Response

​
JSON Response Structure

FieldTypeDescription
summaryStringAI-generated summary of the category results (may include links/buttons)
categoryHitsListList of result categories and associated items (see below)
hitsListNon-agentic search results using the provided query
facetsDictOptional facets metadata (if configured)
categoryHits Structure
FieldTypeDescription
categoryStringThe category label
hitsListDocuments returned for this category query

​
Streaming Response

  • Delivered via Server-Sent Events (SSE).
  • Each event sends deltas (incremental updates) to the response.
  • The final event is of type stream-end to indicate the end of the stream.
Example Stream Output 
event: delta
data: {
  "summary": "Here"
}

event: delta
data: {
  "summary": " are some options you might like for party wear."
}

event: delta
data: {
    "hits": [
      {"_id": "dress_001", "title": "Red Sequin Dress", "price": 89.99},
      {"_id": "dress_005", "title": "Red Silk Gown", "price": 221.99}
    ]
}

event: delta
data: {
  "categoryHits": [
    {
      "category": "Dresses",
      "hits": [
        {"_id": "dress_001", "title": "Red Sequin Dress", "price": 89.99},
        {"_id": "dress_002", "title": "Black Silk Gown", "price": 129.99},
        {"_id": "dress_003", "title": "Blue Off-Shoulder Dress", "price": 99.99}
      ]
    }
  ]
}

event: delta
data: {
  "summary": "Try searching for [[button:query=Casual party outfits]], [[button:query=Formal party attire]] or [[button:query=Accessories for a party]] for more options."
}

event: delta
data: {
  "categoryHits": [
    {
      "category": "Shoes",
      "hits": [
        {"_id": "shoe_001", "title": "Silver Heels", "price": 59.99},
        {"_id": "shoe_002", "title": "Strappy Sandals", "price": 49.99}
      ]
    }
  ]
}

event: stream-end
data: {}

​
Automatic Filtering

When automatic filtering is enabled for your index, the AI agent can apply precise filters to search results based on user intent. The agent understands the product attributes available in your catalog (brands, price ranges, categories, etc.) and constructs filters automatically when the user’s query implies specific criteria.

​
How It Works

  1. Filter construction: When user intent is clear, the agent constructs filter expressions using Marqo’s filter DSL:
    • Exact match: brand:(Nike)
    • Multiple values: (brand:(Nike) OR brand:(Adidas))
    • Numeric range: price:[50 TO 100]
    • Open-ended range: price:[* TO 100]
    • Combined: brand:(Nike) AND price:[* TO 100]
  2. Filter merging: The agent’s filter is merged with any client-provided searchSettings.filter using AND. For example, if the client sends filter: "availability:true" and the agent constructs brand:(Nike), the final filter becomes (availability:true) AND (brand:(Nike)).
  3. Zero-hit fallback: If the merged filter yields no results, the agent’s filter is automatically dropped and the search retries with only the client-provided filter. This ensures users always see relevant products even when the agent’s filter is too restrictive.

​
Response Metadata

When automatic filtering is active, each category in the categoryHits response includes filter metadata:
FieldTypeDescription
appliedFilterstringThe filter that was actually used for the search
filterDroppedbooleantrue if the agent’s filter was dropped due to zero results
originalFilterstringThe original filter before fallback (present when filterDropped is true)
{
  "categoryHits": [
    {
      "category": "Running Shoes",
      "confidence": 0.9,
      "hits": ["..."],
      "appliedFilter": "(availability:true) AND (brand:(Nike))",
      "filterDropped": false
    }
  ]
}