> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upstackdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Measures and Dimensions Reference

> Reference of every measure (numeric metric) and dimension (groupable attribute) in Upstack Analytics — definitions, calculation logic, valid combinations, and the events each is derived from.

Measures and dimensions are the building blocks of every Upstack Analytics query. **Measures** are the numeric values you calculate (revenue, event counts, conversion rates). **Dimensions** are the categories you group by (date, traffic source, device type).

<Tip>
  Start with a measure you care about (e.g., Revenue), add a dimension to break it down (e.g., `utm_source`), and apply filters to focus your analysis. Most useful reports use 1–2 measures and 1–2 dimensions.
</Tip>

## Measures

Measures are aggregate calculations across your event data. Select one or more measures in the query builder to define what you want to calculate.

<Tip>
  Need a metric that isn't listed here? Build your own from a formula over these measures with [Custom Measures](/analytics/custom-measures).
</Tip>

| Name | Type | Description | Unit |
| - | - | - | - |
| `total_events` | measure | Total count of events matching the query filters. | count |
| `unique_visitors` | measure | Count of distinct resolved identities (or anonymous session IDs for unresolved visitors). | count |
| `sessions` | measure | Count of distinct browsing sessions. A session ends after 30 minutes of inactivity. | count |
| `page_views` | measure | Count of PageView events. | count |
| `purchases` | measure | Count of Purchase events. | count |
| `revenue` | measure | Sum of `value` from Purchase events. | currency (store default) |
| `conversion_rate` | measure | Ratio of sessions with at least one Purchase to total sessions. Expressed as a percentage. | percentage |
| `avg_order_value` | measure | Mean `value` across Purchase events. Calculated as `revenue / purchases`. | currency (store default) |
| `bounce_rate` | measure | Percentage of sessions with only a single PageView and no further interaction. | percentage |
| `session_duration` | measure | Average time between the first and last event in a session. | seconds |
| `add_to_cart_rate` | measure | Ratio of sessions with at least one AddToCart event to total sessions. | percentage |
| `cart_abandonment_rate` | measure | Ratio of sessions with AddToCart but no Purchase to sessions with AddToCart. | percentage |
| `avg_pages_per_session` | measure | Mean number of PageView events per session. | count |

<Note>
  Currency-based measures (`revenue`, `avg_order_value`) use the currency from the Purchase event's `currency` field. If your store transacts in multiple currencies, values are reported in the original currency unless you enable currency normalization in settings.
</Note>

## Dimensions

Dimensions define how measures are grouped and broken down. Select one or more dimensions to segment your data.

### Time Dimensions

| Name | Type | Description | Granularity |
| - | - | - | - |
| `date` | dimension | Calendar date of the event. | day |
| `week` | dimension | ISO week of the event. | week |
| `month` | dimension | Calendar month of the event. | month |
| `hour_of_day` | dimension | Hour (0–23) when the event occurred. Useful for time-of-day analysis. | hour |
| `day_of_week` | dimension | Day of the week (Monday–Sunday). | day |

### Traffic Dimensions

| Name | Type | Description | Example Values |
| - | - | - | - |
| `utm_source` | dimension | UTM source parameter from the landing page URL. | `facebook`, `google`, `klaviyo` |
| `utm_medium` | dimension | UTM medium parameter. | `cpc`, `email`, `organic` |
| `utm_campaign` | dimension | UTM campaign parameter. | `summer_sale_2026`, `retargeting_q1` |
| `utm_content` | dimension | UTM content parameter for ad-level breakdown. | `hero_banner`, `sidebar_ad` |
| `utm_term` | dimension | UTM term parameter for keyword-level analysis. | `cotton+tee`, `running+shoes` |
| `referrer` | dimension | HTTP referrer domain that sent the visitor. | `google.com`, `facebook.com`, `direct` |
| `channel` | dimension | Aggregated traffic channel derived from UTM and referrer data. | `Paid Social`, `Organic Search`, `Email`, `Direct` |

### Content Dimensions

| Name | Type | Description | Example Values |
| - | - | - | - |
| `page_path` | dimension | URL path of the page (without domain or query string). | `/products/classic-tee`, `/collections/summer` |
| `event_name` | dimension | Name of the event type. Stored in PascalCase (destination format). | `PageView`, `Purchase`, `AddToCart` |
| `content_type` | dimension | Type of content involved in the event. | `product`, `product_group` |

<Note>
  **Event name formats:** When calling the SDK, use `snake_case` (e.g., `add_to_cart`). Upstack transforms these to `PascalCase` for destinations and analytics storage.
</Note>

### Visitor Dimensions

| Name | Type | Description | Example Values |
| - | - | - | - |
| `device_type` | dimension | Device category detected from user agent. | `mobile`, `desktop`, `tablet` |
| `country` | dimension | Visitor's country, derived from IP geolocation. | `US`, `GB`, `CA`, `AU` |
| `region` | dimension | Visitor's state or region. | `California`, `Ontario`, `London` |
| `is_returning` | dimension | Whether the visitor has been seen in a previous session. | `true`, `false` |

### Destination Dimensions

| Name | Type | Description | Example Values |
| - | - | - | - |
| `destination` | dimension | The forwarding destination the event was sent to. | `meta_capi`, `tiktok`, `klaviyo`, `ga4` |
| `delivery_status` | dimension | Whether the event was successfully delivered to the destination. | `delivered`, `failed`, `pending` |

## Combining Measures and Dimensions

Here are practical examples of how measures and dimensions work together:

| Goal | Measures | Dimensions | Result |
| - | - | - | - |
| Daily revenue trend | `revenue` | `date` | Line chart of revenue per day |
| Channel ROAS comparison | `revenue`, `purchases` | `utm_source` | Table comparing revenue and purchase count by source |
| Mobile vs. desktop conversion | `conversion_rate`, `sessions` | `device_type` | Bar chart comparing conversion rates |
| Top landing pages | `page_views`, `bounce_rate` | `page_path` | Table of pages sorted by traffic with bounce rate |
| Hourly traffic pattern | `sessions` | `hour_of_day` | Bar chart showing when visitors arrive |
| Campaign performance | `revenue`, `conversion_rate`, `avg_order_value` | `utm_campaign` | Full campaign performance table |

<CardGroup cols={2}>
  <Card title="Query Guide" icon="magnifying-glass-chart" href="/analytics/query-guide">
    Learn how to build queries, set date ranges, and apply filters.
  </Card>

  <Card title="Session & Page Analytics" icon="chart-line" href="/analytics/session-and-page-analytics">
    Explore session-level and page-level metrics in detail.
  </Card>

  <Card title="Custom Measures" icon="calculator" href="/analytics/custom-measures">
    Define your own metrics and KPIs from a formula over these measures.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.