Periscope Data Documentation

Connecting to Periscope

First Time Connecting

Connection Definitions

Common Connection Errors

Private Network SSH Tunnels



Getting Started

Keyboard Shortcuts

Charts & Dashboards

Chart Overview

Chart Options

Dashboard Overview

Refresh Mechanics

Organizing Charts

Organizing Dashboards

Table-like Charts

Table Overview

Cohort Grids

Pivot Tables

Graph-like Charts

Overview & General Settings

Chart Types and Settings

Mixing Chart Types

Map Charts

Map Chart Overview


Clusters and Bubbles

Satellite Maps


Other Charts & Customizations

Pie Charts

Image Charts

Chart Annotations

Site Administration

Adding Users

Removing Users

User Types

User Groups

Two-Factor Authentication

Managing User Permissions

Dashboard Permissions

Site Preferences

Query Management

Color Themes

Dashboard Refresh Management

Usage Data

Periscope Cache

Caching Strategies

Querying the Periscope Cache

Cross-Database Joins

CSV Upload

Materializing Views

SQL Formatters

Using SQL Formatters

Composing SQL Formatters

Dollars and Percentages

Time Zone Formatters

Date Aggregation

Date Parts

Basic Filters

Custom Filters

Date Range Filters

Aggregation Filter

Adding, Moving, and Hiding Filters

Advanced Filters

Default Filters


Parent-Child Filters

Matching Filter Values

Time Zone Conversions

Direct Replacement

User Friendly Names


SQL Views

Joining to Views

More SQL Tools

SQL Snippets

Parameterized SQL Snippets

SQL Alerts

Automatic Joins

Version History

Sharing and Embedding

Sharing Dashboards Externally

Email Reports

Easy Embedding

Embed API

Embed API Options

CSV Download

Public CSV URL

Slack API

Slack Linking Reports

Data Management

Adding and Deleting Datasource

Spaces: Data-Level Permissions

Improving Query Throughput

Revoking Table Permissions

Salesforce Datasource

Schema Browser

SSO Integrations




Google Apps

Dashboard and Chart Refresh Mechanics

Dashboard Refresh Rates

Periscope automatically schedules a dashboard to be refreshed regularly in the background with usage. At the moment of refresh, all charts on a dashboard are passed into the refresh queue at the same time.

Background Refreshes

Periscope will refresh dashboards in the background. If a dashboard goes more than 7 days without being viewed, it is deemed inactive and will no longer update once a day.

Each filter combination for a dashboard is considered a separate dashboard all together, and refreshes are based off of the dashboard with that particular filter set. For example, dashboard A with Filter1 applied to it may be viewed constantly, and have a higher frequency refresh schedule. Dashboard A with Filter2 applied to it may rarely be viewed, and refresh less frequently.

Manual refreshes can be launched for all of the charts on a dashboard by selecting the refresh button in the dashboard header. This should look similar to the following image:

The last time a dashboard was refreshed, as well as the total query runtime for the dashboard, can be viewed by hovering over the infomational 'i' icon. This is shown in the Dashboard Overview Documentation Page

Users can also choose to only be able to manually refresh dashboards and turn off automatic background refreshes by emailing

Chart Refresh Rates

Charts do not have their own individual refresh rates. They are automatically refreshed when their dashboards get scheduled to refresh. Individual charts can be manually refreshed by selecting the "Refresh Chart" icon that appears when hovering over a saved chart. It should look similar to the image shown below.

Shared and Embedded Dashboards

Shared and Embedded Dashboards refresh with the same logic described above. Each Shared or Embedded dashboard is considered its own separate dashboard if charts on it uses filters that are set to different values. It will automatically refresh depending on how often it is viewed (with its specific filter set applied), and how often its underlying dashboard is viewed with those same filters on Periscope.

Manually Refresh the Data

Shared and Embedded Dashboards can be manually refreshed by navigating to the original dashboard on Periscope. Once there, the user would want to apply the exact same filter values used to generate the Shared or Embedded dashboards. Then, the user would click the refresh button described earlier on this page. After refreshing the dashboard, navigating back to the Shared or Embedded Dashboard should reflect this update.

Controlling Refresh Rate in Embedded Dashboards

The Periscope Embed API includes a parameter called "data_ts" that is used to determine whether or not to refresh the dashboard. Setting this parameter does not guarantee that the dashboard is refreshed constantly. The parameter requires a unix timestamp, and does not work for values in the future. The best recommended practice for quick refreshes is to set the data_ts parameter to be a few minutes back from the present time.

Public CSV URL

Refresh rates for Public CSV URL data follow the same rates as the underlying dashboard with the specific filter set for a specific user. The specific filter set is determined by the user who generated the URL at the time of generation.

Emailed Dashboards

Dashboards can be scheduled to email once a day or once a week. To set that up, follow the instructions here.

By default, Emailed Dashboards are scheduled to refresh with the default filter set. Charts on the dashboard are refreshed at the specified time, and the email is sent upon completion of the refresh.

Manually Refreshing Data for Emailed Dashboards

As described earlier in the Shared and Emailed Dashboards section, a refresh can be manually enforced by applying the default filters and refreshing all the charts.