Render API
👤 This documentation is intended for Developers.
The Render API is a great way to dynamically generate a downloadable pdf image of an entire dashboard for uses like email distribution and static embeds.
Note: Render API is an add-on feature. Site administrators can contact their Account Manager for additional information.
Using the API
Before using the API, ensure that all charts fit within the PDF page lines (viewable when charts are resized or moved). For optimal performance, ensure charts that are using the Render API are querying against the origin database and refrain from using dashboards that have a long-running query.
The Render API URL takes the following form as a POST request:
https://api.periscopedata.com/api/v1/screenshot_requests
Customers can make a request to the API using the following format:
HEADERS
Content-Type:application/json
HTTP-X-PARTNER-AUTH:<site_name>:<api_key>
BODY
{
"data" : {
"dashboard_id": 1234,
"daterange": {"start": "2015-01-01", "end": "2015-01-05"},
"aggregation": "daily",
"filters": [{"name": "AGE", "value": [1, 2]}],
"dashboard_ts": 1446069112
}
}
Each of these parameters are discussed in detail below.
Site Name
In this section, enter the site name, found in the dashboard's URL. In the example below, the site name is examplesite.
https://app.periscopedata.com/app/examplesite/1234/My-Dashboard
API Key
The account's API key is under the Settings Gear Icon Menu -> Billing and Authentication under Authentication. This ensures only account users are able to make Render API requests.
Dashboard ID
The dashboard ID can be found in the dashboard's URL, immediately preceding the dashboard name. For instance, the dashboard ID for "My Dashboard" is 1234.
https://app.periscopedata.com/app/examplesite/1234/My-Dashboard
Daterange Filter
When using the pre-built daterange filter options or selecting a number of days before the current date, include it using:
"daterange": {"days": 7}
When using a custom range, the user must specify the start and end dates:
"daterange": {"start": "2015-01-01", "end": "2015-01-05"},
Aggregation Filter
To include the dashboard aggregation in the JSON blob, add the following on its own line in the blob:
"aggregation": "daily"
Custom Filters
If the user wants to pass custom filters to the Render API link, include them like so:
"filters": [{"name": "Filter1", "value": "value1"}, {"name": "Filter2", "value": "1234"}]
If there are multiple filter values to be included for the same filter, there are the options to either include it twice or pass an array:
"filters": [{"name": "Filter1", "value": "1234"}, {"name": "Filter1", "value": "5678"}] "filters": [{"name": "Filter1", "value": ["1234", "5678"]}]
To implement child filters, an additional parameter that specifies the group (parent value) must be included. This will always be equivalent to the value of the parent filter being used:
"filters": [{"name": "ParentFilter", "value": 1234}, {"name": "ChildFilter", "value": "5678", "group": "1234"}]
When using filters in the chart titles, the display value, which is populated into the chart title, must be included. The JSON blob cannot be used with the array syntax to ensure proper parsing:
"filters": [{"name": "Filter1", "value": "1234", "display": "Display1"}]
Unused Filters
If a filter is not being used, simply omit it from the blob and no value will be passed for it.
Data Latency
The dashboard_ts value is integer seconds since the epoch (Note: millisecond precision is not supported). Charts with data older than this timestamp will be refreshed and show the updated data in the returned image.
Render API Usage
Run the JSON defining the above dashboard parameters. Sisense allows 60 API requests a minute. Sisense will return a 429 error if this limit is exceeded. If a 429 error occurs, please retry the request after one minute.
Sisense allows 500 Render API requests every 24 hours.
The response will include a URL that points to a file on S3 with the PDF of the dashboard screenshot.
Example:
{
"url": "https://periscope-render-virginia.s3.amazonaws.com/734091687549dd3swpfc01ad094ce9.pdf"
}
Note: The S3 URL is a pre-signed URL and does expire after 3 days.
The S3 URL will be immediately generated. However, please allow a few minutes for the PDF to become available. Initially, the URL will point to a text file containing 'Screenshot not ready.' Once the PDF has been uploaded, the URL will point to the downloadable PDF.
The default limit is 30 widgets for the dashboard to produce a PDF. In order to increase this limit contact the support team at support@periscopedata.com
