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.
Tip: For each Metric included in your query, there will be a corresponding column for that data point in your returned CSV file.
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 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.
Tip: Adding Dimensions to your query will return additional rows, as each combination of grouping criteria will now be split into a separate row.
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 city the visitor was in.
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 or AMP page.
Country
country
The country the visitor was in.
Device
device
The device used (mobile/desktop/tablet).
Distribution
distribution
The distribution channel used (site/Facebook IA/app)
Dynamic Author
dynamic_author
A dynamically updated author. Use if the author tag has changed during the lifetime of an article. (e.g. there was a misspelling of the authors name at publication). Available for queries after 11/01/2015
Dynamic Section
dynamic_section
A dynamically updated section. Use if the section tag has changed during the lifetime of an article. (e.g. it's published under World and later moves to Politics). Available for queries after 11/01/2015.
Dynamic Title
dynamic_title
A dynamically updated title. Use if the title has changed during the lifetime of an article (e.g. a headline was edited ater being published or changes as part of an A/B testing experiement).
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.
Operating System
os
The operating system used.
Page Load Histogram
page_load_hist
Histogram of the page load time.
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.
Referrer
referrer
The referring domain.
Referrer Type
referrer_type
The page referrer type: social, search, direct, internal, and external (aka links).
Region
region
The region the visitor was in (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 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 Paid Content tracking.
Subdomain
subdomain
The specific subdomain (e.g. blog.chartbeat.com, chartbeat.com.
Subscriber
subscriber
The visitor's subscriber status (Guest, Registered, Subscribed, Unspecified).
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.
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.
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.​
Country
country
The country the visitor was in.
Device
device=
The device used (desktop, mobile, tablet).
Distribution
distribution=
The distribution channel used (site/facebook_ia/app).
Dynamic Author
dynamic_author=
A dynamically updated author. Use if the author tag has changed during the lifetime of an article (e.g. there was a misspelling of the author's name at publication).
Dynamic Section
dynamic_section=
A dynamically updated section. Use if the section tag has changed during the lifetime of an article (e.g. it's published under World and later moves to Politics).
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. Set this to publish_date=match_query_range to filter your results to 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).
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.

Recurring Queries

Last updated 1 month ago

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 pageviews that received at least 15 seconds of engaged time.

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 city the visitor was in.
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 or AMP page.
Country	`country`	The country the visitor was in.
Device	`device`	The device used (mobile/desktop/tablet).
Distribution	`distribution`	The distribution channel used (site/Facebook IA/app)
Dynamic Author	`dynamic_author`	A dynamically updated author. Use if the author tag has changed during the lifetime of an article. (e.g. there was a misspelling of the authors name at publication). Available for queries after 11/01/2015
Dynamic Section	`dynamic_section`	A dynamically updated section. Use if the section tag has changed during the lifetime of an article. (e.g. it's published under World and later moves to Politics). Available for queries after 11/01/2015.
Dynamic Title	`dynamic_title`	A dynamically updated title. Use if the title has changed during the lifetime of an article (e.g. a headline was edited ater being published or changes as part of an A/B testing experiement).
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.
Operating System	`os`	The operating system used.
Page Load Histogram	`page_load_hist`	Histogram of the page load time.
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.
Referrer	`referrer`	The referring domain.
Referrer Type	`referrer_type`	The page referrer type: social, search, direct, internal, and external (aka links).
Region	`region`	The region the visitor was in (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 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 Paid Content tracking.
Subdomain	`subdomain`	The specific subdomain (e.g. blog.chartbeat.com, chartbeat.com.
Subscriber	`subscriber`	The visitor's subscriber status (Guest, Registered, Subscribed, Unspecified).
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.

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.
Country	`country`	The country the visitor was in.
Device	`device=`	The device used (`desktop`, `mobile`, `tablet`).
Distribution	`distribution=`	The distribution channel used (`site`/`facebook_ia`/`app`).
Dynamic Author	`dynamic_author=`	A dynamically updated author. Use if the author tag has changed during the lifetime of an article (e.g. there was a misspelling of the author's name at publication).
Dynamic Section	`dynamic_section=`	A dynamically updated section. Use if the section tag has changed during the lifetime of an article (e.g. it's published under World and later moves to Politics).
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. Set this to `publish_date=match_query_range` to filter your results to 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).
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.

Metrics, Dimensions, and Filters

Metrics

Page endpoint Metrics

Video endpoint Metrics​

Dimensions

Page endpoint Dimensions

Video endpoint Dimensions

Filters

Page endpoint Filters

Video endpoint Filters

Video endpoint Metrics