--- title: "Get experience timeseries" method: POST path: "/v25-10-beta/analytics/experience/{experienceId}/timeseries" tags: ["Fetch Experience Data"] --- # Get experience timeseries `POST /v25-10-beta/analytics/experience/{experienceId}/timeseries` ## Request - Base URL: `https://api.intelligems.io` - URL: `https://api.intelligems.io/v25-10-beta/analytics/experience/{experienceId}/timeseries` - Auth: API key in header `intelligems-access-token` - TypeScript: (a function with typed inputs; its response is checked against the schema) 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. - Clamping only applies to a window that **overlaps** the experience lifetime. A window that falls entirely outside it is rejected rather than clamped: HTTP `400` with `{ "error": "Requested time range falls outside the experience lifetime" }`. - `startTs` must be strictly before `endTs`. An inverted range returns HTTP `400` with `{ "error": "Start time must be before end time" }`. **Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s. ## Path parameters - `experienceId` string, uuid, required ## Request body - object - `startTs` string: Optional analysis start timestamp as a 10-digit Unix epoch string in seconds. Defaults to the experience start date. - `endTs` string: Optional analysis end timestamp as a 10-digit Unix epoch string in seconds. Defaults to now or the experience end date. - `granularity` 'hour' | 'day' | 'week' | 'month': Time bucket granularity. Supported values: hour, day, week, month. Defaults to day. - `mode` 'cumulative' | 'noncumulative': Time series mode. Use 'cumulative' for running totals or 'noncumulative' for per-bucket values. Defaults to cumulative. - `metrics` string[]: Array of metric names to include in the response. When omitted, defaults to conversion_rate, net_revenue_per_visitor, and gross_profit_per_visitor. Profit metrics (e.g. gross_profit_per_visitor) require COGS to be configured for the store; when COGS are not configured (cogsConfigured is false) their values are null. Check the top-level cogsConfigured / cogsCoveragePct fields. - `filters` object: Optional analytics filters object. Supports device, visitor, traffic source, country, product, and targeting filters. Analytics filters object for narrowing experience/experiment result data. - `deviceType` 'any' | 'mobile' | 'desktop', nullable: Filter by device type. Options: 'any' (disables filter), 'mobile', 'desktop'. Omit or null to include all devices. - `visitorType` 'any' | 'new' | 'returning', nullable: Filter by visitor type. Options: 'any' (disables filter), 'new', 'returning'. Omit or null to include all visitors. - `customerType` 'new' | 'returning', nullable: Filter experiment analytics by customer type. Options: 'new', 'returning'. Omit or null to include all customers. - `sourceSitesOrChannels` string[]: Filter by traffic source channels. These 25 values are the complete accepted set — the channels the analytics service buckets sessions and orders into — and any other value is rejected with a 400: 'Instagram', 'Facebook', 'Google', 'Twitter', 'TikTok', 'Youtube', 'Klaviyo', 'Attentive', 'Postscript', 'Paid Shopping', 'Paid Search', 'Paid Social', 'Paid Video', 'Display', 'Paid Other', 'Organic Shopping', 'Organic Social', 'Organic Video', 'Organic Search', 'Other', 'Referral', 'Affiliate', 'SMS', 'Email', 'Direct'. Omit or pass an empty array for all channels — there is no 'any' sentinel. - `urlParam` object: Filter by URL query parameter. Object with: queryParam (string|null — the parameter name), queryParamValue (string|null — the value to match), queryParamFilterType (match operator|null: 'equals', 'contains', 'startsWith', 'endsWith', 'doesNotEqual', 'doesNotContain', 'doesNotStartWith', 'doesNotEndWith', 'isNull', 'isNotNull'). REQUIRED COMBINATIONS (enforced with a 400): when queryParamFilterType is set, queryParam must be a non-empty string; every operator except 'isNull'/'isNotNull' also requires a non-empty queryParamValue; 'isNull'/'isNotNull' take no value, so leave queryParamValue null. Omit all three fields to apply no query-parameter filter. - `queryParam` string, nullable, required - `queryParamValue` string, nullable, required - `queryParamFilterType` 'equals' | 'contains' | 'startsWith' | 'endsWith' | 'doesNotEqual' | 'doesNotContain' | 'doesNotStartWith' | 'doesNotEndWith' | 'isNull' | 'isNotNull', nullable, required - `landingPage` object, nullable: DEPRECATED — use landingPageFilters instead, which supports multiple values and an and/or operator. This single-path filter is retained for backwards compatibility and still works, but new integrations should use landingPageFilters. Filter by landing page URL path. Object with: landingPageUrlPath (string|null — the path to match), landingPageUrlPathFilterType (match operator|null: 'equals', 'contains', 'startsWith', 'endsWith', 'doesNotEqual', 'doesNotContain', 'doesNotStartWith', 'doesNotEndWith', 'isNull', 'isNotNull'). REQUIRED COMBINATIONS (enforced with a 400): every operator except 'isNull'/'isNotNull' requires a non-empty landingPageUrlPath; 'isNull'/'isNotNull' take no path, so leave landingPageUrlPath null; and a landingPageUrlPath with no landingPageUrlPathFilterType is rejected. Omit both fields to apply no landing-page filter. - `landingPageUrlPath` string, nullable, required - `landingPageUrlPathFilterType` 'equals' | 'contains' | 'startsWith' | 'endsWith' | 'doesNotEqual' | 'doesNotContain' | 'doesNotStartWith' | 'doesNotEndWith' | 'isNull' | 'isNotNull', nullable, required - `landingPageFilters` object[]: Filter by landing page URL path with multi-value support. Recommended landing page filter (supersedes the deprecated landingPage field). Array of filter items, each with: filterType (match operator: 'equals', 'contains', 'startsWith', 'endsWith', 'doesNotEqual', 'doesNotContain', 'doesNotStartWith', 'doesNotEndWith', 'isNull', 'isNotNull') and values (array of strings to match against). REQUIRED COMBINATIONS (enforced with a 400): every operator except 'isNull'/'isNotNull' requires at least one non-empty entry in values — an omitted, empty, or blank-only values array is rejected rather than silently matching nothing. 'isNull'/'isNotNull' take no values; omit the field (an empty array is tolerated, real values are rejected). Multiple values within a single item are OR'd. How items in the array are combined is controlled by landingPageFiltersOperator. - `values` string[] - `filterType` 'equals' | 'contains' | 'startsWith' | 'endsWith' | 'doesNotEqual' | 'doesNotContain' | 'doesNotStartWith' | 'doesNotEndWith' | 'isNull' | 'isNotNull', required - `landingPageFiltersOperator` 'or' | 'and': How multiple items in landingPageFilters are combined. 'or' (default) — session matches if any filter item matches. 'and' — session must match every filter item. - `userBehavior` object: Filter by visitor browsing behavior. Object with optional boolean flags: viewedCheckout, addedToCart, viewedProductPage, viewedCollectionPage. Set a flag to true to include only visitors who performed that action. Omit or null for flags you don't want to filter on. Multiple true flags are combined with AND logic. - `viewedCheckout` boolean, nullable - `addedToCart` boolean, nullable - `viewedProductPage` boolean, nullable - `viewedCollectionPage` boolean, nullable - `countryCodes` string[]: Filter by ISO 3166-1 alpha-2 country codes (e.g. ['US', 'GB', 'CA']). Omit or pass empty array for all countries. - `countryCodesFilterType` 'include' | 'exclude': How countryCodes should be matched: 'include' (only visitors in the listed countries) or 'exclude' (visitors in any country except the listed ones). Defaults to 'include' when omitted. Requires countryCodes to be a non-empty array. - `maxZScore` union: Maximum Z-score threshold for outlier filtering on order revenue. Visitors with orders whose Z-score exceeds this value are excluded. Accepts number or numeric string. Null or omit to disable outlier filtering. - number - string - `triggeredCustomEvents` string[]: Filter by custom event identifiers that visitors must have triggered. Requires customEventsFilterType to be set to control matching logic. Has no effect without customEventsFilterType. Pull merchant-defined identifiers from the GET https://api.intelligems.io/v25-10-beta/experiences/{experienceId} endpoint > experienceCustomMetrics > customEvent > identifier field. Three additional identifiers are always available with no Events Manager setup, synthesized server-side rather than looked up from a stored custom event: 'checkout_block_viewed', 'onsite_upsell_viewed', 'post_purchase_offer_viewed'. Note: the analytics UI's filter drawer groups these three visually under 'Reached Checkout Stage' alongside the checkout funnel-stage options, but they are NOT reachedCheckoutStage values — pass them here, in triggeredCustomEvents, not in reachedCheckoutStage. - `customEventsFilterType` 'any' | 'all' | 'none': How triggeredCustomEvents should be matched: 'any' (visitor triggered at least one), 'all' (visitor triggered every listed event), 'none' (visitor triggered none of the listed events). Requires triggeredCustomEvents to be a non-empty array. - `reachedCheckoutStage` 'started' | 'contact_info_submitted' | 'address_info_submitted', nullable: Filter to visitors who reached at least the given checkout stage. Options: 'started', 'contact_info_submitted', 'address_info_submitted'. Omit or null to not filter by checkout stage. Note: 'checkout_block_viewed', 'onsite_upsell_viewed', and 'post_purchase_offer_viewed' are NOT valid values here for experience-level analytics — despite appearing next to these stages in the analytics UI's filter drawer, filter on them via triggeredCustomEvents instead (see that field's description). - `minNetRevenue` union: Minimum order net revenue to include (inclusive). Accepts number or numeric string. Omit or null to not apply a minimum. - number - string - `maxNetRevenue` union: Maximum order net revenue to include (inclusive). Accepts number or numeric string. Omit or null to not apply a maximum. - number - string - `minShippingRevenue` union: Minimum shipping revenue to include (inclusive). Accepts number or numeric string. Omit or null to not apply a minimum. - number - string - `maxShippingRevenue` union: Maximum shipping revenue to include (inclusive). Accepts number or numeric string. Omit or null to not apply a maximum. - number - string - `shippingMethods` string[]: Filter by shipping method names. Only orders using one of these methods are included. - `onlyProductIds` string[], nullable: Filter to only include specific Shopify product IDs (numeric strings). - `landingPageTypes` string[]: Filter sessions by landing page types. An array of values from: 'PDP', 'Collection', 'Content', 'Blog', 'Homepage', 'Search', 'Cart', 'Other'. Omit or null to include all landing page types. - `experimentProductsOnly` boolean, nullable: When true, only include products that are part of the experiment. Only applies when analyzing an experience/experiment. - `onlyProductHandles` string[], nullable: Filter to only include specific Shopify product handles. ## Response `200` OK - object - `currency` string, required: ISO 4217 currency code for monetary values (e.g. 'USD'). - `granularity` 'hour' | 'day' | 'week' | 'month', required: The granularity used for time bucketing. - `mode` 'cumulative' | 'noncumulative', required: The time series mode used (cumulative or discrete). - `experienceId` string, required: The UUID of the experience. - `experienceName` string, required: The display name of the experience. - `variations` object[], required: Array of variation metadata objects. Each contains the variation id, name, and whether it is the control. - `id` string, required - `name` string, required - `isControl` boolean, required - `cogsConfigured` boolean: Whether cost of goods sold (COGS) is configured for the store. When false, profit metric values (e.g. gross_profit_per_visitor) are null in every time bucket because they cannot be computed. Only present when the request includes a profit metric. - `cogsCoveragePct` number: Fraction of revenue (0-1) backed by line items that have COGS data. 0 means profit metrics are unavailable and returned as null; a value between 0 and 1 means profit reflects partial COGS coverage; 1 means full coverage. Only present when the request includes a profit metric. - `segments` object, required: Time series data keyed by variation name. Each segment contains a data array of time-bucketed metric values. Profit metric values are null in buckets without COGS coverage; see cogsConfigured / cogsCoveragePct. ## Other responses - `429`: Too Many Requests ## Changes - **2026-11-06** `7b769b2f90b1`: 1 info - endpoint added [Operation history](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta/changes/v25-10-beta/analytics/experience/:experienceId/timeseries/post.md) --- [API](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta.md) - [All operations](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta/llms.txt) - [OpenAPI document](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta/revisions/ca5d7c5b1bb6?raw)