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 API parameters
The following parameters are necessary to include in both your one-time and recurring queries:
Parameter Name
Syntax
Description
API Key
apikey=
Your Chartbeat API Key.
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 "[email protected]". For example, [email protected]
Limit
limit=
The number of rows you'd like to pull in your query. Limits must be base-ten; while there is no hard-limit, large calls are susceptible to 504 gateway timeouts. 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 Queries
Recurring Queries
Metrics, Dimensions, and Filters

API Docs - Previous

Historical API

One-time Queries

Last modified 11mo ago

Copy link

Contents

One-time vs recurring queries

Required API parameters

Additional required parameters for one-time queries

Additional required parameters for recurring queries

Next steps