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:
Run a /submit/
call to submit your new query and receive a query ID.
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.
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.
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.10000
rows — must be base tenasc
(ascending) or desc
(descending) for your sort columnday
, week
, or month
{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: §ion=news
{query_id: "4ed64430-9049-469b-8eee-e38d265017dc"}
/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.{status: "active",host: "site.com",query_id: "fff04f41-f33e-4c93-aa5b-b0677b0703f7",run_status: "completed"}
/recurring/fetch/
endpoint will download the data for a completed query (default format is a CSV file).json
to return data in JSON format instead of CSV//Will return .csv formatted data, unless providing format=json parameter
query_id
parameter.{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},{...}
/recurring/list/
endpoint to view details of all active recurring queries for a given Site on your account.{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: []},{...}
{"host": "mysite.co.uk","query_id": "83ea4ccf-5fea-4695-98b3-2d032ab3c1c7"}