--- title: "Get sitewide snapshot" method: POST path: "/v25-10-beta/analytics/sitewide/snapshot" tags: ["Fetch Sitewide Analytics"] --- # Get sitewide snapshot `POST /v25-10-beta/analytics/sitewide/snapshot` ## Request - Base URL: `https://api.intelligems.io` - URL: `https://api.intelligems.io/v25-10-beta/analytics/sitewide/snapshot` - Auth: API key in header `intelligems-access-token` - TypeScript: (a function with typed inputs; its response is checked against the schema) Retrieve sitewide snapshot metrics for a time window. ### Parameters - `start` — optional **ISO 8601 datetime string**. Beginning of the analysis window. Defaults to the start of the week (Monday, store timezone) containing the date one week ago — so the default window spans 7 to 13 days depending on the current weekday. - `end` — optional **ISO 8601 datetime string**. End of the analysis window. Defaults to now (rounded to the cache interval). Period-over-period `pct_change` is computed against the equivalent window immediately preceding `start`. - `feature` — optional metric-set selector object. See below. - `filters` — optional shared sitewide filters object. See the Filters Reference. > **The window is `start` / `end`, not `startTs` / `endTs`.** Every `/analytics/sitewide/*` endpoint takes ISO 8601 datetime strings under `start` and `end`. The epoch-seconds `startTs` / `endTs` pair used by the experience endpoints (`/analytics/resource/{experienceId}`, `/analytics/experience/{experienceId}/timeseries`, `/analytics/experience/{experienceId}/export`) is **not** accepted here: unknown fields are stripped rather than rejected, so a request sending `startTs` / `endTs` returns `200` over this endpoint's **default window** — from the start of the week (Monday, store timezone) one week ago until now — instead of the range you asked for, and nothing in the response flags the substitution. The default differs per sitewide endpoint, so always pass an explicit `start` when you need a specific window. Date-only strings and datetimes without an offset are rejected — send a full datetime with `Z` or an offset (`"2026-06-01T00:00:00Z"`, not `"2026-06-01"` or `"2026-06-01T00:00:00"`). The optional `feature` parameter is an object, not a string enum. It selects which metric set is returned. **These sets belong to this endpoint.** They are not the same as the sets on `POST /analytics/sitewide/timeseries` — the two endpoints compute different metrics, so a set with the same name returns different fields on each. | `feature` | Fields returned | | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `{ "name": "performance" }` | `gross_profit_per_visitor`, `net_revenue_per_visitor`, `conversion_rate`, `aov`, `gross_margin_pct`, `gross_profit`, `net_revenue`, `n_orders`, `n_visitors`, `average_discount`, `pct_revenue_with_cogs` | | `{ "name": "order" }` | `aov`, `n_visitors`, `n_orders`, `median_order_value`, `average_units_per_order`, `pct_orders_with_free_shipping`, `net_shipping_revenue_per_order` | | `{ "name": "conversion" }` | `viewed_collection_page_rate`, `viewed_product_page_rate`, `add_to_cart_rate`, `checkout_begin_rate`, `conversion_rate`, `bounce_rate`, `abandoned_cart_rate`, `abandoned_checkout_rate` | | `{ "name": "audience", "audience": "device_type" }` | The full sitewide metric set, broken out per segment | Omitting `feature` entirely returns the full sitewide metric set in a single `"All"` segment. `median_order_value` and `average_discount` are available only on this endpoint. Conversely, the timeseries endpoint returns per-session rates (`sessions_per_visitor`, `conversion_rate_per_session`, `net_revenue_per_session`, `gross_profit_per_session`) and `cost_of_revenue`, none of which are computed here. ### Response Structure The response is a JSON object keyed by segment name, **not** a flat object with top-level metric fields. When no audience feature is specified (or `feature.name` is `"performance"`, `"order"`, or `"conversion"`), the response contains a single `"All"` key: ```json { "All": { "currency": "USD", "n_visitors": { "value": 52763, "pct_change": 0.12 }, "conversion_rate": { "value": 0.034, "pct_change": -0.05 }, ... } } ``` When `feature.name` is `"audience"`, the response contains one key per audience segment plus a `"__total"` key: ```json { "Desktop": { "currency": "USD", "n_visitors": { "value": 30000, "pct_change": 0.08 }, ... }, "Mobile": { "currency": "USD", "n_visitors": { "value": 22763, "pct_change": 0.18 }, ... }, "__total": { "currency": "USD", "n_visitors": { "value": 52763, "pct_change": 0.12 }, ... } } ``` **A window with no data returns an empty object `{}`** — not `{ "All": {} }` and not a segment map with zeroed metrics. This applies to every feature, including `audience` (no `"__total"` key either). Check that the segment you want is present before reading metrics off it; `response.All.n_visitors.value` will throw on an empty window. Each segment object contains `currency` (string), the COGS metadata fields `cogs_configured` (boolean) and `cogs_coverage_pct` (number), and metric fields. The two `cogs_*` fields are present for the `performance`, `order`, and `audience` features but omitted for `conversion`. Non-suppressed metric fields are objects whose `value` and `pct_change` cells are optional and nullable (`number | null`). `pct_change` represents the percent change versus the comparison period. In audience view, per-segment metrics can also include `pct_impact_to_total_change` (`number | null`). An unavailable calculation is returned as `null`, including percent change when both current and comparison values are zero or when comparison data is missing. For example, `pct_revenue_with_cogs` can return `{ "value": 0, "pct_change": null }` in a populated `performance` response. Null-check individual cells before using them; a present metric object does not guarantee numeric cells. This is separate from the whole-metric profit suppression described below. **`impact_from_visitor_mix_shift` appears on `__total` for ratio metrics only** — within the `audience` field set that means `conversion_rate`, `aov`, `net_revenue_per_visitor`, and `pct_revenue_with_cogs`. (`gross_margin_pct` is a ratio but is not part of the `audience` field set, so it never carries this field.) Additive metrics (`n_visitors`, `n_orders`, `net_revenue`, `gross_profit`, and the rest of the counts and totals) never carry it, so expect it on a minority of the fields in a `__total` object rather than on all of them. It is the residual of the total percent change that is not attributable to any individual segment — the part explained by the mix of visitors shifting between segments — which is only meaningful for a weighted average, not for a sum. Alongside `currency`, every segment also includes two scalar COGS-status fields (not `{ value, pct_change }` objects): `cogs_configured` (boolean — whether cost-of-goods data is configured for the store) and `cogs_coverage_pct` (number, a fraction in `[0, 1]` for the share of revenue with COGS data). COGS-dependent profit metrics are returned as a bare `null` (not a `{ value, pct_change }` object) when `cogs_configured` is `false`. On this endpoint that is **four** fields: - `gross_profit` - `gross_profit_per_visitor` - `gross_margin_pct` - `oli_net_product_revenue_with_cogs` Clients must null-check all four before reading `.value` / `.pct_change`. Within this endpoint the suppression is applied to any profit metric, so the same rule holds for other profit fields (for example `gross_profit_per_order`, `product_profit`, `subscription_gross_profit`) on the feature sets that return them. **Suppression is per endpoint, not global.** It is applied on this endpoint, on `POST /analytics/sitewide/timeseries`, and on the experience analytics endpoints (`POST /analytics/resource/{experienceId}` and `POST /analytics/experience/{experienceId}/timeseries`, which report the same condition as `cogsConfigured` / `cogsCoveragePct`). It is **not** applied to `orderBreakdown` on `POST /analytics/sitewide/order-distribution` — see that endpoint's note before using its profit fields. ### Metric Availability by Feature - `performance` returns this KPI subset: `n_visitors`, `conversion_rate`, `n_orders`, `aov`, `net_revenue`, `gross_profit`, `gross_profit_per_visitor`, `net_revenue_per_visitor`, `gross_margin_pct`, `average_discount`, `pct_revenue_with_cogs`. - `order` returns this subset: `aov`, `n_visitors`, `n_orders`, `median_order_value`, `average_units_per_order`, `pct_orders_with_free_shipping`, `net_shipping_revenue_per_order`. - `conversion` returns this subset: `viewed_collection_page_rate`, `viewed_product_page_rate`, `add_to_cart_rate`, `checkout_begin_rate`, `conversion_rate`, `bounce_rate`, `abandoned_cart_rate`, `abandoned_checkout_rate`. - `audience` returns per-segment metrics plus a `__total` key: `n_sessions`, `n_visitors`, `n_orders`, `gross_revenue`, `net_revenue`, `order_cogs`, `conversion_rate`, `aov`, `net_revenue_per_visitor`, `shipping_cost`, `transaction_fees`, `tax`, `gross_profit`, `gross_profit_per_visitor`, `oli_net_product_revenue_with_cogs`, `oli_net_product_revenue`, `pct_revenue_with_cogs`. **Rate Limit:** 10 requests per 30s window, refilling 5 tokens every 30s. ## Request body - object - `start` string, date-time: Start of analysis period as an ISO 8601 datetime string (e.g. '2025-01-01T00:00:00.000-05:00'). Defaults to the start of the week containing the date one week ago, in the store's timezone (weeks start Monday) — so the default window spans 7 to 13 days depending on the current weekday, not exactly 7. Note the default differs per sitewide endpoint, so pass an explicit start if you need a specific window. - `end` string, date-time: End of analysis period as an ISO 8601 datetime string. Defaults to now. - `filters` object: Optional analytics filters object. See the Filters Reference for available filter fields. - `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 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. - `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. - `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. - `currencyCodes` string[]: Filter by ISO 4217 order currency codes (e.g. ['USD', 'GBP', 'CAD']). Matches the currency an order was placed in. Omit or pass empty array for all currencies. - `currencyCodesFilterType` 'include' | 'exclude': How currencyCodes should be matched: 'include' (only orders in the listed currencies) or 'exclude' (orders in any currency except the listed ones). Defaults to 'include' when omitted. Requires currencyCodes 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 - `onlyProductIds` string[]: Filter to orders containing at least one of these Shopify product IDs (numeric strings, e.g. ['1234567890', '9876543210']). Omit or pass an empty array for all products. - `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. - `allOrders` boolean: Whether to include all orders or only matched orders. - `feature` union: Optional feature selector object. Omit it or use `{ "name": "performance" }` for sitewide KPI snapshots, `{ "name": "audience", "audience": "device_type" }` for audience segment snapshots, `{ "name": "order" }` for order-focused metrics, or `{ "name": "conversion" }` for conversion funnel metrics. - object - `name` 'performance', required - object - `name` 'audience', required - `audience` 'device_type' | 'visitor_type' | 'source_channel' | 'source_site' | 'country_code' | 'landing_page_full_path', required: Optional audience breakdown dimension. When provided, returns per-segment snapshot instead of site-level KPIs. Supported values: device_type, visitor_type, source_channel, source_site, country_code, landing_page_full_path. - object - `name` 'order', required - object - `name` 'conversion', required ## Response `200` OK - object ## Other responses - `429`: Too Many Requests --- [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/7b769b2f90b1?raw)