Get up and running with Chartbeat—full implementation guides for all our products.

Advanced Queries

Introduction

Chartbeat’s Advanced Queries is designed for analysts and researchers to build and distribute custom historical querie about their audience and content.

Advanced Queries offers a wide array of metrics, filters, and groups that can be used by both analytics and editorial teams to track audience and content data over time. Through the interface, not only can you elect to receive these querie in your inbox, but you’ll have access to an archive of all the querie you’ve created. It’s easy to copy this data into your own pivot tables to organize your data however you need.

Important Note: Advanced Queries will not function if your browser is running an adblocker. For convenience, simply add the URL to the exceptions list in your adblocker, or disable it entirely.

Required Parameters

Query Type

There are two query types to pick from: a one time query, which creates a single CSV file to be downloaded or sent via email, and a recurring query – which you can subscribe to and receive it in your inbox on a daily, weekly, or monthly basis. Note that daily queryies look at the past day of data, weekly querie look at the past week, and monthly look at the past month.

Date Range

The date range specifies time frame you want to pull from for your queriy. You can select a preset range of the past 7 days, 31 days, the previous 24 hours, or a you can create a custom date range with the calendar box.

Metrics Set

A choice of which set of metrics you would like to build querys using. Select the 'Page' endpoint for metrics related to article content (i.e. pageviews) or the 'Video' endpoint for video metrics (i.e. video plays). Note that as they are separate endpoints, you cannot create a single query with both sets of metrics.

Site

The site field is the domain that you want to create a query for. Note that you may only select domains that your Chartbeat login has access to.

Required API Parameters

The Advanced Queries API endpoints may be used to call historical data in either one-time or recurring querie, downloaded directly into your browser. The Advanced Queries API endpoints and parameters can be found in the API Documentation. Below are descriptions of each Advanced Queries metric and group by parameter, as well as their corresponding API syntax.

The following parameters are necessary to to configure Advanced Queries APIs.

Parameter API Syntax Description
API Key apikey= Your API Key - click here for yours.
Endpoint endpoint= Choose between page and video data.
Host host= The domain you'd like to pull data from.
Limit limit= The number of rows you'd like to pull in your query. Limits must be base-ten; while there is no hard-limit, large calls are susceptible to 504 gateway timeouts. If you're consistently seeing timeouts, please reach out to your account manager or support@chartbeat.com.
Start Date start=yyyy-mm-dd= The first day you'd like to pull data from.
End Date end=yyyy-mm-dd= The last day you'd like to pull data on.
Sort Column sort_column= The column you'd like to sort the query on (i.e. path, author...
Sort Order sort_order= The order of the sort (asc/desc).
Timezone tz= The timezone you'd like to run the query in a valid Olson timezone format, e.g. America/New_York (optional).

Example Advanced Queries API Call

Here is an example call to the Advanced Queries API, and following is a full description of every available metric and parameter.

GET
https://api.chartbeat.com/query/v2/submit/page/?&apikey=YOURAPIKEYHERE&sort_column=page_total_time&sort_order=desc&start=yyyy-mm-dd&end=yyyy-mm-dd&endpoint=page&host=YOURSITE.com&limit=1000&tz=America%2FNew_York&dimensions=dynamic_title,path&metrics=page_total_time,page_avg_time,page_uniques,page_views,page_views_loyal,page_views_quality&referrer_type=social

A full discussion of retrieving the results from your API calls can be found in the API Documentation.

Metrics

The metrics parameter identifies which audience and site data points you want returned in your query. Any given query may include multiple metrics to create comprehensive querie.

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.
Average Engaged Time (Video) 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_plays= A count of the number of times a video was played.

Filter

Adding a filter to your query allows you to specify a variable you’d like to focus on. Use the filter parameter to dive deeper into your historical metrics and create querie that reflect specific audience breakdowns.

Filter API Syntax Description
Author author= The author of a page.
Browser browser= The web browser used (i.e. android, blackberry, chrome, firefox, internet_explorer, opera, safari, unknown)
Content Type contenttype= The content type (e.g. gallery, article) as tagged on your site.
Demographics demo= If your site sends Chartbeat custom demographic values they will appear under this demo field (Unique to your domain)
Demo_type demo_type= Demographic type (Unique to your domain)
Device device= The device used (desktop, mobile, tablet)
Distribution distribution= The distribution channel used (site/facebook_ia/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)
Referrer referrer= The referring domain.
Referrer Type referrer_type= The page referrer type: social, search, direct, internal, links.
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)
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.
Video Path video_path= The URL/path of the video.
Video Title video_title= Title of the video.

Group

Use the group by parameter to select the criteria for which your metrics are returned, such as time of day, geographic location, demographic, and page specific data. Adding additional groups allows you to create more dynamic querie.

Parameter API Syntax Description
Author author= The author of a page.
Browser browser= The web browser used.
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.
Country country= The country the visitor was in.
Demographics demo= If your site sends Chartbeat custom demographic values they will appear under this demo field (unique to your domain).
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 querie 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 internal_path= Histogram of the page load time.
Page Type pagetype= The type of page, returned as either article, landing page, 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 queryed path of the page.
Referrer referrer= The referring domain.
Referrer Type referrer_type= The page referrer type: social, search, direct, internal, and 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.
Subdomain subdomain= The specific subdomain.
Subscriber subscriber= The visitor's subscriber status (Guest, Registered, Subscribed, Unspecified).
Section section= The section of a site 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.
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. Use paired with Hour to get per-minute time series.
New/Returning user_status= Returns 1 for new visitors and 0 for returning.
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 day (in UTC) to get hourly time series.
Minute (in UTC) utc_minute= The minute in the UTC time zone. Use paired with hour (in UTC) to get per-minute time series.
Visitor Frequency visit_frequency= Returns new, returning, or loyal.
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.
Video Path video_path= The URL/path of the video.
Video Title video_title= Title of the video.

Here are some ways to get in touch.