Recurring Queries

Learn how to use our six recurring query endpoints to submit a new query, check the query run status, fetch query results and manage existing queries.

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.

Getting data back from a recurring query for the first time is a three-step process:

  1. Run a /submit/ call to submit your new query and receive a query ID.

  2. Wait for your first query run to complete — 4AM the next day for daily queries, 4AM the next Monday for weekly queries, 4AM the next first calendar month day for monthly queries. THEN, run a /status/ call to check the status of your submitted query using the query ID from your previous call to the /submit/ endpoint. Continue running as frequently as every ten seconds or so until you receive a completed status for your query.

  3. Once the status of your query is completed, run a /fetch/ call with the original query ID to download your completed query results. Continue using the same query ID to check status and fetch your updated results with every day, week, or month that passes.

get
Submit Recurring Query

https://api.chartbeat.com/query/v2/recurring/submit/
The expected return value of this call is a query ID that can be used to both check the status of your query and fetch the results when ready. The "filter" parameter is simply a stand-in for the value that you want to filter by; select the dimension that you want to filter the data by, and specify the value for that dimension. Note: Metrics and Dimensions should come before Filters in the appended query parameter sequence.
Request
Response
Request
Path Parameters
endpoint
required
string
Append page/ or video/ to the API endpoint URL above after /submit/, before attaching the query params below. This determines whether your query accesses page or video data.
Query Parameters
apikey
required
string
Your API key
host
required
string
Site ID for the Site you are querying traffic data
limit
required
integer
Set no higher than 10000 rows — must be base ten
sort_column
required
string
Metric or Dimension to sort your queried data by
sort_order
required
string
Either asc (ascending) or desc (descending) for your sort column
tz
required
string
Timezone in a valid Olson timezone format, e.g. America/New_York
metrics
required
string
Comma-separated list of metrics to include in the query results
date_range
required
string
Set to day, week, or month
user_id
required
number
Unique user ID for your personal Chartbeat login (contact support@chartbeat.com to obtain)
{filter}
optional
string
Use a dimension parameter as the query param key
dimensions
optional
string
Comma-separated list of dimensions to include in the query results
email
optional
string
Email address(es) to send recurring query results (comma-delimited)
Response
200: OK
Returns a query ID for user in subsequent status and fetch calls. Example ID:
{query_id: "4ed64430-9049-469b-8eee-e38d265017dc"}

get
Get Status of Recurring Query

https://api.chartbeat.com/query/v2/recurring/status/
Use the /recurring/status/ endpoint to check on the status of your recurring query. Wait for your query status to return "completed" before making the fetch call. Run status will display as null, queued, or completed.
Request
Response
Request
Query Parameters
query_id
required
string
Your query ID from the original submit call
apikey
required
string
Your API key
host
required
string
Site ID for the Site of your submit call
Response
200: OK
Wait for run_status of "completed" before making your fetch call.
{
status: "active",
host: "site.com",
query_id: "fff04f41-f33e-4c93-aa5b-b0677b0703f7",
run_status: "completed"
}

get
Fetch Recent Recurring Query Run

https://api.chartbeat.com/query/v2/recurring/fetch/
The /recurring/fetch/ endpoint will download the data for a completed query (default format is a CSV file).
Request
Response
Request
Query Parameters
host
required
string
Site ID for the Site of your submit call
query_id
required
string
Query ID from your original submit call
apikey
required
string
Your API key
format
optional
string
Set to json to return data in JSON format instead of CSV
Response
200: OK
Returns traffic data from your query!
//Will return .csv formatted data, unless providing format=json parameter

get
Get Previous Recurring Query Runs

https://api.chartbeat.com/query/v2/recurring/runs/
Use this endpoint to return a list of run IDs associated with previous runs for your daily, weekly, or monthly query. To fetch data for a previous run, use the Fetch One-time Query call with your run ID assigned to the query_id parameter.
Request
Response
Request
Query Parameters
query_id
required
string
Query ID from the original submit call
apikey
required
string
Your API key
host
required
string
Site ID (usually your site's root domain)
Response
200: OK
Example response listing previous run IDs:
{
host: "mysite.com",
query_id: "10d92ad1-b3ae-4304-9b00-9cebe8e7e88d",
runs:[
{
run_id:"358a1352-8236-4435-ad53-278d0207af3d",
max_ts: 1591959600
},
{
run_id:"3a6a5258-f3b9-4257-b073-c56cd7e4d711",
max_ts: 1591873200
},
{
run_id:"c834d709-912f-46b4-88bd-b47385927928",
max_ts: 1591786800
},
{...}

get
Get Recurring Queries List

https://dashapi.chartbeat.com/query/v2/recurring/list/
Use the /recurring/list/ endpoint to view details of all active recurring queries for a given Site on your account.
Request
Response
Request
Query Parameters
host
required
string
Chartbeat Site ID (usually root domain of the site you're querying)
apikey
required
string
Your API key
Response
200: OK
Example response:
{
host: "site.com",
queries: [{
status: "active",
expiration_ts: 1454634551,
row_limit: 100,
sort_column: [
"page_views desc"
],
date_range: "day",
host: "site.com",
query_timezone: "America/New_York",
filters: {
section: [
"news"
]
},
interface: 0,
next_report_time: 1587700800,
metrics: [
"page_views"
],
endpoint: "page",
user_id: "######",
dimensions: [
"user_status",
"scroll_hist"
],
allow_null: 0,
query_num: 42,
query_id: "tCsnemrT-2vQ7-glkA-KwYt-hkLjk3ecXvN0R",
query_submission_ts: 1423116551,
query_name: null,
email_addresses: []
},
{...}

get
Cancel Recurring Query

https://api.chartbeat.com/query/v2/recurring/cancel/
Use this call to cancel a specific recurring query that you created.
Request
Response
Request
Query Parameters
query_id
required
string
Query ID for the query you want to cancel
apikey
required
string
Your API key
host
required
string
Site ID for the query you are canceling
Response
200: OK
 Successful cancellation response lists your host and query ID:
{
"host": "mysite.co.uk",
"query_id": "83ea4ccf-5fea-4695-98b3-2d032ab3c1c7"
}