Reddit Ads connector reference

Beta

This feature is in Beta. Workspace admins can control access to this feature from the Previews page. See Manage Databricks previews.

This page provides reference information for the managed Reddit Ads connector in Lakeflow Connect, including supported tables, column definitions, and data types.

Supported source tables

The Reddit Ads connector supports the following types of tables:

• Entity tables: Configuration data about your Reddit Ads account, such as campaigns, ad groups, and ads. These tables are fully refreshed on each pipeline run.
• Report tables: Performance metrics, such as impressions, clicks, and spend. These tables support incremental ingestion.
• Custom report: A user-defined table that lets you choose breakdown dimensions and metric fields. See Custom reports.

Entity tables

Table name	Description
ad_account	Ad accounts accessible to the authenticated user. Lives in the default source schema.
campaign	Campaign configuration and settings.
ad_group	Ad group configuration and settings.
ad	Individual ad details and settings. Corresponds to ads in the Reddit Ads API.

Table name	Description
ad_account	Ad accounts accessible to the authenticated user. Lives in the default source schema.
campaign	Campaign configuration and settings.
ad_group	Ad group configuration and settings.
ad	Individual ad details and settings. Corresponds to ads in the Reddit Ads API.

Report tables

Table name	Primary key	Description
campaign_report	campaign_id, date	Campaign-level performance metrics.
ad_group_report	ad_group_id, date	Ad group-level performance metrics.
ad_report	ad_id, date	Ad-level performance metrics.
campaign_country_report	campaign_id, date, country	Campaign-level performance metrics broken down by country.

Table name	Primary key	Description
campaign_report	campaign_id, date	Campaign-level performance metrics.
ad_group_report	ad_group_id, date	Ad group-level performance metrics.
ad_report	ad_id, date	Ad-level performance metrics.
campaign_country_report	campaign_id, date, country	Campaign-level performance metrics broken down by country.

Data type conventions

Currency

Monetary columns — for example, spend, cpc, bid_value — are stored as decimal(19,2) in the ad account's currency. Values are decimal amounts (for example, 12.34), not micros. The account's currency code is available in the ad_account.currency column and in the report currency column.

JSON columns

Some entity table columns contain complex nested objects stored as JSON strings: targeting, schedule, event_trackers. Parse these with from_json() or parse_json() in SQL or PySpark.

Incremental cursor

Report tables use metrics_updated_at (timestamp) as the incremental cursor.

Entity table schemas

ad_account

Ad accounts accessible to the authenticated user. This table lives in the default source schema.

Column	Data type	Description
id	string	Primary key. Ad account ID.
name	string	Ad account name.
type	string	Account type.
admin_approval	string	Admin approval status.
business_id	string	Associated business ID.
created_at	timestamp	When the account was created.
modified_at	timestamp	When the account was last modified.
currency	string	Account currency code, for example USD.
time_zone_id	string	Account time zone.
attribution_type	string	Attribution type setting.
app_attribution_type	string	App attribution type setting.
click_attribution_window	string	Click attribution window.
view_attribution_window	string	View attribution window.
app_click_attribution_window	string	App click attribution window.
app_view_attribution_window	string	App view attribution window.
spend_cap_type	string	Spend cap type.
suspension_reason	string	Reason for account suspension, if applicable.
excluded_communities	array<string>	Communities excluded from targeting.
excluded_keywords	array<string>	Keywords excluded from targeting.
pixel_partner_preferences	array<string>	Pixel partner preferences.
primary_contact_member_id	string	Primary contact member ID.

Column	Data type	Description
id	string	Primary key. Ad account ID.
name	string	Ad account name.
type	string	Account type.
admin_approval	string	Admin approval status.
business_id	string	Associated business ID.
created_at	timestamp	When the account was created.
modified_at	timestamp	When the account was last modified.
currency	string	Account currency code, for example USD.
time_zone_id	string	Account time zone.
attribution_type	string	Attribution type setting.
app_attribution_type	string	App attribution type setting.
click_attribution_window	string	Click attribution window.
view_attribution_window	string	View attribution window.
app_click_attribution_window	string	App click attribution window.
app_view_attribution_window	string	App view attribution window.
spend_cap_type	string	Spend cap type.
suspension_reason	string	Reason for account suspension, if applicable.
excluded_communities	array<string>	Communities excluded from targeting.
excluded_keywords	array<string>	Keywords excluded from targeting.
pixel_partner_preferences	array<string>	Pixel partner preferences.
primary_contact_member_id	string	Primary contact member ID.

campaign

Campaign configuration and settings.

Column	Data type	Description
id	string	Primary key. Campaign ID.
ad_account_id	string	Associated ad account ID.
name	string	Campaign name.
objective	string	Campaign objective.
configured_status	string	User-set status (ACTIVE or PAUSED).
effective_status	string	Effective delivery status.
delivery_status	array<string>	Detailed delivery status reasons.
created_at	timestamp	When the campaign was created.
modified_at	timestamp	When the campaign was last modified.
start_time	timestamp	Campaign start time.
end_time	timestamp	Campaign end time.
bid_type	string	Bid type.
bid_strategy	string	Bid strategy.
bid_value	decimal(19,2)	Bid value in account currency.
goal_type	string	Goal type.
goal_value	decimal(19,2)	Goal value in account currency.
spend_cap	decimal(19,2)	Spend cap in account currency.
conversion_pixel_id	string	Associated conversion pixel ID.
funding_instrument_id	string	Associated funding instrument ID.
optimization_goal	string	Optimization goal.
view_through_conversion_type	string	View-through conversion type.
app_id	string	Associated app ID.
invoice_label	string	Invoice label.
is_max	boolean	Whether campaign budget optimization is in MAX mode.
is_campaign_budget_optimization	boolean	Whether campaign budget optimization is enabled.
special_ad_categories	array<string>	Special ad categories (for example, housing, credit).
skadnetwork_metadata	string	SKAdNetwork metadata.
age_restriction	string	Age restriction setting.

Column	Data type	Description
id	string	Primary key. Campaign ID.
ad_account_id	string	Associated ad account ID.
name	string	Campaign name.
objective	string	Campaign objective.
configured_status	string	User-set status (ACTIVE or PAUSED).
effective_status	string	Effective delivery status.
delivery_status	array<string>	Detailed delivery status reasons.
created_at	timestamp	When the campaign was created.
modified_at	timestamp	When the campaign was last modified.
start_time	timestamp	Campaign start time.
end_time	timestamp	Campaign end time.
bid_type	string	Bid type.
bid_strategy	string	Bid strategy.
bid_value	decimal(19,2)	Bid value in account currency.
goal_type	string	Goal type.
goal_value	decimal(19,2)	Goal value in account currency.
spend_cap	decimal(19,2)	Spend cap in account currency.
conversion_pixel_id	string	Associated conversion pixel ID.
funding_instrument_id	string	Associated funding instrument ID.
optimization_goal	string	Optimization goal.
view_through_conversion_type	string	View-through conversion type.
app_id	string	Associated app ID.
invoice_label	string	Invoice label.
is_max	boolean	Whether campaign budget optimization is in MAX mode.
is_campaign_budget_optimization	boolean	Whether campaign budget optimization is enabled.
special_ad_categories	array<string>	Special ad categories (for example, housing, credit).
skadnetwork_metadata	string	SKAdNetwork metadata.
age_restriction	string	Age restriction setting.

ad_group

Ad group configuration and settings.

Column	Data type	Description
id	string	Primary key. Ad group ID.
ad_account_id	string	Associated ad account ID.
campaign_id	string	Associated campaign ID.
name	string	Ad group name.
configured_status	string	User-set status.
effective_status	string	Effective delivery status.
delivery_status	array<string>	Detailed delivery status reasons.
created_at	timestamp	When the ad group was created.
modified_at	timestamp	When the ad group was last modified.
start_time	timestamp	Ad group start time.
end_time	timestamp	Ad group end time.
bid_type	string	Bid type.
bid_strategy	string	Bid strategy.
bid_value	decimal(19,2)	Bid value in account currency.
goal_type	string	Goal type.
goal_value	decimal(19,2)	Goal value in account currency.
conversion_pixel_id	string	Associated conversion pixel ID.
optimization_goal	string	Optimization goal.
view_through_conversion_type	string	View-through conversion type.
is_campaign_budget_optimization	boolean	Whether campaign budget optimization is active for this ad group.
campaign_objective_type	string	Campaign objective type.
app_id	string	Associated app ID.
product_set_id	string	Associated product set ID.
shopping_type	string	Shopping type.
saved_audience_id	string	Saved audience ID.
targeting	string	JSON string containing targeting settings.
shopping_targeting	string	Shopping targeting settings.
schedule	string	JSON string containing ad scheduling settings.
skadnetwork_metadata	string	SKAdNetwork metadata.

Column	Data type	Description
id	string	Primary key. Ad group ID.
ad_account_id	string	Associated ad account ID.
campaign_id	string	Associated campaign ID.
name	string	Ad group name.
configured_status	string	User-set status.
effective_status	string	Effective delivery status.
delivery_status	array<string>	Detailed delivery status reasons.
created_at	timestamp	When the ad group was created.
modified_at	timestamp	When the ad group was last modified.
start_time	timestamp	Ad group start time.
end_time	timestamp	Ad group end time.
bid_type	string	Bid type.
bid_strategy	string	Bid strategy.
bid_value	decimal(19,2)	Bid value in account currency.
goal_type	string	Goal type.
goal_value	decimal(19,2)	Goal value in account currency.
conversion_pixel_id	string	Associated conversion pixel ID.
optimization_goal	string	Optimization goal.
view_through_conversion_type	string	View-through conversion type.
is_campaign_budget_optimization	boolean	Whether campaign budget optimization is active for this ad group.
campaign_objective_type	string	Campaign objective type.
app_id	string	Associated app ID.
product_set_id	string	Associated product set ID.
shopping_type	string	Shopping type.
saved_audience_id	string	Saved audience ID.
targeting	string	JSON string containing targeting settings.
shopping_targeting	string	Shopping targeting settings.
schedule	string	JSON string containing ad scheduling settings.
skadnetwork_metadata	string	SKAdNetwork metadata.

ad

Individual ad details and settings. Corresponds to ads in the Reddit Ads API.

Column	Data type	Description
id	string	Primary key. Ad ID.
ad_account_id	string	Associated ad account ID.
ad_group_id	string	Associated ad group ID.
campaign_id	string	Associated campaign ID.
name	string	Ad name.
type	string	Ad type.
configured_status	string	User-set status.
effective_status	string	Effective delivery status.
delivery_status	array<string>	Detailed delivery status reasons.
created_at	timestamp	When the ad was created.
modified_at	timestamp	When the ad was last modified.
click_url	string	Destination URL when the ad is clicked.
click_url_query_parameters	string	Query parameters appended to the click URL.
campaign_objective_type	string	Campaign objective type.
post_id	string	Associated Reddit post ID.
post_url	string	URL of the associated Reddit post.
profile_id	string	Associated profile ID.
preview_url	string	Ad preview URL.
preview_expiry	timestamp	When the preview URL expires.
event_trackers	string	JSON string containing event tracker configurations.
products	string	Associated products.
rejection_reason	string	Reason for ad rejection, if applicable.
shopping_creative	string	Shopping creative settings.
skadnetwork_metadata	string	SKAdNetwork metadata.

Column	Data type	Description
id	string	Primary key. Ad ID.
ad_account_id	string	Associated ad account ID.
ad_group_id	string	Associated ad group ID.
campaign_id	string	Associated campaign ID.
name	string	Ad name.
type	string	Ad type.
configured_status	string	User-set status.
effective_status	string	Effective delivery status.
delivery_status	array<string>	Detailed delivery status reasons.
created_at	timestamp	When the ad was created.
modified_at	timestamp	When the ad was last modified.
click_url	string	Destination URL when the ad is clicked.
click_url_query_parameters	string	Query parameters appended to the click URL.
campaign_objective_type	string	Campaign objective type.
post_id	string	Associated Reddit post ID.
post_url	string	URL of the associated Reddit post.
profile_id	string	Associated profile ID.
preview_url	string	Ad preview URL.
preview_expiry	timestamp	When the preview URL expires.
event_trackers	string	JSON string containing event tracker configurations.
products	string	Associated products.
rejection_reason	string	Reason for ad rejection, if applicable.
shopping_creative	string	Shopping creative settings.
skadnetwork_metadata	string	SKAdNetwork metadata.

Report table schemas

All report tables share the same metric columns. They differ only in their primary key columns.

Shared metric columns

Every report table includes account_id (string) and the following metric columns:

Core delivery

Column	Data type	Description
impressions	long	Number of impressions.
clicks	long	Number of clicks.
spend	decimal(19,2)	Total spend in account currency.
ecpm	decimal(19,2)	Effective cost per thousand impressions.
cpc	decimal(19,2)	Cost per click.
cpv	decimal(19,2)	Cost per view.
ctr	double	Click-through rate.
reach	long	Number of unique users reached.
frequency	double	Average number of times each user saw the ad.
viewable_impressions	long	Number of viewable impressions.
engaged_click	long	Number of engaged clicks.
reddit_leads	long	Number of Reddit leads.
conversion_roas	double	Return on ad spend from conversions.

Column	Data type	Description
impressions	long	Number of impressions.
clicks	long	Number of clicks.
spend	decimal(19,2)	Total spend in account currency.
ecpm	decimal(19,2)	Effective cost per thousand impressions.
cpc	decimal(19,2)	Cost per click.
cpv	decimal(19,2)	Cost per view.
ctr	double	Click-through rate.
reach	long	Number of unique users reached.
frequency	double	Average number of times each user saw the ad.
viewable_impressions	long	Number of viewable impressions.
engaged_click	long	Number of engaged clicks.
reddit_leads	long	Number of Reddit leads.
conversion_roas	double	Return on ad spend from conversions.

Engagement (populated for engagement campaigns; null for other campaign types)

Column	Data type	Description
upvotes	long	Number of upvotes on the ad.
downvotes	long	Number of downvotes on the ad.
comment_upvotes	long	Number of upvotes on comments.
comment_downvotes	long	Number of downvotes on comments.
comment_submissions	long	Number of comments submitted.
comment_page_views	long	Number of comment page views.

Column	Data type	Description
upvotes	long	Number of upvotes on the ad.
downvotes	long	Number of downvotes on the ad.
comment_upvotes	long	Number of upvotes on comments.
comment_downvotes	long	Number of downvotes on comments.
comment_submissions	long	Number of comments submitted.
comment_page_views	long	Number of comment page views.

Video plays and watch time

Column	Data type	Description
video_started	long	Number of times video playback started.
video_plays_expanded	long	Number of times the video was expanded.
video_plays_with_sound	long	Number of plays with sound on.
video_watched_3_seconds	long	Number of views reaching 3 seconds.
video_watched_5_seconds	long	Number of views reaching 5 seconds.
video_watched_10_seconds	long	Number of views reaching 10 seconds.
video_watched_25_percent	long	Number of views reaching 25% completion.
video_watched_50_percent	long	Number of views reaching 50% completion.
video_watched_75_percent	long	Number of views reaching 75% completion.
video_watched_95_percent	long	Number of views reaching 95% completion.
video_watched_100_percent	long	Number of views reaching 100% completion.

Column	Data type	Description
video_started	long	Number of times video playback started.
video_plays_expanded	long	Number of times the video was expanded.
video_plays_with_sound	long	Number of plays with sound on.
video_watched_3_seconds	long	Number of views reaching 3 seconds.
video_watched_5_seconds	long	Number of views reaching 5 seconds.
video_watched_10_seconds	long	Number of views reaching 10 seconds.
video_watched_25_percent	long	Number of views reaching 25% completion.
video_watched_50_percent	long	Number of views reaching 50% completion.
video_watched_75_percent	long	Number of views reaching 75% completion.
video_watched_95_percent	long	Number of views reaching 95% completion.
video_watched_100_percent	long	Number of views reaching 100% completion.

Video rates and viewability

Column	Data type	Description
video_view_rate	double	Video view rate.
video_view_rate_6_seconds	double	Video view rate at 6 seconds.
video_view_rate_15_seconds	double	Video view rate at 15 seconds.
video_completion_rate	double	Video completion rate.
video_fully_viewable_impressions	long	Number of fully viewable impressions.
video_viewable_impressions	long	Number of viewable impressions.
video_viewable_watched_6_seconds	long	Number of viewable impressions watched 6 seconds.
video_viewable_watched_15_seconds	long	Number of viewable impressions watched 15 seconds.

Column	Data type	Description
video_view_rate	double	Video view rate.
video_view_rate_6_seconds	double	Video view rate at 6 seconds.
video_view_rate_15_seconds	double	Video view rate at 15 seconds.
video_completion_rate	double	Video completion rate.
video_fully_viewable_impressions	long	Number of fully viewable impressions.
video_viewable_impressions	long	Number of viewable impressions.
video_viewable_watched_6_seconds	long	Number of viewable impressions watched 6 seconds.
video_viewable_watched_15_seconds	long	Number of viewable impressions watched 15 seconds.

Cost per view

Column	Data type	Description
cost_per_3_second_view	decimal(19,2)	Cost per 3-second view.
cost_per_6_second_view	decimal(19,2)	Cost per 6-second view.
cost_per_15_second_view	decimal(19,2)	Cost per 15-second view.
cost_per_completed_view	decimal(19,2)	Cost per completed view.

Column	Data type	Description
cost_per_3_second_view	decimal(19,2)	Cost per 3-second view.
cost_per_6_second_view	decimal(19,2)	Cost per 6-second view.
cost_per_15_second_view	decimal(19,2)	Cost per 15-second view.
cost_per_completed_view	decimal(19,2)	Cost per completed view.

Other

Column	Data type	Description
currency	string	Currency code for monetary columns.
metrics_updated_at	timestamp	When the metrics were last updated. Used as the incremental cursor.

Column	Data type	Description
currency	string	Currency code for monetary columns.
metrics_updated_at	timestamp	When the metrics were last updated. Used as the incremental cursor.

campaign_report

Campaign-level performance metrics.

Primary key: campaign_id (string), date (date, YYYY-MM-DD).

Includes all shared metric columns plus account_id (string).

ad_group_report

Ad group-level performance metrics.

Primary key: ad_group_id (string), date (date, YYYY-MM-DD).

Includes all shared metric columns plus account_id (string) and pacing (double), which is auto-returned for the ad group breakdown.

ad_report

Ad-level performance metrics.

Primary key: ad_id (string), date (date, YYYY-MM-DD).

Includes all shared metric columns plus account_id (string).

campaign_country_report

Campaign-level performance metrics broken down by country.

Primary key: campaign_id (string), date (date, YYYY-MM-DD), country (string).

Includes all shared metric columns plus account_id (string).

Custom reports

A custom report lets you choose the exact breakdown dimensions and metric fields you want. Declare it by setting source_table: custom_report and providing the report definition under connector_options.reddit_ads_options.custom_report_options.

The destination_table name is required for custom reports.

The primary key of a custom report is composed of the chosen breakdown columns. Metric fields are stored as data values.

Custom report breakdowns and fields

Supported breakdowns — you must include at least one time dimension (DATE or HOUR). The destination column name is shown in parentheses.

DATE (date), HOUR (hour), AD_ACCOUNT_ID (account_id), AD_GROUP_ID (ad_group_id), AD_ID (ad_id), CAMPAIGN_ID (campaign_id), COMMUNITY (community), COUNTRY (country), DMA (dma), GALLERY_ITEM_ID (post_id), GENDER (gender), INTEREST (interest), KEYWORD (keyword), OS_TYPE (os_type), PLACEMENT (placement), REGION (region).

Supported fields (destination column name is the lowercased token):

Core delivery: IMPRESSIONS (long), CLICKS (long), SPEND (decimal(19,2)), CPC (decimal(19,2)), ECPM (decimal(19,2)), CTR (double), CONVERSION_ROAS (double).

Video: VIDEO_STARTED, VIDEO_PLAYS_EXPANDED, VIDEO_PLAYS_WITH_SOUND, VIDEO_WATCHED_3_SECONDS, VIDEO_WATCHED_5_SECONDS, VIDEO_WATCHED_10_SECONDS, VIDEO_WATCHED_25_PERCENT, VIDEO_WATCHED_50_PERCENT, VIDEO_WATCHED_75_PERCENT, VIDEO_WATCHED_95_PERCENT, VIDEO_WATCHED_100_PERCENT, VIDEO_FULLY_VIEWABLE_IMPRESSIONS, VIDEO_VIEWABLE_IMPRESSIONS (all long).

App install conversions: APP_INSTALL_ADD_PAYMENT_INFO_COUNT, APP_INSTALL_ADD_TO_CART_COUNT, APP_INSTALL_APP_LAUNCH_COUNT, APP_INSTALL_COMPLETED_TUTORIAL_COUNT, APP_INSTALL_INSTALL_COUNT, APP_INSTALL_MMP_INSTALL_COUNT, APP_INSTALL_MMP_TOTAL_INSTALL_COUNT, APP_INSTALL_SKAN_INSTALL_COUNT, APP_INSTALL_SKAN_TOTAL_INSTALL_COUNT, APP_INSTALL_LEVEL_ACHIEVED_COUNT, APP_INSTALL_PURCHASE_COUNT, APP_INSTALL_SEARCH_COUNT, APP_INSTALL_SIGN_UP_COUNT, APP_INSTALL_SPEND_CREDITS_COUNT, APP_INSTALL_VIEW_CONTENT_COUNT (all long).

Other: PRIORITY (string).