Getting Started with our Historical API
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.
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.
The following parameters are necessary to include in both your one-time and recurring queries:
Parameter Name | Syntax | Description |
API Key |
| Your Chartbeat API Key. |
Endpoint |
| Choose between |
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, host=video@mysite.com. |
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 |
| The column you'd like to sort the query on. |
Sort Order |
| The order of the sort ( |
Timezone |
| The timezone you'd like to run the query in a valid Olson timezone format, e.g. America/New_York. |
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.
One-time queries must also include the start and end date parameters:
Parameter Name | Syntax | Description |
Start Date |
| Start of date range to pull data from. |
End Date |
| End of date range to pull data from. |
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 |
| The frequency for your recurring query to run; |
Check out the next three pages of this guide to find all the information you need to get started using our Historical API.
