# Metrics, Dimensions, and Filters
## Metrics
The Metrics parameter identifies which user engagement data points you want returned in your query. Any given query may include multiple metrics to create comprehensive queries.
{% hint style="success" %}
**Tip:** For each Metric included in your query, there will be a corresponding column for that data point in your returned CSV file.
{% endhint %}
### Page endpoint Metrics
| Metric | API Syntax | Description |
| ------------------------ | -------------------- | ---------------------------------------------------------------------------------------------- |
| Average Scroll | `page_avg_scroll` | The average maximum depth that visitors have scrolled to, in pixels, from the top of the page. |
| Average Engaged Time | `page_avg_time` | The average amount of time in seconds visitors actively spent on a page. |
| Scroll Starts | `page_scroll_starts` | The percentage of page views where a scroll event occurred, expressed as a decimal. |
| Total Engaged Time | `page_total_time` | The total amount of time in seconds spent actively on a page across sites. |
| Uniques | `page_uniques` | A count of the number of unique cookies who visited the page. |
| Page Views | `page_views` | A count of the number of page views. |
| Loyal Visitor Page Views | `page_views_loyal` | The number of pageviews from visitors who visit your site an average of every other day. |
| Quality Page Views | `page_views_quality` | The number of pageviews that received at least 15 seconds of engaged time. |
### **Video endpoint Metrics**
| Metric | API Syntax | Description |
| -------------------- | ----------------- | -------------------------------------------------------------------------------------- |
| Average Engaged Time | `video_avg_time` | The average amount of time for which visitors watched a video (in seconds). |
| Video Loads | `video_loads` | A count of the number of times a video loaded. |
| Video Play Rate | `video_play_rate` | The fraction of loaded videos that were subsequently played. (Video Plays/Video Loads) |
| Video Plays | `video_plays` | A count of the number of times a video was played. |
## Dimensions
Use the dimensions to select the grouping criteria for which your metrics are returned, such as time of day, geographic location, and page specific data.
{% hint style="success" %}
**Tip:** Adding Dimensions to your query will return additional *rows*, as each combination of grouping criteria will now be split into a separate row.
{% endhint %}
### Page endpoint Dimensions
| Dimension | API Syntax | Description |
| ------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Author | `author` | The author of a page. |
| Canonical Referrer | `canonical_referrer` | A rolled-up view of the referrer domain. For instance, traffic from m.facebook.com and facebook.com both have a canonical referrer of Facebook. |
| City | `city` | The visitor's city. |
| Client-side Day | `client_day` | The calendar day, according to the timezone set by the visitor. |
| Client-side Hour | `client_hour` | The hour of the day (0-23), according to the timezone set by the visitor. |
| Client-side Minute | `client_minute` | The minute, according to the timezone set by the visitor. |
| Content Type | `contenttype` | The content type (e.g. gallery, article) as tagged on [your site](https://docs.chartbeat.com/cbp/tracking/standard-websites/configuration-variables#content-type) or [AMP page](https://docs.chartbeat.com/cbp/tracking/google-amp/amp-configuration-variables). |
| Country | `country` | The visitor's country. |
| Device | `device` | The device used (mobile/desktop/tablet). |
| Distribution | `distribution` | The distribution channel used (site/FBIA/app). |
| Internal Navigation Path | `internal_path` | The page path that users clicked away from when they opened a new page. Useful for learning about historical click-through data. |
| Operating System | `os` | The operating system used. |
| Page Load Histogram | `page_load_hist` | Histogram of the page load time (100 millisecond bins). |
| Page Type | `pagetype` | The type of page, returned as either Article, LandingPage, or Unknown. |
| Page Width Histogram | `pagewidth_hist` | Width of the page in pixels (50 pixels bins). Useful when analyzing responsive designs. |
| Page Path | `path` | The URL/path of the page. |
| Publish Date | `publish_date` | The date that a piece of content on your site was [first tracked by Chartbeat](https://help.chartbeat.com/hc/en-us/articles/208982958-Real-Time-metrics-glossary#h_8034396542001550335263977). |
| Referrer | `referrer` | The referring domain. |
| Referrer Type | `referrer_type` | The page referrer type: social, search, direct, internal, and external (aka links). |
| Region | `region` | The visitor's region (returns states for US) |
| Scroll Depth Histogram | `scroll_hist` | Histogram of the number of pixels scrolled (100 pixel bins). |
| Section | `section` | The [section of a page](https://docs.chartbeat.com/cbp/tracking/standard-websites/configuration-variables#sections-and-authors) visited. |
| Site Experience | `site_experience` | The site experience for the visitor (AMP/Standard). An NA value indicates that the visitor comes from an off-site distribution channel. |
| Sponsor | `sponsor` | The sponsor ID. Note that this is only available to domains that are using the [`sponsorName` config variable.](https://docs.chartbeat.com/cbp/tracking/standard-websites/configuration-variables#sponsor-name) |
| Subdomain | `subdomain` | The specific subdomain (e.g. blog.chartbeat.com, chartbeat.com. |
| Subscriber | `subscriber` | The visitor's [subscriber status](https://docs.chartbeat.com/cbp/tracking/standard-websites/subscriber-engagement) (Guest, Registered, Subscribed, Unspecified). |
| Title | `title` | Page title. |
| Engaged Time Histogram | `time_hist` | Histogram of active engaged time (15 second bins). |
| Day | `tz_day` | The calendar day in your time zone. |
| Hour | `tz_hour` | The hour of the day (0-23) in your time zone. Can be used with Day to get hourly time series. |
| Minute | `tz_minute` | The minute in your time zone. Can be used with Hour to get per-minute time series. |
| Month | `tz_month` | The month, with day boundaries in your timezone. |
| Day (in UTC) | `utc_day` | The calendar day in the UTC time zone. |
| Hour (in UTC) | `utc_hour` | The hour of the day (0-23) in the UTC time zone. Can be used with utc\_day to get hourly time series. |
| Minute (in UTC) | `utc_minute` | The minute in the UTC time zone. Use paired with utc\_hour to get per-minute time series. |
| UTM Campaign | `utm_campaign` | Identifies a specific promotion/campaign. |
| UTM Content | `utm_content` | Identifies what specifically was clicked. |
| UTM Medium | `utm_medium` | Identifies the type of link, ‘email’ for example. |
| UTM Source | `utm_source` | Identifies to which site a link was posted. |
| UTM Term | `utm_term` | Identifies search term/terms. |
| Visitor Frequency | `visit_frequency` | Returns New, Returning, or Loyal. |
### **Video endpoint Dimensions**
| Dimension | API Syntax | Description |
| --------------- | ------------- | ----------------------------------------------------------------------------------------------- |
| Device | `device` | The device used (mobile/desktop/tablet). |
| Page path | `page_path` | The URL/path of the page a video appeared on. |
| Play state | `play_state` | Play state of video (loaded, playing, paused, completed). |
| Day | `tz_day` | Play state of video (loaded, playing, paused, completed). |
| Hour | `tz_hour` | The hour of day (0-23) in your timezone. Can be used with Day to get hourly timeseries. |
| Minute | `tz_minute` | The minute in your time zone. Use paired with Hour to get per-minute time series. |
| Month | `tz_month` | The month, with day boundaries in your timezone. |
| Day (in UTC) | `utc_day` | The calendar day in the UTC time zone. |
| Hour (in UTC) | `utc_hour` | The hour of day (0-23) in the UTC timezone. Can be used with utc\_day to get hourly timeseries. |
| Minute (in UTC) | `utc_minute` | The minute in the UTC timezone. Use paired with utc\_hour to get per-minute timeseries. |
| Video path | `video_path` | The URL/path of the video. |
| Video title | `video_title` | The title of the video. |
## Filters
Filters help narrow down the returned data such that it only pertains to relevant criteria. Use the filter parameter to create queries that reflect specific audience segments.
{% hint style="success" %}
**Tip**: Filters don't impact returned *rows* or *columns*, but do shape the data such that all returned values will meet the filter conditions being set.
{% endhint %}
### Page endpoint Filters
| Filter | API Syntax | Description |
| ------------------------ | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Author | `author=` | The author of a page. |
| Canonical Referrer | `canonical_referrer=` | A rolled-up view of the referrer domain. For instance, traffic from m.facebook.com and facebook.com both have a canonical referrer of Facebook. |
| City | `city` | The city the visitor was in. |
| Content type | `contenttype=` | The content type (e.g. gallery, article) as [**tagged on your site**.](https://docs.chartbeat.com/cbp/tracking/standard-websites/configuration-variables#content-type) |
| Country | `country` | The country the visitor was in. |
| Device | `device=` | The device used (`desktop`, `mobile`, `tablet`). |
| Distribution | `distribution=` | The distribution channel used (`site`/`FBIA`/`app`). |
| Internal Navigation Path | `internal_path=` | The page path that users clicked off from when they traveled to a new page. Useful for learning about historical click-through data. |
| Page Path | `path=` | The reported path of the page (Unique to your domain). |
| Page Type | `pagetype=` | The type of page. There are currently three types: `Article`, `LandingPage`, and `Unknown`. |
| Publish Date | `publish_date=` | The date that a piece of content on your site was first tracked by Chartbeat. Filter must be set as `publish_date=match_query_range`; this will return articles that were published within the start and end date of your query. |
| Referrer | `referrer=` | The referring domain. |
| Referrer Type | `referrer_type=` | The page referrer type: `social`, `search`, `direct`, `internal`, `external`. |
| Section | `section=` | The section of a site visited (Unique to your domain) |
| Site Experience | `site_experience=` | The site experience for the visitor (`amp`, `standard`). An `NA` value indicates that the visitor comes from an off-site distribution channel. |
| Sponsor | `sponsor=` | The sponsor ID or name, as tagged on the piece of sponsored content. |
| Subdomain | `subdomain=` | The specific subdomain (Unique to your domain). |
| Subscriber | `subscriber=` | The visitor's subscriber status (Guest, Registered, Subscribed, Unspecified). |
| Title | `title=` | Page title. |
| UTM Campaign | `utm_campaign=` | Identifies a specific promotion/campaign. |
| UTM Content | `utm_content=` | Identifies what specifically was clicked. |
| UTM Medium | `utm_medium=` | Identifies the type of link, ‘email’ for example. |
| UTM Source | `utm_source=` | Identifies to which site a link was posted. |
| UTM Term | `utm_term=` | Identifies search term/terms. |
| Visitor Frequency | `visit_frequency=` | New/Returning/Loyal/Unclassified. |
### **Video endpoint Filters**
| Metric | API Syntax | Description |
| ---------- | ------------ | --------------------------------------------- |
| Device | `device` | The device used (mobile/desktop/tablet). |
| Page path | `page_path` | The URL/path of the page a video appeared on. |
| Video path | `video_path` | The URL/path of the video. |