Metrics, Dimensions, and Filters
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.
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. |
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. |
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.
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. |
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 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.
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= | |
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. |
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. |
Last modified 3mo ago