Follow-Up: The PageView History API is Now in Beta!

[sgergely]

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):

1. 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.
2. 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!

[dbrace]

Thank you for this, @sgergely. I look forward to using it.

I do have a few pieces of feedback from my first time looking at this:

1. Since start_date and end_date are formatted as YYYY-MM-DD and not YYYY-MM-DDTHH:MM:SSZ, how do time zones / UTC / ISO 8601 come into play?
   1. As an example, if I use a start_date of 2025-07-01, will it actually be 2025-07-01T04:00:00Z (Tuesday, July 1, 2025 at 12:00 AM ET) or 2025-07-01T00:00:00Z (Monday, June 30, 2025 at 8:00 PM ET) or will it be something else?
   2. It might not seem to matter but some user account activity could overlap the end or beginning of a month.
2. While not its designed purpose, will start_date and end_date accept the current month (for the start_date) and the next month (for the end_date)?
   1. If not, what will happen?
   2. I ask because from the UI for the "Page Views" area under "1-year activity", it is possible to request the CSV for the current month and that is helpful.
3. Since a specific user and time range query is cached for 24 hours, even though the data is meant to be historical and in the past, would it be possible to incorporate a DELETE endpoint (using the query_id that was initially received) so that someone can delete the previous request and do a new request?
   1. There would probably also need to be a new status (since the documentation shows that currently the only statuses are processing and finished) added as well.
   2. As you might be able to see, my #2 relates to #3. It is helpful to have a CSV of user account activity that has occured in the last 30 days or that day. With the changes that have been implemented over the last few months, that is no longer possible.
4. What happens if someone tries to query/download the results and more than 24 hours has passed?
5. How can someone find out when the query will expire or when it did expire?
6. When using the API, will anything appear for the user account and its "Page Views" area under "1-year activity"?

-Doug