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

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

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

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)

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

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

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.