Getting Started with Data Lab API

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 API key here 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=	Note: Your API key should no longer be set as a query param; instead. pass it in the HTTP header
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=	A comma-separated list of values to return (e.g. column=ts_bin,page_views,visit_frequency). See list of accepted column options below.
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	The content type (e.g. gallery, article), as set in your site or AMP code via the type or contentType variable.
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	The visitor's subscriber status (Guest, Registered, Subscribed, Unspecified).
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.