Analytics API

The Analytics API provides comprehensive search analytics data for your Marqo implementation. Access metrics, trends, and insights about search behavior through a RESTful interface.

Base URL

https://ecom.marqo-ep.ai/api/v1/analytics

Authentication

Include your API key in the Authorization header of every request using the Bearer scheme:

Authorization: Bearer {api_key}

Common Parameters

Customer ID

Parameter	Type	Description
`customerId`	String (required)	Your pixel account identifier

Time Range Parameters

You must specify either days or both start and end:

Parameter	Type	Description
`days`	Integer	Number of days to look back (minimum: 1)
`start`	ISO 8601 datetime	Start of the time range (UTC)
`end`	ISO 8601 datetime	End of the time range (UTC)

Examples:

Using days:

?days=7

Using date range:

?start=2025-01-01T00:00:00Z&end=2025-01-31T23:59:59Z

Important: When providing start and end, end must be later than start. Timestamps are truncated to the hour (minutes and seconds are ignored), so 2025-12-05T10:59Z is treated as 2025-12-05T10:00:00Z.

Context Type

Parameter	Type	Description
`context`	String (enum)	The section context for analytics data

Valid values:

searches - Analytics for search queries
collections - Analytics for collection views

Term Filter

Parameter	Type	Description
`term`	String (optional)	Filter analytics for a specific search term or collection name

Label

Parameter	Type	Description
`label`	String (optional)	Scope analytics to a single label (namespace). Append `label=<label>` to any analytics request.

Labels let you segment analytics into namespaces that are tracked alongside your global metrics. Two kinds of labels are available:

A/B experiments — pixel_experiment:<experiment_id>, where <experiment_id> is the experiment you specified in the Pixel.
Traffic source — user_source:<traffic_source>, where <traffic_source> is one of the traffic source tags sent with your events (for example, user_source:web_prod).

Each label is its own namespace, so a labeled request returns metrics for only that namespace. The same events are still aggregated into your global (unlabeled) metrics, so requests without a label parameter continue to report combined totals across all sources.

Use the Labels endpoint to discover which labels are currently available for your account.

Example:

?label=user_source:web_prod

Metrics Reference

When using the Time Series endpoint, you must specify one of the following metrics:

Metric	Value	Description
Total Queries	`totalQueries`	Total number of search queries or collection views
Click-Through Rate	`clickThroughRate`	Percentage of queries that resulted in clicks
Add to Cart Rate	`addToCartRate`	Percentage of queries that resulted in add-to-cart actions
Conversion Rate	`conversionRate`	Percentage of queries that resulted in purchases
Average Order Value	`averageOrderValue`	Average monetary value of purchases
Total Revenue	`totalRevenue`	Total revenue generated
Total Clicks	`totalClicks`	Total number of clicks on results
Total Add to Carts	`totalAddToCarts`	Total number of add-to-cart actions
Total Purchases	`totalPurchases`	Total number of completed purchases
Sessions Count	`sessionsCount`	Total number of unique sessions

Endpoints

Get Available Accounts

Retrieves all pixel IDs associated with your account.

GET /accounts

Example Request:

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

Response:

{
  "customerIds": [
    {
      "customerId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "label": "label"
    },
    {
      "customerId": "f6e5d4c3-b2a1-4f5e-6d7c-8b9a0e1f2a3b",
      "label": "label"
    }
  ]
}

Error Responses:

404: No pixel ids found for your account

Labels

Returns the list of labels (namespaces) available for your account. Use any returned label as the value of the label query parameter on the other analytics endpoints to scope results to that namespace.

GET /labels

Query Parameters:

customerId (required)

Example Request:

curl "https://ecom.marqo-ep.ai/api/v1/analytics/labels?customerId=a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" \
  -H "Authorization: Bearer {api_key}"

Response:

{
  "labels": [
    "pixel_experiment:summer_ranking_test",
    "pixel_experiment:pdp_layout_v2",
    "user_source:web_prod",
    "user_source:app_prod",
    "user_source:web_mobile_prod"
  ]
}

Response Fields:

labels: Array of available labels. Each label is one of:
- pixel_experiment:<experiment_id> — an A/B experiment you specified in the Pixel.
- user_source:<traffic_source> — a traffic source derived from the traffic source tags sent with your events.

Applying a label:

Append label=<label> to any analytics request to scope it to that namespace. For example, to get the overview for web_prod traffic only:

curl "https://ecom.marqo-ep.ai/api/v1/analytics/overview?customerId=a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d&days=3&context=searches&label=user_source:web_prod" \
  -H "Authorization: Bearer {api_key}"

Labels are populated from data sent through the Event Tracking API. Traffic source labels only appear once events carrying the corresponding traffic source tags have been ingested.

Overview Analytics

Provides high-level analytics overview for the specified time period. Optionally filter by a specific search term or collection.

GET /overview

Query Parameters:

customerId (required)
context (required): searches or collections
days OR start + end (required): Time range
term (optional): Filter analytics for a specific search term or collection name
label (optional): Scope to a single namespace. See Label and the Labels endpoint

Example Request (All Terms):

curl "https://ecom.marqo-ep.ai/api/v1/analytics/overview?customerId=a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d&days=3&context=searches" \
  -H "Authorization: Bearer {api_key}"

Example Request (Specific Term):

curl "https://ecom.marqo-ep.ai/api/v1/analytics/overview?customerId=a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d&days=3&context=searches&term=technology" \
  -H "Authorization: Bearer {api_key}"

Response:

{
  "totalQueries": 116375,
  "clickThroughRate": 0.241,
  "addToCartRate": 0.0,
  "conversionRate": 0.149,
  "averageOrderValue": 0.064,
  "totalRevenue": 1114,
  "sessionsCount": 32011
}

Response Fields:

totalQueries: Total number of queries in the time period
clickThroughRate: Decimal representation of CTR (0.241 = 24.1%)
addToCartRate: Decimal representation of ATC rate
conversionRate: Decimal representation of conversion rate
averageOrderValue: Average order value in currency units
totalRevenue: Total revenue generated
sessionsCount: Number of unique user sessions

Search Terms Analytics

Returns analytics data for search terms within the specified period, sorted by total queries in descending order.

GET /terms

Query Parameters:

customerId (required)
context (required): searches or collections
days OR start + end (required): Time range
limit (optional): Number of terms to return (1-1000, default: 100)
label (optional): Scope to a single namespace. See Label and the Labels endpoint

Example Request:

curl "https://ecom.marqo-ep.ai/api/v1/analytics/terms?customerId=a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d&days=3&context=searches&limit=5" \
  -H "Authorization: Bearer {api_key}"

Response:

{
  "terms": [
    {
      "term": "logo",
      "totalQueries": 1241,
      "totalRevenue": 7,
      "clickThroughRate": 0.242,
      "addToCartRate": 0.0,
      "conversionRate": 0.211
    },
    {
      "term": "text",
      "totalQueries": 1150,
      "totalRevenue": 7,
      "clickThroughRate": 0.286,
      "addToCartRate": 0.0,
      "conversionRate": 0.215
    }
  ]
}

Response Fields (per term):

term: The search term or collection name
totalQueries: Number of times this term was queried
totalRevenue: Revenue generated from this term
clickThroughRate: CTR for this specific term
addToCartRate: ATC rate for this term
conversionRate: Conversion rate for this term

Funnel Analytics

Provides funnel conversion analytics showing the progression from queries to purchases. Optionally filter by a specific search term or collection.

GET /funnel

Query Parameters:

customerId (required)
context (required): searches or collections
days OR start + end (required): Time range
term (optional): Filter analytics for a specific search term or collection name
label (optional): Scope to a single namespace. See Label and the Labels endpoint

Example Request (All Terms):

curl "https://ecom.marqo-ep.ai/api/v1/analytics/funnel?customerId=a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d&days=3&context=searches" \
  -H "Authorization: Bearer {api_key}"

Example Request (Specific Term):

curl "https://ecom.marqo-ep.ai/api/v1/analytics/funnel?customerId=a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d&days=3&context=searches&term=technology" \
  -H "Authorization: Bearer {api_key}"

Response:

{
  "totalQueries": 116375,
  "totalClicks": 28096,
  "totalAddToCarts": 21037,
  "totalPurchases": 17296
}

Response Fields:

totalQueries: Total queries at the top of the funnel
totalClicks: Number of result clicks
totalAddToCarts: Number of add-to-cart actions
totalPurchases: Number of completed purchases at the bottom of the funnel

Time Series Analytics

Returns time-series data for a specific metric over the specified period. Optionally filter by a specific search term or collection.

GET /time-series

Query Parameters:

customerId (required)
context (required): searches or collections
days OR start + end (required): Time range
metric (required): One of the metrics listed in the Metrics Reference section
term (optional): Filter analytics for a specific search term or collection name
label (optional): Scope to a single namespace. See Label and the Labels endpoint

Example Request (All Terms):

curl "https://ecom.marqo-ep.ai/api/v1/analytics/time-series?customerId=a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d&days=3&context=searches&metric=addToCartRate" \
  -H "Authorization: Bearer {api_key}"

Example Request (Specific Term):

curl "https://ecom.marqo-ep.ai/api/v1/analytics/time-series?customerId=a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d&days=3&context=searches&metric=addToCartRate&term=technology" \
  -H "Authorization: Bearer {api_key}"

Response:

{
  "datapoints": [
    { "timestamp": "2025-11-25T00:00:00Z", "value": 0.0 },
    { "timestamp": "2025-11-25T01:00:00Z", "value": 0.0 },
    { "timestamp": "2025-11-25T02:00:00Z", "value": 0.0 },
    { "timestamp": "2025-11-25T03:00:00Z", "value": 0.0 }
  ]
}

Response Format:

Returns a JSON object with an array of datapoints
Each datapoint contains a timestamp (ISO 8601 datetime) and value for that time interval
Time series data is provided in UTC timezone
Granularity automatically adjusts based on the time period:
- Hourly: For time periods up to 100 hours
- Daily: For time periods between 100 hours and 100 days
- Weekly: For time periods between 100 days and 100 weeks
- Monthly: For time periods between 100 weeks and 100 months
- Yearly: For time periods greater than 100 months

Error Responses

The API uses standard HTTP status codes:

Status Code	Description
200	Success
400	Bad Request - Invalid parameters or validation error
403	Forbidden - Invalid account permissions
404	Not Found - Resource not found
500	Internal Server Error

Error Response Format:

{
  "detail": "Error message describing what went wrong"
}

Common Validation Errors

Cannot use days with start or end: You must use either days OR the start/end combination, not both
Must use start and end together: If you provide start, you must also provide end, and vice versa
Missing time range: You must provide either days or both start and end
End must be greater than start: When using start and end, the end timestamp must be after the start timestamp
Invalid timestamp format: Timestamps must be in ISO 8601 format (e.g., 2025-01-01T00:00:00Z)

Data Freshness

The API performs background file synchronization every 15 minutes to ensure data freshness. Analytics data may have a delay of up to 15 minutes from real-time events.

Best Practices

URL Encoding

Always URL-encode search terms in query parameters. For example, "lower third" becomes "lower%20third".

Example:

curl "https://ecom.marqo-ep.ai/api/v1/analytics/overview?customerId=...&term=lower%20third" \
  -H "Authorization: Bearer {api_key}"

Time Ranges

Use days for recent data
Use start/end for specific historical periods

Limit Parameter

Start with smaller limits (e.g., 50) and increase as needed for the /terms endpoint.

Error Handling

Implement retry logic for 5xx errors with exponential backoff.

Rate Metrics

When analyzing rates (CTR, conversion rate), remember they are decimal values (0.241 = 24.1%).

Time Series Granularity

Time series data granularity automatically adjusts based on the selected time period:

Hourly (≤100 hours): Ideal for short-term analysis and real-time monitoring
Daily (100 hours - 100 days): Best for weekly and monthly trend analysis
Weekly (100 days - 100 weeks): Suitable for quarterly and annual comparisons
Monthly (100 weeks - 100 months): Best for multi-year trend analysis
Yearly (>100 months): For long-term historical patterns

All time series data is provided in UTC timezone.

CORS Configuration

The API supports Cross-Origin Resource Sharing (CORS) for browser-based applications. Only GET requests are supported through CORS.

Base URL​

Authentication​

Common Parameters​

Customer ID​

Time Range Parameters​

Context Type​

Term Filter​

Label​

Metrics Reference​

Endpoints​

Get Available Accounts​

Labels​

Overview Analytics​

Search Terms Analytics​

Funnel Analytics​

Time Series Analytics​

Error Responses​

Common Validation Errors​

Data Freshness​

Best Practices​

URL Encoding​

Time Ranges​

Limit Parameter​

Error Handling​

Rate Metrics​

Time Series Granularity​

CORS Configuration​

Base URL

Authentication

Common Parameters

Customer ID

Time Range Parameters

Context Type

Term Filter

Label

Metrics Reference

Endpoints

Get Available Accounts

Labels

Overview Analytics

Search Terms Analytics

Funnel Analytics

Time Series Analytics

Error Responses

Common Validation Errors

Data Freshness

Best Practices

URL Encoding

Time Ranges

Limit Parameter

Error Handling

Rate Metrics

Time Series Granularity

CORS Configuration