For the complete documentation index, see llms.txt. This page is also available as Markdown.
Fetch Experience Data
post
Retrieve per-variant time series data for an experience (A/B test).
POST /analytics/experience/{experienceId}/timeseries
Returns metric values over time for each variation in the experiment, segmented by variation name. Use this data to compare variant performance over time and compute signals like "win-day count" (how many periods a variant beat control).
Parameters
experienceId (path) — required. UUID of the experience.
granularity — optional time bucketing: hour, day (default), week, or month.
mode — cumulative (default, running totals) or noncumulative (per-bucket values).
metrics — optional array of metric enum values to include (see table below). Defaults to conversion_rate, net_revenue_per_visitor, gross_profit_per_visitor.
startTs — optional 10-digit epoch timestamp in seconds. Defaults to experience start date.
endTs — optional 10-digit epoch timestamp in seconds. Defaults to now or experience end date.
filters — optional analytics filters object. See below and the Filters Reference for available fields.
Available Metrics
Pass one or more of these enum values in the metrics array:
Value
Description
conversion_rate
Conversion rate
net_revenue_per_visitor
Revenue per visitor (RPV)
gross_profit_per_visitor
Profit per visitor (PPV)
aov
Average order value
n_visitors
Visitor count
n_orders
Order count
net_revenue
Total net revenue
Filters
This endpoint accepts the same filters as POST /analytics/resource/{experienceId}. Key filters include:
Field
Type
Description
deviceType
string
"any", "mobile", or "desktop"
visitorType
string
"any", "new", or "returning"
countryCodes
string[]
ISO 3166-1 alpha-2 codes, e.g. ["US", "GB"]
sourceSitesOrChannels
string[]
Traffic channel names (see Filters Reference)
userBehavior
object
Visitor behavior filter (see sub-fields below)
experimentProductsOnly
boolean
Only include products in the experiment (target products)
onlyProductIds
string[]
Shopify product IDs to include
onlyProductHandles
string[]
Shopify product handles to include
userBehavior sub-fields
All fields are optional booleans. Set to true to filter to only visitors who performed that action.
Field
Description
viewedProductPage
Visitor viewed a product page
viewedCollectionPage
Visitor viewed a collection page
addedToCart
Visitor added an item to cart
viewedCheckout
Visitor reached checkout
See the Filters Reference section for the full list of available filter fields.
Response Structure
The response contains a segments object keyed by variation name. Each segment has a data array of time-bucketed metric values. A variations array provides metadata including which variation is the control.
Each data point includes a dt field as a formatted date string (not Unix epoch). Format depends on granularity:
hour / day: "YYYY-MM-DD HH:mm:ss"
week / month: "YYYY-MM-DD"
Date Range Behavior
When startTs and endTs are omitted, the date range defaults to the experience's full lifetime (start date through end/pause date or now).
If the experience is paused or ended, the response is automatically truncated at the pause/end date — no data points are returned after that point.
If the provided startTs is before the experience start date, it is clamped to the experience start. Similarly, endTs is clamped to the experience end/pause date.
Retrieve analytics data for a specific experience, including metrics, variations, and optionally graph images.
This legacy GET endpoint is deprecated, intentionally limited to the original query-parameter contract, and kept only as a beta compatibility path. Use the POST variant on the same path for all new integrations. The GET endpoint will be removed when the beta version ends.
Valid view values are overview, audience, and post_test. The value summary is not supported. When view=audience, you must also provide the audience query parameter.
The legacy start and end query parameters must be 10-digit Unix epoch timestamps in seconds, not milliseconds.
Response payloads include impact (object with est_monthly_revenue_increase: the projected 30-day revenue lift from the best non-control variation vs. control, or null when there is insufficient data) plus distribution and ordering helpers such as audienceOrder, histogram, kde, and cdf.
Query parameters
graphsstringOptional
Comma-separated list of graph IDs to include in response. Applies to "view=overview" and "view=audience" requests. On this deprecated GET endpoint an unrecognized ID is silently ignored and "graphs" comes back empty; the POST variant rejects it with a 400 instead. Available options:
abandoned_cart_rate
abandoned_checkout_rate
add_to_cart_rate
avg_discount_per_all_orders
avg_discount_per_discounted_order
avg_product_revenue_per_unit
avg_units_per_order
checkout_address_submitted_rate
checkout_begin_rate
checkout_enter_contact_info_rate
conversion_rate
net_product_revenue_per_order
net_revenue_from_post_purchase_offer
net_revenue_from_upsell
net_revenue_per_order
net_revenue_per_visitor
net_shipping_revenue_per_order
pct_orders_free_shipping
pct_orders_with_post_purchase_offer
pct_orders_with_upsell
pct_subscription_orders
profit_per_order
profit_per_visitor
subscription_orders_per_visitor
subscription_product_revenue_per_order
subscription_profit_per_visitor
subscription_revenue_per_order
subscription_revenue_per_visitor
view_collection_page_rate
view_product_page_rate
graphOutputstring · enumOptional
Output format for graph images. 'png' (default) uploads to S3 and returns a URL. 'base64' returns the raw base64-encoded PNG data inline.
Default: pngPossible values:
viewstring · enumOptional
Resource view to analyze. Supported values are 'overview' for variation-level metrics, 'audience' for a breakdown by the selected audience dimension, and 'post_test' for post-test metrics (customers who converted during the test, tracked by their purchase behavior after that conversion, split by variation).
Default: overviewPossible values:
audiencestring · enumOptional
Audience breakdown dimension. Required when view is audience. Optional when view is post_test (returns the post-test breakdown by the selected dimension). Not allowed when view is overview. Use one of the supported audience fields such as device_type, visitor_type, or source_channel.
Possible values:
analyticsViewTypestring · enumOptional
Optional analytics view preset used by the backend when building the analysis request.
Possible values:
endstringOptional
Optional analysis end timestamp as a 10-digit Unix epoch string in seconds (not milliseconds).
startstringOptional
Optional analysis start timestamp as a 10-digit Unix epoch string in seconds (not milliseconds).
Responses
200
OK
application/json
get/v25-10-beta/analytics/resource/{experienceId}
200
OK
post
Analyze analytics data for a specific experience using a POST request body for filters and request settings.
The legacy GET /analytics/resource/{experienceId} endpoint remains available only as a beta compatibility path for existing integrations. It is deprecated, limited to its original query-parameter contract, and will be removed when the beta version ends.
Valid view values are overview, audience, and post_test. The value summary is not supported. When view is audience, you must also provide the audience field. When view is post_test, the audience field is optional (supply it to break the post-test metrics down by that dimension). The audience field is not allowed when view is overview.
Use startTs and endTs in the request body to match the backend contract. These values must be 10-digit Unix epoch timestamps in seconds, not milliseconds. Use the filters object for all advanced filtering instead of query parameters.
Audience breakdowns (view=audience)
When view is audience, metrics are segmented by the selected audience dimension — one row per (variation × segment) — ordered by visitor count.
Only the high-cardinality dimensions country_code and landing_page_full_path are limited by default: when you omit topN, they return the top 10 segments by visitor count. The other dimensions — device_type, visitor_type, source_channel, and source_site — are low-cardinality and are not limited by default; they return all their segments.
Use the topN field to control this. It accepts an integer between 1 and 1000:
Omit topN — country_code and landing_page_full_path return their top 10; all other dimensions return every segment.
Set topN to a value between 1 and 1000 — caps the selected dimension at that many top segments (applies to any dimension). Values above 1000 are rejected.
The 1000 maximum bounds the response size and query cost, so a breakdown can never degrade into the unbounded scan that caused earlier timeouts. This is why landing_page_full_path, which can have thousands of distinct URLs, is never returned in full — request the top segments you need (up to 1000).
Post-test metrics (view=post_test)
Post-test metrics look at customers who converted during the test and track their purchase behavior after that conversion, split by variation — answering "which variation produced more valuable customers over time?". Tracking is at the customer level (not cookie). Order filters narrow the in-test customer set only; they do not constrain the post-test orders.
The includeInTestOrders field (boolean, default true) controls whether in-test orders are folded into the metrics:
true (default) — returns all three families. total_* is the LTV view (post-test + in-test combined), and the in-test eso_* family is included.
false — the eso_* family is omitted entirely, and total_* collapses to equal post_* (since no in-test orders are folded in). The post_* family and headcounts are returned as usual.
Headcounts and rates are always present: n_visitors, n_customers, customers_per_visitor, pct_repeat_customers.
Every metric is { value }. There is no pct_change field.
uplift is only present on rate metrics. On a non-control variation, per-visitor and per-customer rate metrics additionally carry uplift: { value } — the ratio vs control as a fraction. Two rules govern it:
The control variation never carries uplift.
Raw counts and absolute totals never carry uplift, on any variation. That covers n_visitors, n_customers, n_post_orders, n_eso_orders, n_total_orders, post_net_revenue, post_gross_profit, eso_net_revenue, eso_gross_profit, total_net_revenue, and total_gross_profit — all of which are always bare { value }. Compute a comparison on those yourself if you need one.
The metrics that do carry uplift are the eighteen *_per_visitor / *_per_customer rates across the three families (six per family — orders, revenue, and profit, each per visitor and per customer), plus customers_per_visitor and pct_repeat_customers. That is twenty uplift-carrying fields on a non-control variation when includeInTestOrders is true, and fourteen when it is false (the eso_* family drops out, taking six of the rates with it).
Metric families:
post_* — post-test orders only (after the customer's in-test conversion): n_post_orders, post_net_revenue, post_gross_profit, post_orders_per_visitor, post_revenue_per_visitor, post_profit_per_visitor, post_orders_per_customer, post_revenue_per_customer, post_profit_per_customer.
eso_* — in-test ("experiment span") orders, only when includeInTestOrders=true: n_eso_orders, eso_net_revenue, eso_gross_profit, eso_orders_per_visitor, eso_revenue_per_visitor, eso_profit_per_visitor, eso_orders_per_customer, eso_revenue_per_customer, eso_profit_per_customer.
total_* — post + in-test combined (LTV view): n_total_orders, total_net_revenue, total_gross_profit, total_orders_per_visitor, total_revenue_per_visitor, total_profit_per_visitor, total_orders_per_customer, total_revenue_per_customer, total_profit_per_customer. Always present, but when includeInTestOrders=false these values equal the corresponding post_* values.
When view=post_test is combined with audience, each metric row additionally carries an audience key (the bucket value, e.g. "mobile"), with one row per (variation × audience value), and audienceOrder is populated.
Graphs
When requesting graphs via the graphs object, graphs.ids accepts an array of metric identifiers.
The authoritative list of valid values is the graphs.ids enum in this endpoint's request schema, which is generated from the metric catalogue — see the schema for the current set. It is deliberately not duplicated in prose here: the previous hand-maintained list had fallen four values behind the enum (net_revenue_from_upsell, pct_orders_with_upsell, net_revenue_from_post_purchase_offer, pct_orders_with_post_purchase_offer were all accepted but undocumented).
Note: revenue_per_visitor is not a valid graph ID — use net_revenue_per_visitor instead.
Invalid IDs are rejected with a 400 validation error on this endpoint. The deprecated GET /analytics/resource/{experienceId} instead silently drops them and returns graphs: [].
Each graph object in the response includes id (string), key (the original metric key), type (chart type, e.g. "bar"), title (display title), and either url (CDN URL when outputFormat is "png") or data (base64-encoded PNG when outputFormat is "base64").
Additional Response Fields
Response payloads include impact (object with est_monthly_revenue_increase: the projected 30-day revenue lift from the best non-control variation vs. control, or null when there is insufficient data) plus the ordering helper audienceOrder (segment display ordering, populated only for view=audience and for view=post_test with an audience; an empty array otherwise).
histogram, kde, and cdf are also always present alongside the primary metrics and variations arrays, but this endpoint does not currently populate them — they are returned as empty arrays regardless of view, analyticsViewType, or date range. Do not build on them here. For an order-value distribution, use POST /analytics/sitewide/order-distribution, which returns a populated orderValueDistribution.kernel_density_estimate and orderValueDistribution.cumulative_distribution_function.
audienceOrder
audienceOrder is a display ordering hint, not the order of the metrics array. The metrics rows come back in the order the analytics store returned them, so do not assume the two line up — sort or index by the audience key if you need them to.
The ordering is by total visitors summed across all variations, descending. Two consequences:
It will not match a descending sort of any single variation's n_visitors, because the sort key is the cross-variation total.
"Other" and "Unknown" are pinned to the end regardless of size, in that order, so they can appear after segments with fewer visitors.
Resource view to analyze. Supported values are 'overview' for variation-level metrics, 'audience' for a breakdown by the selected audience dimension, and 'post_test' for post-test metrics (customers who converted during the test, tracked by their purchase behavior after that conversion, split by variation).
Default: overviewPossible values:
audiencestring · enumOptional
Audience breakdown dimension. Required when view is audience. Optional when view is post_test (returns the post-test breakdown by the selected dimension). Not allowed when view is overview. Use one of the supported audience fields such as device_type, visitor_type, or source_channel.
Possible values:
includeInTestOrdersbooleanOptional
Only applies when view is post_test. Controls whether in-test orders are folded into the metrics. When true (default), the in-test eso_* family is included and total_* is the LTV view (post-test + in-test combined). When false, the eso_* family is omitted and total_* collapses to equal post_*. The post_* family and headcounts/rates are always returned.
Default: true
analyticsViewTypestring · enumOptional
Optional analytics view preset used by the backend when building the analysis request.
Possible values:
endTsstringOptional
Optional analysis end timestamp as a 10-digit Unix epoch string in seconds (not milliseconds). Maps directly to the backend endTs field.
startTsstringOptional
Optional analysis start timestamp as a 10-digit Unix epoch string in seconds (not milliseconds). Maps directly to the backend startTs field.
topNinteger · max: 1000Optional
Only applies when view is audience. Caps the breakdown to the top N segments by visitor count, where N is an integer between 1 and 1000. By default, only the high-cardinality dimensions country_code and landing_page_full_path are capped at 10; the other dimensions (device_type, visitor_type, source_channel, source_site) are low-cardinality and returned in full. Set a value between 1 and 1000 to override the cap for any dimension. The 1000 maximum bounds the response size and query cost — this is why landing_page_full_path, which can have thousands of distinct URLs, is never returned in full.
testResultbooleanOptional
When true, compute and return the opt-in test verdict alongside the overview. The verdict is returned on the response as testResult.
The response body is wrapped in an experience key:
{"experience":{"id":"YOUR_EXPERIENCE_ID"}}
Compared with GET /experiences-list, this response additionally includesexperienceCustomMetrics, experienceIntegrations, experienceKeyMetrics, shippingTestMethodDefinitions, and shippingCarrierProvider.
It omitshasSchedule and history, which only list items carry. variations is present on both, but this response carries the full variation shape rather than the list's reduced one.
Tracking who changed what
This endpoint exposes two complementary audit trails:
experienceActions (always returned) — lifecycle state transitions (start, pause, end, delete, reset). Each entry includes a performedBy field with the email of the user who triggered the action, resolved from History records by matching action type and timestamp within a 5-minute window. performedBy is null when no matching History record is found.
changeLog (opt-in, see includeChangeLog below) — audit trail of deployed-config changes that touched this experience. Each entry groups diffs by entity type (experience, variations, offers, onsiteEdits, onsiteInjections, redirects, checkoutBlocks, audiences, pageTargeting) and identifies the deployer via performedBy. Capped at the 20 most recent entries, newest first.
Note that the two trails format performedBy differently: experienceActions returns a bare email ("jane@example.com"), while changeLog returns a display name with the email in angle brackets ("Jane Doe <jane@example.com>"). Parse the changeLog form before treating it as an address.
Query Parameters
All query parameters are optional.
includeChangeLog — boolean, defaults to false. When true, the response includes a top-level changeLog array on the experience.
Note on history
List items on GET /experiences-list include a history array containing raw user-action records with broader action types (saveExperience, duplicateExperience, archiveCampaign, etc.) and full user objects. The single-experience response does not include this history field — use experienceActions for lifecycle events and ?includeChangeLog=true for config-deploy diffs instead.
When true, include a top-level changeLog array on the experience containing per-deploy diffs of entities that were modified (experience, variations, offers, onsiteEdits, onsiteInjections, redirects, checkoutBlocks, audiences, pageTargeting). Each entry carries the deployer's email via performedBy. Capped at the 20 most recent deploys, newest first. Defaults to false.
