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.

Submit Recurring Query

GET 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.

Path Parameters

Name	Type	Description
endpoint	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

Name	Type	Description
apikey	string	Your API key
host	string	Site ID for the Site you are querying traffic data
limit	integer	Set no higher than 10000 rows — must be base ten
sort_column	string	Metric or Dimension to sort your queried data by
sort_order	string	Either asc (ascending) or desc (descending) for your sort column
tz	string	Timezone in a valid Olson timezone format, e.g. America/New_York
metrics	string	Comma-separated list of metrics to include in the query results
date_range	string	Set to day, week, or month
user_id	number	Unique user ID for your personal Chartbeat login (contact [e-mail] to obtain)
{filter}	string	{filter} is a placeholder value. Choose from our list of filter parameters (see the final page of this guide), and pass in a filter value. For example: &section=news
dimensions	string	Comma-separated list of dimensions to include in the query results
email	string	Email address(es) to send recurring query results (comma-delimited)

200 Returns a query ID for user in subsequent status and fetch calls. Example ID:

{query_id: "4ed64430-9049-469b-8eee-e38d265017dc"}

Get Status of Recurring Query

GET 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.

Query Parameters

Name	Type	Description
query_id	string	Your query ID from the original submit call
apikey	string	Your API key
host	string	Site ID for the Site of your submit call

200 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"
}

Fetch Recent Recurring Query Run

GET 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).

Query Parameters

Name	Type	Description
host	string	Site ID for the Site of your submit call
query_id	string	Query ID from your original submit call
apikey	string	Your API key
format	string	Set to json to return data in JSON format instead of CSV

200 Returns traffic data from your query!

//Will return .csv formatted data, unless providing format=json parameter

Get Previous Recurring Query Runs

GET 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.

Query Parameters

Name	Type	Description
query_id	string	Query ID from the original submit call
apikey	string	Your API key
host	string	Site ID (usually your site's root domain)

200 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 Recurring Queries List

GET 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.

Query Parameters

Name	Type	Description
host	string	Chartbeat Site ID (usually root domain of the site you're querying)
apikey	string	Your API key

200 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: []
    },
{...}

Cancel Recurring Query

GET https://api.chartbeat.com/query/v2/recurring/cancel/

Use this call to cancel a specific recurring query that you created.

Query Parameters

Name	Type	Description
query_id	string	Query ID for the query you want to cancel
apikey	string	Your API key
host	string	Site ID for the query you are canceling

200 Successful cancellation response lists your host and query ID:

{
    "host": "mysite.co.uk",
    "query_id": "83ea4ccf-5fea-4695-98b3-2d032ab3c1c7"
}