Reddit Ads connector reference

Important

This feature is in Beta. Workspace admins can control access to this feature from the Previews page. See Manage Azure 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

  • Last updated on