Skip to content

Marqo Event Tracking API Guide

Overview

The Marqo Event Tracking API allows you to track user interactions on ecommerce websites by sending HTTP requests directly to the Marqo API. Track key events such as searches, clicks, add-to-cart actions, and purchases. These events are collected by Marqo and made available for model training and index optimization.

Features

  • Direct API Integration: Send tracking data directly via HTTP requests
  • A/B Testing Support: Include experiment identifiers for testing different approaches
  • Comprehensive Event Tracking: Track searches, clicks, add-to-cart, and purchases
  • Flexible Implementation: Integrate from any backend system or client application

High Level Implementation

There are a few main steps to implementing Marqo Event Tracking:

  1. Gather your customerID, experimentID, and API key from your Marqo account.
  2. Configure your application to send HTTP POST requests to the Marqo API endpoint.
  3. [Optional] If running A/B experiments, include the appropriate experiment identifiers in your requests.
  4. Implement event tracking for each user interaction you want to monitor (detailed below).

Prerequisites

  1. Reach out to the Marqo team for access to your customerID and experimentID.
  2. Locate your API Key from the Marqo Cloud Console.

API Configuration

Configuration Variables

Gather the following information from your Marqo account:

Parameter Type Description
customerId string Your unique customer identifier from Marqo
experimentId string Unique identifier for this tracking experiment
apiKey string API key for authentication from Marqo Cloud Console

API Endpoint

All events should be sent to: 

POST https://metrics-client-gateway-7as0xbl6.uc.gateway.dev

A/B Testing with Event Tracking

When running A/B experiments, you can include additional context in your event tracking to analyze the performance of different approaches.

Experiment Tracking Strategy

  1. Assign Users to Variants: Implement your own logic to assign users to different experiment groups
  2. Include Experiment Context: Add experiment information to your event data
  3. Track Consistently: Ensure the same user always gets the same variant throughout their session

Example Implementation

curl -X POST "https://metrics-client-gateway-7as0xbl6.uc.gateway.dev" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Origin: https://yourdomain.com" \
  -d '{
    "events": [{
      "eventType": "ClickEvent",
      "customerId": "YOUR_CUSTOMER_ID",
      "experimentId": "YOUR_EXPERIMENT_ID",
      "userId": "user123",
      "sessionId": "session456",
      "timestamp": "2025-06-16T12:00:00Z",
      "title": "Running Shoes",
      "docId": "12345",
      "referrerUrl": "https://yourdomain.com/",
      "pageUrl": "https://yourdomain.com/products/running-shoes"
    }]
  }'

This approach allows you to: - Track which variant a user experienced - Analyze conversion rates by experiment group
- Compare search performance across different implementations

Event Tracking API Calls

Track user interactions by sending HTTP POST requests to the Marqo API endpoint with the appropriate event data and authentication headers.

Required Headers

All API calls must include these headers:

Content-Type: application/json
x-api-key: YOUR_API_KEY
Origin: https://yourdomain.com

Event Structure

All events follow this structure with an events array:

{
  "events": [
    {
      "eventType": "...",
      "customerId": "YOUR_CUSTOMER_ID",
      "experimentId": "YOUR_EXPERIMENT_ID",
      "userId": "user123",
      "sessionId": "session456", 
      "timestamp": "2025-06-16T12:00:00Z",
      // Event-specific data goes here at the top level
      "query": "example search term",
      "docId": "12345",
      "title": "Product Title"
    }
  ]
}

Event Types and Examples

Here are the 5 main event types for tracking user interactions:

Important: All events use a flat structure with event-specific data alongside common fields and ISO 8601 timestamps.

Search Event

Track when a user performs a search.

curl -X POST "https://metrics-client-gateway-7as0xbl6.uc.gateway.dev" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Origin: https://yourdomain.com" \
  -d '{
    "events": [{
      "eventType": "SearchEvent",
      "customerId": "YOUR_CUSTOMER_ID",
      "experimentId": "YOUR_EXPERIMENT_ID",
      "userId": "user123",
      "sessionId": "session456",
      "timestamp": "2025-06-16T12:00:00Z",
      "query": "red sneakers",
      "referrerUrl": "https://yourdomain.com/",
      "pageUrl": "https://yourdomain.com/search?q=red+sneakers"
    }]
  }'

Collection View Event

Track when a user views a collection page.

curl -X POST "https://metrics-client-gateway-7as0xbl6.uc.gateway.dev" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Origin: https://yourdomain.com" \
  -d '{
    "events": [{
      "eventType": "CollectionViewEvent",
      "customerId": "YOUR_CUSTOMER_ID",
      "experimentId": "YOUR_EXPERIMENT_ID",
      "userId": "user123",
      "sessionId": "session456",
      "timestamp": "2025-06-16T12:00:00Z",
      "collectionName": "shoes",
      "referrerUrl": "https://yourdomain.com/",
      "pageUrl": "https://yourdomain.com/collections/shoes"
    }]
  }'

Click Event

Track user clicks (like product views or button clicks).

curl -X POST "https://metrics-client-gateway-7as0xbl6.uc.gateway.dev" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Origin: https://yourdomain.com" \
  -d '{
    "events": [{
      "eventType": "ClickEvent",
      "customerId": "YOUR_CUSTOMER_ID",
      "experimentId": "YOUR_EXPERIMENT_ID",
      "userId": "user123",
      "sessionId": "session456",
      "timestamp": "2025-06-16T12:00:00Z",
      "docId": "12345",
      "title": "Running Shoes Red for Men",
      "referrerUrl": "https://yourdomain.com/search?q=red+sneakers",
      "pageUrl": "https://yourdomain.com/products/running-shoes-red-men"
    }]
  }'

Add to Cart Event

Track when a user adds a product to their cart.

curl -X POST "https://metrics-client-gateway-7as0xbl6.uc.gateway.dev" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Origin: https://yourdomain.com" \
  -d '{
    "events": [{
      "eventType": "AddToCartEvent",
      "customerId": "YOUR_CUSTOMER_ID",
      "experimentId": "YOUR_EXPERIMENT_ID",
      "userId": "user123",
      "sessionId": "session456",
      "timestamp": "2025-06-16T12:00:00Z",
      "docId": "12345",
      "title": "Running Shoes Red for Men",
      "referrerUrl": "https://yourdomain.com/search?q=red+sneakers",
      "pageUrl": "https://yourdomain.com/products/running-shoes-red-men"
    }]
  }'

Purchase Event

Track completed purchases.

curl -X POST "https://metrics-client-gateway-7as0xbl6.uc.gateway.dev" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Origin: https://yourdomain.com" \
  -d '{
    "events": [{
      "eventType": "PurchaseEvent",
      "customerId": "YOUR_CUSTOMER_ID",
      "experimentId": "YOUR_EXPERIMENT_ID",
      "userId": "user123",
      "sessionId": "session456",
      "timestamp": "2025-06-16T12:00:00Z",
      "docId": "12345",
      "quantity": 1,
      "title": "Running Shoes Red for Men",
      "price": 76,
      "referrerUrl": "https://yourdomain.com/products/running-shoes-red-men",
      "pageUrl": "https://yourdomain.com/checkout"
    }]
  }'

Extracting Context from Referrer URLs

For click, add-to-cart, and purchase events, you should extract context information from the referrer URL to provide attribution for user actions:

Collection Name Extraction

Extract collection names from referrer URLs using patterns like: - https://yourstore.com/collections/shoes → collectionName: "shoes" - https://yourstore.com/collections/electronics → collectionName: "electronics"

Search Query Extraction

Extract search queries from referrer URLs using URL parameters: - https://yourstore.com/search?q=red+sneakers → query: "red sneakers" - https://yourstore.com/search?q=wireless+headphones → query: "wireless headphones"

Implementation Example

// Extract collection name from URL
function getCollectionNameFromUrl(url) {
  const match = url.match(/\/collections\/([^/?#]+)/);
  return match ? match[1] : null;
}

// Extract search query from URL parameters
function getSearchQueryFromUrl(url) {
  const params = new URL(url, window.location.origin).searchParams;
  const query = params.get('q');
  return query ? decodeURIComponent(query.replace(/\+/g, ' ')).trim() : null;
}

This context helps track the customer journey and understand how users navigate from search results or collection pages to product interactions and purchases.

Parameter Descriptions

Based on the confirmed API structure:

Common Event Fields (Required for All Events)

Parameter Type Description Required
eventType string Type of event: "SearchEvent", "CollectionViewEvent", "ClickEvent", "AddToCartEvent", "PurchaseEvent" Yes
customerId string Your unique customer identifier Yes
experimentId string Unique identifier for tracking session Yes
userId string Unique identifier for the user Yes
sessionId string Unique identifier for the user session Yes
timestamp string ISO 8601 timestamp (e.g., "2025-06-16T12:00:00Z") Yes

Search Event Fields

Parameter Type Description
query string Search query entered by user
referrerUrl string URL of the page that referred the user to this page
pageUrl string Current page URL where the event occurred

Collection View Event Fields

Parameter Type Description
collectionName string Name of the collection
referrerUrl string URL of the page that referred the user to this page
pageUrl string Current page URL where the event occurred

Click Event Fields

Parameter Type Description
docId string Document identifier
title string Product title
referrerUrl string URL of the page that referred the user to this page
pageUrl string Current page URL where the event occurred

Add to Cart Event Fields

Parameter Type Description
docId string Document identifier
title string Product title
referrerUrl string URL of the page that referred the user to this page
pageUrl string Current page URL where the event occurred

Purchase Event Fields

Parameter Type Description
docId string Document identifier
quantity number Number of items purchased
title string Product title
price number Price per item
referrerUrl string URL of the page that referred the user to this page
pageUrl string Current page URL where the event occurred

Session Management and User Tracking

With the API-based approach, you are responsible for managing user sessions and tracking if needed for your use case.

Implementation Notes

  • Required Fields: Every event must include eventType, customerId, experimentId, userId, sessionId, and timestamp
  • Flat Structure: Event-specific data goes at the top level alongside common fields
  • Timestamp Format: Use ISO 8601 format (e.g., "2025-06-16T12:00:00Z")
  • Simple Structure: Keep only essential fields as shown in the examples above
  • Privacy Compliance: Ensure event tracking complies with privacy regulations

Authentication and Security

All API calls to the Marqo tracking service require proper authentication and should follow security best practices.

Authentication Headers

Each API request must include the following headers:

Header Description Example
Content-Type Specifies JSON content format application/json
x-api-key API key for authentication <api_key>
Origin Your website domain https://yourdomain.com

Security Best Practices

  • HTTPS Only: Always use HTTPS when making API calls
  • API Key Protection: Store API keys securely and never expose them in client-side code
  • Rate Limiting: Implement appropriate rate limiting to avoid API throttling
  • Error Handling: Implement retry logic with exponential backoff for failed requests
  • Data Validation: Validate all data before sending to ensure proper formatting
  • CORS Considerations: Ensure your domain is authorized for cross-origin requests if calling from browser

Marqo Data Collection Policy

Overview

Marqo is committed to protecting and ensuring the privacy and security of our customers and their site users. We believe in transparency regarding how we collect and use data to improve our services. When you implement Marqo event tracking on your site, we collect limited user interaction data that you choose to send. This data is exclusively used for fine-tuning our base models, optimizing index settings, enhancing search relevance and accuracy, providing better overall search experiences for your users. This data is not sold to third parties and is retained in our system for a default period of 2 years. Marqo has robust mechanisms to delete and remove this data upon request from our customers.

Data Collection Details

Marqo collects various types of data through the event tracking API. The exact data collection scope is subject to the specific implementation chosen by the customer, but typically includes:

User Interaction Events

  • Search Activity
    • Search queries
    • Filter selections
    • Search refinements
    • Results viewed
  • E-commerce Interactions
    • Add-to-cart actions
    • Purchase completions
    • Product views
    • Checkout processes
  • Site Engagement
    • Button clicks
    • Page navigation
    • Content interaction
    • Session duration

Technical Information

  • Browser type and version
  • Device information (desktop, mobile, tablet)
  • Operating system
  • Date and time of interactions
  • HTTP information: protocol, version, and response code

Data Security and Compliance

All collected data is processed in compliance with relevant data protection regulations and accessible only to authorized personnel

Data Usage Benefits

The data collected through Marqo event tracking directly contributes to: source- More accurate search results for your users - Personalized search experiences - Improved product recommendations - Enhanced analytics and insights - Continuous improvement of the Marqo platform For additional information or to discuss specific data collection requirements, please contact our team at support@marqo.ai.