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

The recommendation and agentic endpoints take the same context parameter with their own value sets.

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

The agentic time series endpoint counts conversations rather than queries, so it accepts totalConversations in place of totalQueries.

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

Recommendation Analytics

Reports on the recommendation endpoints instead of on searches and collections. There are four routes, mirroring the standard ones:

GET /overview/recommendations
GET /terms/recommendations
GET /funnel/recommendations
GET /time-series/recommendations

Each takes the same customerId, time range and label parameters as its standard counterpart, plus a context parameter that selects which shelf to report on. The type-style searches and collections values do not apply here.

Query Parameters:

customerId (required)
context (required): for-you, complementary or similar
days OR start + end (required): Time range
metric (required on /time-series/recommendations): One of the metrics listed in the Metrics Reference
limit (optional, /terms/recommendations only): Number of terms to return
label (optional): Scope to a single namespace. See Label

Example Request:

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

Each route returns the same response shape as the standard endpoint it mirrors: /overview/recommendations matches Overview Analytics, /funnel/recommendations matches Funnel Analytics, /time-series/recommendations matches Time Series Analytics, and /terms/recommendations matches Search Terms Analytics with each term being a seed product id rather than a search term.

note

The for-you shelf has no seed-product breakdown, so /terms/recommendations is not available for context=for-you.

Agentic Analytics

Reports on conversational agent sessions. Agentic analytics are conversation-shaped rather than query-shaped: they count conversations and messages where the standard endpoints count queries.

GET /agentic/overview
GET /agentic/funnel
GET /agentic/time-series

Query Parameters:

customerId (required)
context (required): chat is the only accepted value
days OR start + end (required): Time range
metric (required on /agentic/time-series): One of the metrics listed in the Metrics Reference, where totalConversations replaces totalQueries

Example Request:

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

/agentic/overview and /agentic/funnel mirror Overview Analytics and Funnel Analytics, reporting conversation counts and per-conversation message statistics alongside the shared click, add-to-cart, conversion and revenue figures. /agentic/time-series mirrors Time Series Analytics.

There is no agentic equivalent of the terms endpoint.

note

Agentic conversation rates are ratios of events to conversations, not to queries. A single conversation can produce several clicks, so these rates can exceed 1.0.

Error Responses

Errors use the same envelope as every other Ecom API endpoint: a JSON body with a single error key.

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

warning

Read the message from error, not from detail. The analytics service reports its own failures under a detail key, but requests to https://ecom.marqo-ep.ai are served through the Ecom API gateway, which copies that text into error before returning it. A client parsing detail reads undefined.

Status Code	Description	Produced by
200	Success	—
400	Invalid parameters or validation error	Analytics service
401	The API key is missing, empty, unknown, or revoked	Gateway
403	The API key does not have access to the requested account	Analytics service
404	Resource not found	Analytics service
500	Unexpected failure	Analytics service
502	The analytics service could not be reached. Safe to retry	Gateway

Status codes raised by the analytics service are relayed unchanged. Codes raised by the gateway are returned before the request reaches the analytics service, so a 401 means the key was rejected at the edge and no analytics query ran.

See Responses and Errors for the error envelope, authentication failures and status codes shared across the whole Ecom API.

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 allows cross-origin requests from any origin, with any request header and any method. Every analytics endpoint is GET, so a request that uses another method returns 404 rather than failing a CORS check.

Calling analytics from a browser means shipping an API key to the browser. Prefer calling these endpoints from your server.

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​

Recommendation Analytics​

Agentic 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

Recommendation Analytics

Agentic 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