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

NameTypeDescription

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

NameTypeDescription

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 support@chartbeat.com 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)

{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

NameTypeDescription

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

{
    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

NameTypeDescription

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

//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

NameTypeDescription

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)

{
    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

NameTypeDescription

host

string

Chartbeat Site ID (usually root domain of the site you're querying)

apikey

string

Your API key

{
  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

NameTypeDescription

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

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

Last updated