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 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.

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/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.
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.
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).
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.

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/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.