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

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

{
    status: "active",
    host: "site.com",
    query_id: "fff04f41-f33e-4c93-aa5b-b0677b0703f7",
    run_status: "completed"
}

//Will return .csv formatted data, unless providing format=json 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
        },
{...}

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