Datasets API

The Datasets API is part of our new partner data product, Slate Analytics. Unlike other Slate reports, datasets are append-only (each file has new data), are not available for download in the Slate UI (but are accessible via API only), and are built explicitly for partner data engineers to consume granular data and perform analytics. This topic helps data engineers set up their pipelines to retrieve dataset, defines the values in the dataset files, and provides sample queries and suggestions for the optimal ways partners can use this data.

Practical use of datasets

We provide datasets to consumers in the form of a changelog. Each event is published only once. However, if any column values for a previously provided row need to be updated, we will publish a new version of the record to reflect the changes in your next available file. The changelog is append-only, to ensure that all data modifications are captured. Data engineers can use this changelog to update their data tables directly.

When you process the changelog, it’s essential to always use the latest record for a given event_id, based on the last_update_time_utc column. This ensures that you always have the most up-to-date version of each record. If a record needs to be deleted, this action is reflected in the is_deleted column. A value of 1 indicates that the record has been deleted, while a value of 0 represents an active record. This changelog approach allows you to effectively manage new and changing data, and ensures that your data tables remain accurate and up to date with the latest information.

Before you make requests to the Dataset API, it’s important to understand the basic requirements for authentication and pagination. This section covers how to securely access the API and navigate large datasets efficiently.

Authentication
To retrieve datasets you must have:

1. A login with Amazon Security Profile
2. An authorization code to request a token
3. A token for all curl requests

The base URI is: https://videocentral.amazon.com/apis/v2. All requests should include a valid LWA authentication token in the request authorization header. For example:

If the request header doesn’t include the token, or if the token is expired, the Datasets API will return an unauthorized exception.

Pagination
All Slate API responses are paginated. Pagination parameters are specified through requests parameters.

All paginated responses contain the following fields.

To programmatically access datasets, clients should follow a series of API calls that enumerate available resources—such as accounts, groups, businesses, and datasets—before retrieving downloadable URLs for the data files. This sequence is designed to support automation and can be integrated into recurring data pipelines or scheduled workflows.

List accounts
/v2/accounts

This resource returns the list of Slate accounts that the user can access. The set of accounts is accessible in Slate through the accounts dropdown list near the top right corner of the portal. You can also use these links to find your account_id or your channel/studio_id.

List groups (business lines)
/v2/accounts/{account_id}

This resource returns the groups of business lines (such as channels) that the user can access.

List businesses
/v2/accounts/{account_id}/{group_id}

This resource returns a list of businesses (such as specific channel names) available for this account, depending on the given business line.

List available datasets
/v2/accounts/{acccount_id}/{group_id}/{business_id}/datasets

This resource returns the list of datasets available for a given channel or studio. (The list of available datasets and their attributes are included in Dataset definitions, later in this topic.) The datasets currently available to download are:

• Subscription: Events in the customer lifecycle, such as when a customer subscribed.
• Playback: Playback session events where customers engaged with content.
• Catalog: Events where your catalog metadata has changed, such as when a new title was added.

Obtain dataset file(s)
/v2/accounts/{account_id}/{group_id}/{partition_id}/datasets/{dataset_id}

This resource provides a list of dataset files. Depending on the requested time range, the list may include a large number of files. The total field indicates how many files to expect. After completing a full backfill, you can stay up to date by continuing to request files using a startDateTime equal to the last retrieved timestamp and an endDateTime set to the current time.

New datasets are published approximately every 4 hours, and may contain events that have occurred within the previous 12 hours. We recommend calling our API multiple times per day, approximately every 4-6 hours, to ensure your local data is as complete and up-to-date as possible. If we experience a delay in publishing, we will communicate through email as soon as possible.

The following table describes the available request parameters for dataset files.

Note: Our maximum data retention is 2 years. Requests for datasets with a timestamp earlier than 2 years prior will not return any results.

The tables in this section list the columns, data types, and definitions for each of the 3 available datasets.

Subscription dataset

Playback dataset

Catalog dataset

The following SQL example demonstrates how the dataset tables connect. You can join playback data to the subscription event log on the subscription_event_id column. This provides the latest subscription status prior to that stream. In this example, the catalog_id column in the playback dataset is joined to the id field in catalog_event_log to provide all catalog metadata.

The following SQL example will return the top 10 first-watched titles for customers post their having started a subscription.

If you want to automate data extraction from the Datasets API on a recurring schedule, the following sample Python script demonstrates how to make incremental API calls every 6 hours. It tracks the timestamp of the last successful request by persisting it locally, and uses that value—plus one second—as the startDateTime for the next call. The script calculates endDateTime as the current time, builds the appropriate query parameters, and sends a GET request with authentication. This approach ensures continuous, non-overlapping data retrieval across time windows and can be scheduled via cron or another job scheduler.