# 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](/cbp/tracking/google-amp/amp-configuration-variables.md). |
| 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**.](/cbp/tracking/standard-websites/configuration-variables.md#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. |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.chartbeat.com/cbp/api/historical-api/metrics-dimensions-filters.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.