Schema and Inputs

Base Contract

• Endpoint: POST /graphql/v1
• Docs index: GET /docs/v1
• Deprecated aliases: POST /graphql and GET /docs
• Scalars used in inputs:
• Date: accepts YYYY-MM-DD or YYYY/MM/DD and normalizes to YYYY-MM-DD
• DateTime
• JSON

Shared Input Types

DateRangeInput

• start: Date!
• end: Date!

Behavior:

• range is inclusive
• end must be on or after start
• max inclusive span is capped by server policy (MAX_DATE_RANGE_DAYS)

SharedAnalyticsFilterInput

Optional session-qualification filters used by multiple queries:

• newUser: Boolean — limit to sessions from first-time visitors
• returningUser: Boolean — limit to sessions from returning visitors
• purchase: Boolean — limit to sessions that include at least one conversion
• nonPurchase: Boolean — limit to sessions with no conversions
• averageOrderValueMin: Float — lower bound filter on session-level AOV
• averageOrderValueMax: Float — upper bound filter on session-level AOV
• device: DeviceType — limit to sessions from a specific device type

Notes:

• newUser and returningUser are mutually exclusive; if both are set only one takes effect.
• purchase and nonPurchase are mutually exclusive; if both are set only one takes effect.

JourneySequenceInput

Used by continuation analysis:

• sequencePageIds: [ID!]
• anchorMustBeEntry: Boolean
• excludeNextPageIds: [ID!]
• requireActivePages: Boolean
• includeContinuation: Boolean
• includeVisitIds: Boolean

Enums

• DeviceType: MOBILE, DESKTOP, TABLET
• HeatmapEventType: CLICK, SCROLL
• AnalyticsMetric: PAGE_VIEWS, SESSIONS, UNIQUE_VISITORS
• AnalyticsBreakdown: DATE, URL, COUNTRY, DEVICE, REFERRER
• SessionGroupBy: DATE, PAGE
• SessionSortBy: DATE, PAGE, SESSIONS, PAGEVIEWS, CONVERSIONS, REVENUE, REVENUE_PER_SESSION, AVERAGE_ORDER_VALUE, CONVERSION_RATE
• JourneyGroupBy: PAGE, TRAFFIC_SOURCE, DEVICE, BROWSER, DATE
• JourneyMetric: SESSIONS, PAGEVIEWS, REVENUE, REVENUE_PER_SESSION, AVERAGE_ORDER_VALUE, CONVERSION_RATE
• SortDirection: ASC, DESC
• FunnelBreakdown: NONE
• ConversionBreakdown: DATE, CONVERSION_NAME, PAGE, COUNTRY, DEVICE
• CustomEventBreakdown: DATE, EVENT_NAME, EVENT_CATEGORY, COUNTRY, DEVICE
• RawPageviewOrderBy: SERVER_DATE, PAGE, SESSIONS, PAGEVIEWS, REVENUE, REVENUE_PER_SESSION, AVERAGE_ORDER_VALUE, CONVERSION_RATE, PURCHASES, SCROLL_DEPTH, TIME_ON_PAGE
• RawEventOrderBy: PAGE, SELECTOR, OFFSET_X, OFFSET_Y, VALUE, ORDERS, REVENUE, AOV

Metrics Glossary

Use this section as the shared meaning for core metrics across all analytics queries.

Sessions (Visits)

• Meaning: number of distinct visits/sessions included in the result set.
• Formula: sessions = count(distinct visitId)
• Interpretation: this is a visit count, not a user count.

Pageviews

• Meaning: total tracked page view events in the selected scope.
• Formula: pageviews = sum(pageview events)
• Interpretation: one session can produce multiple pageviews.

Events

• Meaning: total count of matching tracked events.
• Formula: events = sum(event_count) (or equivalent aggregated event rows)
• Interpretation: used in heatmap and customEvents style outputs.

Revenue

• Meaning: sum of conversion/order revenue in scope.
• Formula: revenue = sum(conversion revenue)
• Interpretation: value is numeric and may be 0 when no matching conversions are found.
• **Date attribution:** Revenue is attributed to the session's start date, not the timestamp of the conversion event. A session that started on 2026-04-18 and converted after midnight is counted against 2026-04-18. When filtering by date range, the range applies to session start date — all revenue belonging to qualifying sessions is included regardless of when the conversion event fired.

Conversions

• Meaning: number of conversion records/orders matched by filters.
• Formula: conversions = count(conversion rows)
• Interpretation: typically one conversion record maps to one order in current outputs.
• **Date attribution:** Conversions are attributed to the session's start date, not the timestamp of the conversion event. A session that started on 2026-04-18 and converted after midnight is counted against 2026-04-18. When filtering by date range, the range applies to session start date — all conversions belonging to qualifying sessions are included regardless of when the conversion event fired.

Conversion Rate (CR)

• Meaning: conversion efficiency per session.
• Formula: conversionRate = conversions / sessions
• Zero handling: when sessions = 0, conversion rate is 0.
• Interpretation: returned as a ratio (for example 0.125 = 12.5%).

Average Order Value (AOV)

• Meaning: average revenue per conversion/order.
• Formula: averageOrderValue = revenue / conversions
• Zero handling: when conversions = 0, AOV is 0.
• Interpretation: use this with conversions and revenue for quality-of-revenue analysis.

Revenue per Session

• Meaning: average revenue generated by each session.
• Formula: revenuePerSession = revenue / sessions
• Zero handling: when sessions = 0, revenue per session is 0.

Traffic Source

• Meaning: visit referrer/source dimension for grouped analytics.
• Source mapping: trafficSource comes from visit referrer/source fields.
• Default behavior: empty source values are normalized to Direct in grouped output.

Query Input Matrix

viewerAccess

Input: none

Response: ViewerAccess (accountId, allowedSites, allowedEndpoints, siteScope)

sites

Input: none

Response: [Site!] (id, name, domain, timezone, status)

analytics

Input type: AnalyticsQueryInput

Required: siteId, metric, range

Optional: filters, breakdown, limit

steps is typed as [FunnelStepInput!]! and must be an array of step objects.

sessionAnalytics

Input type: SessionAnalyticsQueryInput

Required: siteId, range

Optional: filters, groupBy, metrics, sortBy, sortDirection, pageUrl, trafficSource, browser, limit

pageviewAnalytics

Input type: PageviewAnalyticsQueryInput

Required: siteId, range

Optional: filters, groupBy, metrics, sortBy, sortDirection, conversionName, pageUrl, trafficSource, browser, limit

journeyContinuationAnalytics

Input type: JourneyContinuationAnalyticsQueryInput

Required: siteId, range, journey

Optional: filters, limit

rawPageviewAnalytics

Input type: RawPageviewAnalyticsQueryInput

Required: siteId, range

Optional: filters, eventType, eventTypes, conversionName, pageUrl, includeRevenue, orderBy, sortDirection, limit

rawEventAnalytics

Input type: RawEventAnalyticsQueryInput

Required: siteId, range

Optional: filters, conversionName, pageUrl, selector, includePage, orderBy, sortDirection, limit

Behavior:

• includePage defaults to true and controls whether page is projected/grouped in rows.
• Output rows include value (event count), orders, revenue, and aov.
• selector and pageUrl filters are applied before grouped row aggregation.

funnels

Input type: FunnelQueryInput

Required: siteId, range, steps

Optional: filters, breakdown, limit

Response rows always include an implicit Step 1 baseline:

• Step 1: All Sessions
• Step 2..N: user-provided steps in order

steps supports typed step entries:

• type: EVENT with event: FunnelEventName
• type: PAGE_VIEW with page: FunnelPageFilterInput

Canonical steps example:

[

  { "type": "EVENT", "event": "PRODUCT_VIEWED" },

  { "type": "PAGE_VIEW", "page": { "operator": "EQUALS", "value": "https://example.com/checkout" } },

  { "type": "EVENT", "event": "CHECKOUT_COMPLETED" }

]

Allowed FunnelEventName values:

• CART_VIEWED
• CHECKOUT_STARTED
• ADD_TO_CART
• HOMEPAGE_VIEWED
• PRODUCT_VIEWED
• CHECKOUT_COMPLETED
• COLLECTION_VIEWED

Allowed FunnelPageOperator values:

• EQUALS
• NOT_EQUALS
• CONTAINS
• NOT_CONTAINS
• BEGINS
• ENDS

Funnel row metrics:

• sessions (compat alias of completedUsers)
• completedUsers
• completedRate (ratio vs previous step; Step 1 is 1)
• abandonedUsers (drop-off from previous step; Step 1 is 0)
• abandonedRate (drop-off ratio vs previous step; Step 1 is 0)
• revenue (sum of conversion revenue for visits that reached the step)
• revenuePerCompletedUser

Tooling note: some GraphQL UIs cannot visually compose list-of-object arguments; use raw JSON variables for steps.

heatmap

Input type: HeatmapQueryInput

Required: siteId, range

Optional: url, eventType, selector, limit

conversions

Input type: ConversionQueryInput

Required: siteId, range

Optional: conversionName, filters, breakdown, limit

customEvents

Input type: CustomEventQueryInput

Required: siteId, range

Optional: eventName, eventCategory, filters, breakdown, limit

sitePages

Input type: SitePagesQueryInput

Required: siteId

Returns active pages for a site with unique screenshot URLs. Each row contains id, pageName, and screenshotUrl.

Optional urlFilter narrows results by screenshot URL. It takes an operator (EQUALS, NOT_EQUALS, CONTAINS, NOT_CONTAINS, STARTS_WITH, NOT_STARTS_WITH, ENDS_WITH, NOT_ENDS_WITH, REGEX) and a value string.