Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Intelligems External Fetch Experience Data API
version: v25-10-beta
description: Programmatic access to manage Intelligems A/B tests, personalizations, and experiences, to define custom events, and to pull experiment and sitewide analytics for a Shopify store. Authenticate with an API key in the `intelligems-access-token` header.
contact:
name: Intelligems
url: https://docs.intelligems.io/developer-resources/external-api
servers:
- url: https://api.intelligems.io
description: Production
security:
- intelligems_access_token: []
tags:
- name: Fetch Experience Data
paths:
/v25-10-beta/analytics/experience/{experienceId}/timeseries:
post:
tags:
- Fetch Experience Data
description: '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.'
parameters:
- in: path
name: experienceId
schema:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
startTs:
description: Optional analysis start timestamp as a 10-digit Unix epoch string in seconds. Defaults to the experience start date.
type: string
endTs:
description: Optional analysis end timestamp as a 10-digit Unix epoch string in seconds. Defaults to now or the experience end date.
type: string
granularity:
default: day
description: 'Time bucket granularity. Supported values: hour, day, week, month. Defaults to day.'
type: string
enum:
- hour
- day
- week
- month
mode:
default: cumulative
description: Time series mode. Use 'cumulative' for running totals or 'noncumulative' for per-bucket values. Defaults to cumulative.
type: string
enum:
- cumulative
- noncumulative
metrics:
default:
- conversion_rate
- net_revenue_per_visitor
- gross_profit_per_visitor
description: 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.
type: array
items:
type: string
enum:
- conversion_rate
- net_revenue_per_visitor
- gross_profit_per_visitor
- aov
- n_visitors
- n_orders
- net_revenue
filters:
description: 'Optional analytics filters object. Supports device, visitor, traffic source, country, product, and targeting filters.
Analytics filters object for narrowing experience/experiment result data.'
type: object
properties:
deviceType:
description: 'Filter by device type. Options: ''any'' (disables filter), ''mobile'', ''desktop''. Omit or null to include all devices.'
anyOf:
- type: string
enum:
- any
- mobile
- desktop
- type: 'null'
visitorType:
description: 'Filter by visitor type. Options: ''any'' (disables filter), ''new'', ''returning''. Omit or null to include all visitors.'
anyOf:
- type: string
enum:
- any
- new
- returning
- type: 'null'
customerType:
description: 'Filter experiment analytics by customer type. Options: ''new'', ''returning''. Omit or null to include all customers.'
anyOf:
- type: string
enum:
- new
- returning
- type: 'null'
sourceSitesOrChannels:
description: '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.'
type: array
items:
type: string
enum:
- 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
urlParam:
description: '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.'
type: object
properties:
queryParam:
anyOf:
- type: string
- type: 'null'
queryParamValue:
anyOf:
- type: string
- type: 'null'
queryParamFilterType:
anyOf:
- type: string
enum:
- equals
- contains
- startsWith
- endsWith
- doesNotEqual
- doesNotContain
- doesNotStartWith
- doesNotEndWith
- isNull
- isNotNull
- type: 'null'
required:
- queryParam
- queryParamValue
- queryParamFilterType
landingPage:
description: '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.'
deprecated: true
anyOf:
- type: object
properties:
landingPageUrlPath:
anyOf:
- type: string
- type: 'null'
landingPageUrlPathFilterType:
anyOf:
- type: string
enum:
- equals
- contains
- startsWith
- endsWith
- doesNotEqual
- doesNotContain
- doesNotStartWith
- doesNotEndWith
- isNull
- isNotNull
- type: 'null'
required:
- landingPageUrlPath
- landingPageUrlPathFilterType
- type: 'null'
landingPageFilters:
description: '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.'
type: array
items:
type: object
properties:
values:
type: array
items:
type: string
filterType:
type: string
enum:
- equals
- contains
- startsWith
- endsWith
- doesNotEqual
- doesNotContain
- doesNotStartWith
- doesNotEndWith
- isNull
- isNotNull
required:
- filterType
landingPageFiltersOperator:
description: How multiple items in landingPageFilters are combined. 'or' (default) — session matches if any filter item matches. 'and' — session must match every filter item.
type: string
enum:
- or
- and
userBehavior:
description: '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.'
type: object
properties:
viewedCheckout:
anyOf:
- type: boolean
- type: 'null'
addedToCart:
anyOf:
- type: boolean
- type: 'null'
viewedProductPage:
anyOf:
- type: boolean
- type: 'null'
viewedCollectionPage:
anyOf:
- type: boolean
- type: 'null'
countryCodes:
description: Filter by ISO 3166-1 alpha-2 country codes (e.g. ['US', 'GB', 'CA']). Omit or pass empty array for all countries.
type: array
items:
type: string
countryCodesFilterType:
description: '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.'
type: string
enum:
- include
- exclude
maxZScore:
description: 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.
anyOf:
- anyOf:
- type: number
- type: string
- type: 'null'
triggeredCustomEvents:
description: 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 this field from the GET https://api.intelligems.io/v25-10-beta/experiences/{experienceId} endpoint > experienceCustomMetrics > customEvent > identifier field.
type: array
items:
type: string
customEventsFilterType:
description: '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.'
type: string
enum:
- any
- all
- none
reachedCheckoutStage:
description: '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.'
anyOf:
- type: string
enum:
- started
- contact_info_submitted
- address_info_submitted
- type: 'null'
minNetRevenue:
description: Minimum order net revenue to include (inclusive). Accepts number or numeric string. Omit or null to not apply a minimum.
anyOf:
- anyOf:
- type: number
- type: string
- type: 'null'
maxNetRevenue:
description: Maximum order net revenue to include (inclusive). Accepts number or numeric string. Omit or null to not apply a maximum.
anyOf:
- anyOf:
- type: number
- type: string
- type: 'null'
minShippingRevenue:
description: Minimum shipping revenue to include (inclusive). Accepts number or numeric string. Omit or null to not apply a minimum.
anyOf:
- anyOf:
- type: number
- type: string
- type: 'null'
maxShippingRevenue:
description: Maximum shipping revenue to include (inclusive). Accepts number or numeric string. Omit or null to not apply a maximum.
anyOf:
- anyOf:
- type: number
- type: string
- type: 'null'
shippingMethods:
description: Filter by shipping method names. Only orders using one of these methods are included.
type: array
items:
type: string
onlyProductIds:
description: Filter to only include specific Shopify product IDs (numeric strings).
anyOf:
- type: array
items:
type: string
- type: 'null'
landingPageTypes:
description: '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.'
type: array
items:
type: string
enum:
- PDP
- Collection
- Content
- Blog
- Homepage
- Search
- Cart
- Other
experimentProductsOnly:
description: When true, only include products that are part of the experiment. Only applies when analyzing an experience/experiment.
anyOf:
- type: boolean
- type: 'null'
onlyProductHandles:
description: Filter to only include specific Shopify product handles.
anyOf:
- type: array
items:
type: string
- type: 'null'
responses:
'200':
description: OK
headers:
access-control-allow-origin:
schema:
type: string
description: CORS allow-origin header.
access-control-allow-credentials:
schema:
type: string
description: CORS allow-credentials header.
content-type:
schema:
type: string
description: Response content type.
Timing-Allow-Origin:
schema:
type: string
description: Allowed origin for Timing headers.
content:
application/json:
schema:
type: object
properties:
currency:
type: string
description: ISO 4217 currency code for monetary values (e.g. 'USD').
granularity:
type: string
enum:
- hour
- day
- week
- month
description: The granularity used for time bucketing.
mode:
type: string
enum:
- cumulative
- noncumulative
description: The time series mode used (cumulative or discrete).
experienceId:
type: string
description: The UUID of the experience.
experienceName:
type: string
description: The display name of the experience.
variations:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
isControl:
type: boolean
required:
- id
- name
- isControl
additionalProperties: false
description: Array of variation metadata objects. Each contains the variation id, name, and whether it is the control.
cogsConfigured:
description: 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.
type: boolean
cogsCoveragePct:
description: 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.
type: number
segments:
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
data:
type: array
items:
type: object
properties:
dt:
type: string
required:
- dt
additionalProperties:
anyOf:
- type: number
- type: 'null'
required:
- data
additionalProperties: false
description: 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.
required:
- currency
- granularity
- mode
- experienceId
- experienceName
- variations
- segments
additionalProperties: false
summary: Create v25 10 beta analytics experience by experience id timeseries
x-summary-source: derived
operationId: postV2510BetaAnalyticsExperienceByExperienceIdTimeseries
x-operation-id-source: derived
/v25-10-beta/analytics/resource/{experienceId}:
get:
tags:
- Fetch Experience Data
description: '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`.'
deprecated: true
parameters:
- in: query
name: graphs
schema:
description: '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'
type: string
description: '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_sh
# --- truncated at 32 KB (851 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/intelligems/refs/heads/main/openapi/intelligems-fetch-experience-data-api-openapi.yml