# 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**](https://chartbeat.com/publishing/settings/api-keys/) 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-01T00:00:00&end=2025-01-02T00:00:00&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.

<table><thead><tr><th width="186.19270833333331">Parameter name</th><th width="161.21875">Syntax</th><th>Description</th></tr></thead><tbody><tr><td>API Key</td><td><code>apikey=</code></td><td>Note: Your API key should no longer be set as a query param; instead. <a href="https://docs.chartbeat.com/cbp/api/conversion-api/getting-started-with-our-conversion-api#required-api-parameters">pass it in the HTTP header</a></td></tr><tr><td>Host name</td><td><code>host=</code></td><td>The site dashboard you are querying (this is usually your website's root domain, e.g. <code>host=website.com</code>). Accepts one value. Do not include https or www.</td></tr><tr><td>Start Date/Time</td><td><code>start=</code></td><td>Start date and timestamp of query. Format: <code>YYYY-MM-DDTXX:XX:XX</code>  </td></tr><tr><td>End Date/Time</td><td><code>end=</code></td><td>End date and timestamp of query. Format: <code>YYYY-MM-DDTXX:XX:XX</code></td></tr><tr><td>Timezone</td><td><code>tz=</code></td><td>Timezone (e.g. <code>America/New_York</code>)</td></tr><tr><td>Columns</td><td><code>columns=</code></td><td>A comma-separated list of values to return (e.g. <code>column=ts_bin,page_views,visit_frequency</code>). See list of accepted column options <a href="#columns">below</a>.</td></tr><tr><td>Serialization</td><td><code>serialization=</code></td><td>Format for the returned data. JSON or CSV. (e.g. <code>&#x26;serialization=json</code>). Responses can be downloaded as a gzipped file (i.e. <code>filename.csv.gz</code> or <code>filname.json.gz</code></td></tr></tbody></table>

### Columns

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

<table><thead><tr><th width="222.765625">Column name</th><th>Description</th></tr></thead><tbody><tr><td>browser</td><td>The web browser used by a visitor to access the site (e.g., Chrome, Firefox, Safari).</td></tr><tr><td>content_type</td><td>The content type (e.g. gallery, article), as set in your <a href="https://docs.chartbeat.com/cbp/tracking/standard-websites/configuration-variables#content-type">site</a> or <a href="https://docs.chartbeat.com/cbp/tracking/google-amp/amp-configuration-variables#additional-amp-variables">AMP</a> code via the <code>type</code> or <code>contentType</code> variable. </td></tr><tr><td>country</td><td>The visitor's country.</td></tr><tr><td>device</td><td>The visitor's device (desktop, mobile, or tablet)</td></tr><tr><td>engaged_page_views</td><td>Pageviews that received at least 15 seconds of engaged time.</td></tr><tr><td>engaged_time</td><td>The amount of time in seconds visitors were actively engaged (scrolling/typing/tapping)  on a page.</td></tr><tr><td>host</td><td>The site dashboard name, usually the root domain.</td></tr><tr><td>internal_path</td><td>The internal page path that users clicked away from when they opened a new page on the site.</td></tr><tr><td>loyalty_type</td><td>New, Returning, or Loyal. (Also known as Visitor Frequency)</td></tr><tr><td>os</td><td>The operating system used (e.g. <code>android</code>, <code>ios</code>, <code>chrome</code>)</td></tr><tr><td>page_avg_scroll</td><td>The average maximum depth that visitors have scrolled to, in pixels, from the top of the page.</td></tr><tr><td>page_scroll_starts</td><td>The percentage of page views where a scroll event occurred, expressed as a decimal.</td></tr><tr><td>page_type</td><td>The type of page. Article, LandingPage, or Unknown.</td></tr><tr><td>page_views_loyal</td><td>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.</td></tr><tr><td>page_views_quality</td><td>Pageviews that received at least 15 seconds of engaged time.</td></tr><tr><td>page_views</td><td>The number of pages viewed.</td></tr><tr><td>path</td><td>The URL/path of the page.</td></tr><tr><td>pinger_source</td><td>The distribution channel used (Site/App).</td></tr><tr><td>referrer_type</td><td>The page referrer type: social, search, direct, internal, and external (aka links).</td></tr><tr><td>referrer</td><td>The referring domain.</td></tr><tr><td>region</td><td>The visitor's region (returns states for US).</td></tr><tr><td>scroll_hist</td><td>Histogram of the number of pixels scrolled in 100 pixel bins.</td></tr><tr><td>scrolled_page_views</td><td>Count of pageviews where a user has scrolled.</td></tr><tr><td>site_experience</td><td>The site experience for the visitor (AMP/Standard). An NA value indicates that the visitor comes from an off-site distribution channel.</td></tr><tr><td>subdomain</td><td>The specific subdomain (e.g. blog.chartbeat.com, chartbeat.com).</td></tr><tr><td>subscriber_type</td><td>The visitor's <a href="https://docs.chartbeat.com/cbp/tracking/standard-websites/subscriber-engagement">subscriber status</a> (Guest, Registered, Subscribed, Unspecified).</td></tr><tr><td>total_scroll</td><td>Sum of the total number of pixels scrolled.</td></tr><tr><td>ts_bin</td><td>Hourly time bin.</td></tr><tr><td>utm_campaign</td><td>Identifies a specific promotion/campaign.</td></tr><tr><td>utm_content</td><td>Identifies what specifically was clicked.</td></tr><tr><td>utm_medium</td><td>Identifies the type of link, ‘email’ for example.</td></tr><tr><td>utm_source</td><td>Identifies to which site a link was posted.</td></tr><tr><td>utm_term</td><td>Identifies search term/terms.</td></tr><tr><td>visit_frequency</td><td>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.</td></tr></tbody></table>