LogoLogo
Help CenterStatusContact
  • Chartbeat Documentation
  • Implement Tracking
    • Standard Websites
      • Adding chartbeat.js to Your Site
      • Customize Tracking Settings
      • Tracking Virtual Page Change
      • User Subscriber Status
      • Alternative Site Integrations
      • Integration QA Steps: Website
      • Additional Page Metadata
    • Google AMP
      • Chartbeat Code for AMP
      • AMP Configuration Variables
      • Alternative AMP Integration
      • Integration QA Steps: AMP
    • Mobile App SDKs
      • Intro to Mobile App Tracking
      • Android SDK
      • iOS SDK
      • Integration QA Steps: Mobile Apps
  • Feature Integrations
    • Headline and Image Testing
      • Adding chartbeat_mab.js to Your Site
      • Image Compatibility
      • Flicker & Flicker Control
      • mab.js Specifications
      • Integration QA Steps: Headline and Image Testing
    • Video Engagement
      • Adding chartbeat_video.js to Your Site
      • Supported OVP Integrations
      • Custom Player Integration SDK
      • Configure Video Tracking Settings
      • Integration QA: Video Tracking
    • Conversion
      • Adding subscriptions.js to Your Site
      • Conversion Events
      • Integration QA Steps: Conversion
      • Supported Conversion Flows
  • API Docs
    • Real-Time API
      • Getting Started with our Real-Time API
      • Traffic Data
      • Video Engagement Data
    • Historical API
      • Getting Started with our Historical API
      • One-time Queries
      • Recurring Queries
      • Metrics, Dimensions, and Filters
    • Headline Testing API
      • Getting Started with our Headline Testing API
      • Raw Data
      • Summary Report
      • Variant Report
    • Conversion API
      • Getting Started with our Conversion API
      • Top Articles
    • Data Lab API
      • Getting Started with Data Lab API
  • Help Center
  • Contact Support
  • Datastream Docs
  • Back to Chartbeat.com
Powered by GitBook
On this page
  • Metrics
  • Page endpoint Metrics
  • Video endpoint Metrics​
  • Dimensions
  • Page endpoint Dimensions
  • Video endpoint Dimensions
  • Filters
  • Page endpoint Filters
  • Video endpoint Filters

Was this helpful?

  1. API Docs
  2. Historical API

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

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

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

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

Subdomain

subdomain

The specific subdomain (e.g. blog.chartbeat.com, chartbeat.com.

Subscriber

subscriber

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=

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.

PreviousRecurring QueriesNextHeadline Testing API

Last updated 6 months ago

Was this helpful?

The content type (e.g. gallery, article) as tagged on or .

The date that a piece of content on your site was .

The visited.

The sponsor ID. Note that this is only available to domains that are using the

The visitor's (Guest, Registered, Subscribed, Unspecified).

The content type (e.g. gallery, article) as

your site
AMP page
first tracked by Chartbeat
section of a page
sponsorName config variable.
subscriber status
tagged on your site.