# Recurring 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/`**](#submit-recurring-query) 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/`**](#get-status-of-recurring-query) 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/`**](#fetch-recent-recurring-query-run) 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 (*see note*) | string | **NOTE**: Your API key should no longer be set as a query param; instead, [pass it in the HTTP header](https://docs.chartbeat.com/cbp/api/historical-api/getting-started-with-our-historical-api#required-parameters) | | `host` | string | Site ID for the Site you are querying traffic data | | `limit` | integer | Base-10 values only | | `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 to obtain) | | {filter} | string | `{filter}` is a placeholder value. Choose from our [list of filter parameters](https://docs.chartbeat.com/cbp/api/historical-api/metrics-dimensions-filters#filters), and pass in a filter value. For example: `§ion=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) | {% tabs %} {% tab title="200 Returns a query ID for user in subsequent status and fetch calls. Example ID:" %} ```scheme {query_id: "4ed64430-9049-469b-8eee-e38d265017dc"} ``` {% endtab %} {% endtabs %} ## 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 | | `host` | string | Site ID for the Site of your submit call | | apikey (*see note*) | string | **NOTE**: Your API key should no longer be set as a query param; instead, [pass it in the HTTP header](https://docs.chartbeat.com/cbp/api/historical-api/getting-started-with-our-historical-api#required-parameters) | {% tabs %} {% tab title="200 Wait for run\_status of "completed" before making your fetch call." %} ```scheme { status: "active", host: "site.com", query_id: "fff04f41-f33e-4c93-aa5b-b0677b0703f7", run_status: "completed" } ``` {% endtab %} {% endtabs %} ## 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 | | `format` | string | Set to `json` to return data in JSON format instead of CSV | | apikey (*see note*) | string | **NOTE**: Your API key should no longer be set as a query param; instead, [pass it in the HTTP header](https://docs.chartbeat.com/cbp/api/historical-api/getting-started-with-our-historical-api#required-parameters) | {% tabs %} {% tab title="200 Returns traffic data from your query!" %} ``` //Will return .csv formatted data, unless providing format=json parameter ``` {% endtab %} {% endtabs %} ## 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 | | `host` | string | Site ID (usually your site's root domain) | | apikey (*see note*) | string | **NOTE**: Your API key should no longer be set as a query param; instead, [pass it in the HTTP header](https://docs.chartbeat.com/cbp/api/historical-api/getting-started-with-our-historical-api#required-parameters) | {% tabs %} {% tab title="200 Example response listing previous run IDs:" %} ```scheme { 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 }, {...} ``` {% endtab %} {% endtabs %} ## 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 (*see note*) | string | **NOTE**: Your API key should no longer be set as a query param; instead, [pass it in the HTTP header](https://docs.chartbeat.com/cbp/api/historical-api/getting-started-with-our-historical-api#required-parameters) | {% tabs %} {% tab title="200 Example response:" %} ```scheme { 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: [] }, {...} ``` {% endtab %} {% endtabs %} ## 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 | | `host` | string | Site ID for the query you are canceling | | apikey (*see note*) | string | **NOTE**: Your API key should no longer be set as a query param; instead, [pass it in the HTTP header](https://docs.chartbeat.com/cbp/api/historical-api/getting-started-with-our-historical-api#required-parameters) | {% tabs %} {% tab title="200  Successful cancellation response lists your host and query ID:" %} ```scheme { "host": "mysite.co.uk", "query_id": "83ea4ccf-5fea-4695-98b3-2d032ab3c1c7" } ``` {% endtab %} {% endtabs %}