Audiencelab Data Specifications

1. Data Location

Storage

Data is stored on AWS S3 under the following bucket:

audiencelab-processed

Path Format

s3://audiencelab-processed/table={table_name}/year={year}/month={month}/day={day}/hour={hour}/api_key={your_api_key}/

{table_name}: Name of the table (e.g., PURCHASE, AD, basic_retention, etc.)
{year}/{month}/{day}/{hour}: Partitions based on UTC date and hour
{your_api_key}: The API key tied to the data

Data is delivered to S3 in hourly batches, usually around 20 minutes past each hour. Folders are partitioned by hour, where hour represents the start of the interval. For instance, data for 14:00–14:59 UTC resides in the folder hour=14.

Time Zone Details

Default: UTC-based partitioning
For ad network "_updated" tables, data retrieval uses the ad account's local time zone, as the updates roll up "yesterday's" data based on the local date in that time zone

3. Available Tables and Schemas

Below are the primary tables with their purposes, schemas, and partition examples. Note that some events contain utc_offset and local_time columns, enabling analysis by user's local time if desired.

3.1 Purchase Events (PURCHASE)

Description

Records all in-game purchase events.

Schema

Field	Type	Description
creative_token	string	Creative identifier
id (purchase_id)	string	Purchase ID
name (purchase_name)	string	Purchase name
status	string	Purchase status
device_model	string	Device model
os_system	string	Operating system
currency	string	Currency code
value	float	Purchase value
retention_day	float	Day of retention
created_at	string	Timestamp (YYYY-MM-DD HH:MM:SS)
date	string	Date (YYYY-MM-DD)
utc_offset	string	UTC offset
local_time	string	Local timestamp (YYYY-MM-DD HH:MM:SS)

Partition Example

table=PURCHASE/year=2025/month=01/day=01/hour=00/api_key=your_api_key/

3.2 Ad Events (AD)

Description

Contains in-game ad view events, including any value attributed to each view.

Schema

Field	Type	Description
creative_token	string	Creative identifier
source	string	Ad source
media_source	string	Media source
channel	string	Ad channel
id (ad_id)	string	Ad ID
name (ad_name)	string	Ad name
reward	string	Reward information
device_model	string	Device model
os_system	string	Operating system
currency	string	Currency code
watch_time	float	Watch time in seconds
retention_day	float	Day of retention
value	float	Ad value
created_at	string	Timestamp (YYYY-MM-DD HH:MM:SS)
date	string	Date (YYYY-MM-DD)
utc_offset	string	UTC offset
local_time	string	Local timestamp (YYYY-MM-DD HH:MM:SS)

Partition Example

table=AD/year=2025/month=01/day=01/hour=00/api_key=your_api_key/

3.3 Retention Events (basic_retention & rolling_retention)

Description

Includes basic retention data (basic_retention) and rolling retention data (rolling_retention). Rolling retention "fills in" missing active days between user sessions.

Schema

Field	Type	Description
creative_token	string	Creative identifier
device_model	string	Device model
os_system	string	Operating system
retention_day	int	Day of retention
backfill_day	int	Backfill day
created_at	string	Timestamp (YYYY-MM-DD HH:MM:SS)
start_date	string	Start date (YYYY-MM-DD)
utc_offset	string	UTC offset
local_time	string	Local timestamp (YYYY-MM-DD HH:MM:SS)

Partition Examples

table=basic_retention/year=2025/month=01/day=01/hour=00/api_key=your_api_key/
table=rolling_retention/year=2025/month=01/day=01/hour=00/api_key=your_api_key/

3.4 Browser Metrics (browser_metrics_insert)

Description

Includes browser-specific usage metrics. Also contains rolling retention details that fill in missing active days between user sessions.

Schema

Field	Type	Description
creative_token	string	Creative identifier
browser_name	string	Browser name
device_vendor	string	Device vendor
os_system	string	Operating system
count	int	Metric count
created_at	string	Timestamp (YYYY-MM-DD HH:MM:SS)
date	string	Date (YYYY-MM-DD)

Partition Example

table=browser_metrics_insert/year=2025/month=01/day=01/hour=00/api_key=your_api_key/

3.5 Device Metrics (device_metrics)

Description

Contains device specifications and location details from user sessions.

Schema

Field	Type	Description
creative_token	string	Creative identifier
city	string	City
country	string	Country
created_at	string	Timestamp (YYYY-MM-DD HH:MM:SS)
device_model	string	Device model
device_name	string	Device name
dpi	int	Screen DPI
gpu_rendered	string	GPU renderer
gpu_vendor	string	GPU vendor
gpu_version	string	GPU version
height	float	Screen height
isp	string	Internet service provider
lat	float	Latitude
legacy_height	float	Legacy screen height
legacy_width	float	Legacy screen width
lon	float	Longitude
low_battery_level	bool	Low battery indicator
org	string	Organization
os_system	string	Operating system
region_name	string	Region name
timezone	string	Timezone
width	float	Screen width
zip	string	ZIP code

Partition Example

table=device_metrics/year=YYYY/month=MM/day=DD/hour=HH/api_key=your_api_key/

3.6 Ad Networks

Description

Contains ad network campaign data, with creative_token parsed from the URL. Two distinct table types exist:

{network} (e.g., meta): Data updated hourly with previous hour's metrics
{network}_updated (e.g., meta_updated): Data updated daily at 12 PM local ad account time, capturing finalized metrics (because hourly data can be retroactively adjusted) from previous day

Schema

Field	Type	Description
creative_token	string	Creative identifier
impressions	int	Number of impressions
clicks	int	Number of clicks
spend	float	Spend in USD (converted using daily exchange rate)
spend_original	float	Original spend in account currency
created_at	string	Timestamp (YYYY-MM-DD HH:MM:SS)
date	string	Date (YYYY-MM-DD)
run_at	string	Run timestamp (YYYY-MM-DD HH:MM:SS)

Partition Examples (for Meta)

table=meta/year=2025/month=01/day=01/hour=00/api_key=your_api_key/
table=meta_updated/year=2025/month=01/day=01/api_key=your_api_key/

Supported Networks

meta, meta_updated
google, google_updated
tiktok, tiktok_updated

s3://audiencelab-processed/metadata.json

s3://audiencelab-processed/table=metadata/api_key=your_api_key/creative_metadata.parquet

Important Notes

All timestamps are generally stored in UTC unless otherwise specified
For "_updated" tables, the local time zone of the ad account determines the "daily" cutoffs
The utc_offset and local_time fields (in relevant tables) enable local-time-based analytics

Audiencelab Data Specifications

On this page