Following our recent announcement about the changes to the Canvas Page Views feature, we are excited to share a major update specifically for our developer community and partners: The new PageView History API is now available in Beta!
This new asynchronous API is designed to solve the need for accessing large volumes of historical Page View data, moving beyond the 30-day limit imposed on the standard List user page views API.
Accessing Historical Data: A New Asynchronous Approach
As we mentioned previously, the legacy API provides excellent performance for real-time and recent (30-day) data. The PageView History API is built to handle the heavy lifting of querying and generating large historical datasets, which requires a different, asynchronous workflow.
A Unified Data Strategy for Customers
A critical feature of this release is data consistency. Both the new PageView History API and the standard List user page views API accommodate the same PageViews object structure. This unified object model enables a powerful data strategy for our partners that might be familiar for those who are already using our DAP Query API (CD2):
- Initial Snapshot: Use the new PageView History API to pull a comprehensive historical snapshot of data across any timeframe up to the last 12 months. This forms the baseline dataset stored on your premises.
- Incremental Updates: Use the existing, high-performance List user page views API (which provides the last 30 days) to pull regular, incremental updates.
By combining these two APIs, you can efficiently build and maintain a complete, up-to-date PageViews dataset locally.
Here is the three-step process to access comprehensive historical Page View data:
1. Initiate the Query
The new workflow begins with the Initiate page views query endpoint.
- You will use this endpoint to start the historical data retrieval job.
- In your request, you specify the desired date range and any other filtering criteria for the data you need.
- The API will immediately return a job ID, allowing you to move on to other tasks while the data is being compiled.
- IMPORTANT LIMITATION: Currently, only one PageView History query can be run in parallel per Canvas instance.
24-Hour Result Caching: If you initiate an export query for a specific user and time range, the result is cached for 24 hours. Any identical query submitted within that window will not run again; instead, it will return the link to the cached result. To ensure you retrieve the absolute latest data (within the last 30 days), we still recommend using the standard List user page views API for incremental updates.
2. Poll the Status
Since gathering large volumes of historical data takes time, you must monitor the job's progress using the Poll query status endpoint.
- Using the job ID received in the first step, you will periodically call this endpoint to check if the query has finished processing.
- Once the status indicates the query is complete and the results are ready, you can move to the final step.
3. Get the Results
The final step is to download the compiled data using the Get query results endpoint.
- This endpoint will provide a link or mechanism to download the full, requested historical data set, which is formatted for easy consumption.
- This structure ensures that you can reliably pull extensive datasets without the limitations or time-outs associated with synchronous requests.
- Availability Check: You can issue a `HEAD` request to this endpoint to retrieve only the result status code, which is useful for checking the file's availability and size without initiating a full download.
- Expiration Handling: Be aware that the download link is temporary, it is only valid for 24 hours. If the results are no longer available (e.g., the file has expired from storage), this endpoint may return a `410 Gone` status code.
Get Started Today
We encourage all partners and developers who require historical Page View data to begin testing this new API in the Beta environment.
You can find the full documentation, including endpoint specifics, parameters, and response details, on the Canvas Developer site:
PageView History API Documentation (Beta)
Your feedback during this Beta period is invaluable as we work to finalize this feature for general release!
