Getting Started with our Historical API

Get familiar with our Advanced Queries Historical API for fetching summary historical traffic data with specified start and end times. Note that Advanced Queries is a Premium feature.

Our Advanced Queries API endpoints may be used to retrieve summary historical data for your site in either one-time or recurring queries, downloadable in CSV or JSON format.

Advanced Queries reports are highly customizable with a wide array of metrics, filters, and dimensions available to return specific summary traffic data about your audience engagement with your online content over time.

One-time vs recurring queries

There are two query types to pick from:

One-time queries are good for pulling data over custom date ranges. One-time queries must be submitted anew for every unique run if your team wants to run the same report (using the same metrics, dimensions, and/or filters) over unique date ranges (using unique start and end date parameters).

Recurring queries are only submitted once, but they continue to generate new reports for every calendar day, week, or month. This is a good option for teams that want to pull in the same traffic data with every day, week, or month that passes. The query start and end times are defined by the selected date range option:

• Daily recurring queries (date_range=day) return data for the previous 24-hour calendar day based on your selected timezone for the query. These queries begin a new run at 12:01AM each day for their selected timezone, and should be completed (available to fetch) by 4AM.

• Weekly recurring queries (date_range=week) return data for the previous 7-day calendar week (12:00AM Monday - 11:59PM Sunday) based on your selected timezone for the query. These queries begin a new run at 12:01AM every Monday for their selected timezone, and should be completed (available to fetch) by 4AM Monday.

• Monthly recurring queries (date_range=month) return data for the previous calendar month based on your selected timezone for the query. These queries begin a new run at 12:01AM on the first calendar day of every month for their selected timezone, and should be completed (available to fetch) by 4AM on the first day.

Required parameters

API Key: This should 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://api.chartbeat.com/query/v2/submit/page/?host=YOUR_HOST&limit=100&start=YYYY-MM-DD&end=YYYY-MM-DD&sort_column=page_views&sort_order=desc&tz=America/New_York&metrics=page_views,page_uniques&dimensions=path,title"

The following parameters are necessary to include in both your one-time and recurring queries:

API Key	apikey=	NOTE: Your API key should no longer be set as a query param; instead, pass it in the HTTP header
Endpoint	endpoint=	Choose between page and video data. Video data is only available for Sites with active Video Dashboards.
Host	host=	The Site you are querying (site ID is usually your website's root domain). If you are using our video API endpoint, the host value is your site ID prepended with "video@". For example, [email protected].
Limit	limit=	The number of rows you'd like to pull in your query. Large calls are susceptible to 504 gateway timeouts, so we recommend setting no more than 10,000 rows.
Sort Column	sort_column=	The column you'd like to sort the query on.
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.
Metrics	metrics=	Every query must include one or more specified metrics (traffic data returned in the report).

Note: The complete list of available metrics, dimensions, and filter parameters is included in the fourth and final page of this guide: Metrics, Dimensions, and Filters.

Additional required parameters for one-time queries

One-time queries must also include the start and end date parameters:

Parameter Name	Syntax	Description
Start Date	start=yyyy-mm-dd	Start of date range to pull data from.
End Date	end=yyyy-mm-dd	End of date range to pull data from.

Additional required parameters for recurring queries

Recurring queries do not accept the start and end date parameters, and instead require the date range parameter set to day, week, or month:

Parameter Name	Syntax	Description
Date Range	date_range=	The frequency for your recurring query to run; day for daily, week for weekly, month for monthly.

Next steps

Check out the next three pages of this guide to find all the information you need to get started using our Historical API.

One-time QueriesRecurring QueriesMetrics, Dimensions, and Filters