Content Reporting

Showpad's Content Reporting API service (also known as the Export API) enables you to generate and download everything you see in the Reports section of Showpad's Admin App, including asset views, share activity, Shared Space participation, and more.

What you'll learn:

How to export content analytics data as CSV or JSON
The data model and available export tables
Request parameters for filtering and pagination
How to handle large data volumes with scroll IDs

TL;DR

Export JSON? Use GET /api/v3/exports/events.json
Export CSV? Use GET /api/v3/exports/events.csv
Large datasets? Use the X-Showpad-Scroll-Id header for pagination
Filter by date? Use startedAt and endedAt parameters

When to use the API

BI Integration	Custom Dashboards	Data Warehouse	Automated Reports
Connect Showpad data to Power BI, Tableau, or Looker for unified analytics.	Build custom visualizations tailored to your organization's KPIs.	Store historical data in Snowflake, BigQuery, or Redshift for long-term analysis.	Schedule automated data pulls to generate recurring reports.

Prerequisites

Plan: Ultimate | Advanced or Expert
Permissions: Administrator access to Showpad's Admin App
Authentication: Valid OAuth 2.0 access token (learn more)

Quick Reference

Jump to detailed documentation:

Event Types Lookup Relations Example Queries

Data Model

Content Reporting Diagram

Export Tables

Nearly all exports begin with the Events table. This table is the central table for exporting content data. All content-related actions a user can make are tracked as in this table. All other export tables (lookup) relate to the Events (fact) table.

Requests

Base Endpoint

The base endpoint for event calls is https://{{subdomain}}.showpad.biz/api/v3/exports/events. Every request must be prefixed with this base endpoint.

Export JSON

To export in JSON format, use the .json extension in your request.

cURL
JavaScript
Python

curl -X GET "https://{subdomain}.showpad.biz/api/v3/exports/events.json" \
  -H "Authorization: Bearer {access_token}"

const response = await fetch('https://{subdomain}.showpad.biz/api/v3/exports/events.json', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {access_token}',
  },
});

const data = await response.json();
console.log(data);

import requests

url = "https://{subdomain}.showpad.biz/api/v3/exports/events.json"
headers = {"Authorization": "Bearer {access_token}"}

response = requests.get(url, headers=headers)
print(response.json())

Example Response

{
  "meta": {
    "count": 2
  },
  "response": {
    "items": [
      {
        "id": "evt_abc123",
        "eventType": "asset-viewed",
        "userId": "usr_xyz789",
        "assetId": "ast_def456",
        "startedAt": "2024-03-15T10:30:00Z",
        "endedAt": "2024-03-15T10:32:45Z",
        "duration": 165
      },
      {
        "id": "evt_abc124",
        "eventType": "asset-shared",
        "userId": "usr_xyz789",
        "assetId": "ast_def456",
        "startedAt": "2024-03-15T10:33:00Z"
      }
    ]
  }
}

Export CSV

To export in CSV format, use the .csv extension in your request.

cURL
JavaScript
Python

curl -X GET "https://{subdomain}.showpad.biz/api/v3/exports/events.csv" \
  -H "Authorization: Bearer {access_token}"

const response = await fetch('https://{subdomain}.showpad.biz/api/v3/exports/events.csv', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {access_token}',
  },
});

const data = await response.text();
console.log(data);

import requests

url = "https://{subdomain}.showpad.biz/api/v3/exports/events.csv"
headers = {"Authorization": "Bearer {access_token}"}

response = requests.get(url, headers=headers)
print(response.text)

Note

CSV is only available in the Exports endpoints.

Parameters

Name	Type	Format	Description
`channelIds`	string		Only include events with the specified channel IDs. You can list multiple IDs by separating them with a comma.
`endedAt`	string	`YYYY-MM-DD` \| `YYYY-MM-DD HH:mm:ss`	Only include events that happened before this date.
`eventType`	string		Only include events with the specified event type. You can list multiple event types by separating them by a comma.
`limit`	integer	`int32`	Sets the maximum number of returned items. The maximum limit is set to 1000. For example, if `limit` is 50, only 50 items will be retrieved.
`loggedAfter`	string	`YYYY-MM-DD` \| `YYYY-MM-DD HH:mm:ss`	Only include events that have been logged to Showpad after this date (for offline use, this is when the device comes online).
`loggedBefore`	string	`YYYY-MM-DD` \| `YYYY-MM-DD HH:mm:ss`	Only include events that have been logged to Showpad before this date (for offline use, this is when the device comes online).
`pageBased`	boolean	`true` \| `false`	Include page-based information in events.
`startedAt`	string	`YYYY-MM-DD` \| `YYYY-MM-DD HH:mm:ss`	Only include events that happened after this date.
`userId`	string		Only include events for a specified user by user ID.

info

For an exhaustive overview of all event types, see Event Types.

Control Returned Items

By default, the maximum number of returned items with the Events call is set to 500. You can use the limit parameter to change this to any value between 50 and 1000.

For larger volumes of data, we include a header in the response, called X-Showpad-Scroll-Id which contains a token. If you make the same request again but set this header on your second request, the events call will return the second batch of requests.

The second reponse will contain another X-Showpad-Scroll-Id header which you can then use to fetch the third batch of requests, and so on. The X-Showpad-Scroll-Id is not changed with every new response but it is valid for a limited time. We recommend always using the scroll id from your most recent response in your next call.

You can loop your requests this way until all data is fetched. Once the response contains no more events, this indicates that no more data can be fetched.

Potential Data Variations

When comparing exports with the reports in the Admin App, data may differ for several reasons:

Asset View Data

The Admin App calculates reports differently than raw API exports. For example, in the Top Content report, shares are calculated as the number of times content is shared with someone. A document shared with two people counts as two shares. If the report says 100 shares, that represents 100 different users who shared content.

Details per page

You can export details per page. When aggregating view events on an asset per user, note that there's an event for every page and an event for the whole document. For asset analytics matching the Admin App (whole document only), filter where page = NULL.

Deleted records

Users, user groups, and assets can be deleted. Admin App reporting excludes events related to deleted or inactive users. To match these results, filter out records based on the deletedAt field in the relevant tables.

Date filtering

For date filtering, use the startedAt field of the events.

Divisions

Assets belong to a library (which is a Division). Instances can have one or more Divisions. Personal files are also a Division, accessible only by that user. There is a division field on events, but it's safest to join Divisions with asset tables rather than event tables.

Offline events

Showpad apps track events when offline and sync when back online. These events retain the original startTime and endTime timestamps. Use the loggedAt timestamp to detect when data was received by the server.

Error Handling

For standard HTTP errors (401, 403, 429, etc.), see the Error Codes reference.

Content Reporting-Specific A 500 error often indicates an expired scroll ID. Always use the most recent

X-Showpad-Scroll-Id from your last response when paginating. :::

Rate Limits

The Content Reporting API has the following limits:

Max items per request: 1,000 (use limit parameter)
Default items per request: 500
Scroll ID expiration: Limited time validity. Always use the most recent scroll ID.

Best Practice For large data exports, implement exponential backoff and always persist the latest

X-Showpad-Scroll-Id to resume interrupted exports. :::

Next Steps

Event Types: Complete list of all event types returned by the API
Lookup Relations: Field definitions and table relationships
Example Queries: SQL examples for analyzing your exported data

Was this page helpful?

When to use the API​

Quick Reference​

Data Model​

Export Tables​

Requests​

Base Endpoint​

Export JSON​

Export CSV​

Parameters​

Control Returned Items​

Potential Data Variations​

Error Handling​

Rate Limits​

Next Steps​