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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.chartbeat.com/cbp/api/data-lab-api/getting-started-with-data-lab-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.