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
  • Required API Parameters
  • Columns

Was this helpful?

  1. API Docs
  2. Data Lab API

Getting Started with Data Lab API

PreviousData Lab API

Last updated 9 days ago

Was this helpful?

This section contains information on how to make requests to Chartbeat’s Data Lab API endpoint to return a CSV or JSON gzipped file.

Required API Parameters

API Key: To be passed in the HTTP Header with "X-CB-AK". You can create and access your under your account settings. Make sure to select an API key that has access to all calls for your domain.

Example CURL request

curl --header "X-CB-AK: YOUR-API-KEY" "https://dashapi.chartbeat.com/datalab_api/get_data?host=chartbeat.com&start=2025-01-01&end=2025-01-02&tz=America%2FNew_York&columns=ts_bin,host,path,page_views&serialization=csv" > foo.csv.gz

Note: > foo.csv.gz is the name of the gzipped file that will be automatically downloaded when you make this request. For json, use the format foo.json.gz

The following parameters are necessary to include in the query.

Parameter name
Syntax
Description

API Key

apikey=

Host name

host=

The site dashboard you are querying (this is usually your website's root domain, e.g. host=website.com). Accepts one value. Do not include https or www.

Start Date

start=

Start date of query. Format: YYYY-MM-DD

End Date

end=

End date of query. Format: YYYY-MM-DD

Timezone

tz=

Timezone (e.g. America/New_York)

Columns

columns=

Serialization

serialization=

Format for the returned data. JSON or CSV. (e.g. &serialization=json). Responses can be downloaded as a gzipped file (i.e. filename.csv.gz or filname.json.gz

Columns

Use the columns param and include one or more of the accepted options below in a comma-separated list.

Column name
Description

browser

The web browser used by a visitor to access the site (e.g., Chrome, Firefox, Safari).

content_type

country

The visitor's country.

device

The visitor's device (desktop, mobile, or tablet)

engaged_page_views

Pageviews that received at least 15 seconds of engaged time.

engaged_time

The amount of time in seconds visitors were actively engaged (scrolling/typing/tapping) on a page.

host

The site dashboard name, usually the root domain.

internal_path

The internal page path that users clicked away from when they opened a new page on the site.

loyalty_type

New, Returning, or Loyal. (Also known as Visitor Frequency)

os

The operating system used (e.g. android, ios, chrome)

page_avg_scroll

The average maximum depth that visitors have scrolled to, in pixels, from the top of the page.

page_scroll_starts

The percentage of page views where a scroll event occurred, expressed as a decimal.

page_type

The type of page. Article, LandingPage, or Unknown.

page_views_loyal

Pageviews from visitors who visit your site an average of every other day, or a minimum of eight unique days in a 16 day period.

page_views_quality

Pageviews that received at least 15 seconds of engaged time.

page_views

The number of pages viewed.

path

The URL/path of the page.

pinger_source

The distribution channel used (Site/App).

referrer_type

The page referrer type: social, search, direct, internal, and external (aka links).

referrer

The referring domain.

region

The visitor's region (returns states for US).

scroll_hist

Histogram of the number of pixels scrolled in 100 pixel bins.

scrolled_page_views

Count of pageviews where a user has scrolled.

site_experience

The site experience for the visitor (AMP/Standard). An NA value indicates that the visitor comes from an off-site distribution channel.

subdomain

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

subscriber_type

total_scroll

Sum of the total number of pixels scrolled.

ts_bin

Hourly time bin.

utm_campaign

Identifies a specific promotion/campaign.

utm_content

Identifies what specifically was clicked.

utm_medium

Identifies the type of link, ‘email’ for example.

utm_source

Identifies to which site a link was posted.

utm_term

Identifies search term/terms.

visit_frequency

Number of days out of the last 15 that this user has visited; min 0, max 15. Can be used to calculate a custom "Visitor Frequency" metric.

Note: Your API key should no longer be set as a query param; instead.

A comma-separated list of values to return (e.g. column=ts_bin,page_views,visit_frequency). See list of accepted column options .

The content type (e.g. gallery, article), as set in your or code via the type or contentType variable.

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

API key here
pass it in the HTTP header
site
AMP
subscriber status
below