Meta Ads ingestion 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 contains reference material for the Meta Ads ingestion connector in Databricks Lakeflow Connect.

Automatic data transformations

Databricks transforms Meta Ads data types to Delta-compatible data types as follows:

Meta Ads Type	Delta Type
string	String
int	Integer
long	Long
float	Float
double	Double
boolean	Boolean
datetime	Timestamp
date	Date
list	Array
map	Map
enum	String

Supported objects

The Meta Ads connector supports ingesting the following objects:

Object	Description
ads	Individual ads in your campaigns
ad_sets	Ad sets that group ads together with shared targeting, budget, and schedule settings
campaigns	Top-level campaign objects that contain ad sets
ad_images	Image assets used in ads
ad_insights	Performance metrics and analytics data for ads, ad sets, campaigns, or accounts
ad_creatives	Creative elements (images, videos, text) used in ads
custom_audiences	Custom audience definitions for targeting
ad_videos	Video assets used in ads
custom_conversions	Custom conversion event definitions

ad_insights configuration options

The ad_insights object supports additional configuration options for analyzing performance data.

Start date

Set the earliest date from which to ingest historical ad_insights data. The Insights API only retains data for approximately 36 months, so start_date must be within the last 36 months. If unset, the connector defaults to 36 months before the current date.

Granularity levels

Specify the level at which to retrieve performance metrics:

• account: Account-level metrics
• campaign: Campaign-level metrics
• adset: Ad set-level metrics
• ad: Ad-level metrics (default)

Breakdown dimensions

Configure breakdown dimensions to segment performance data:

• age: Age ranges
• gender: Gender
• country: Country
• region: Geographic region
• dma: Designated Market Area (US only)
• device_platform: Device platform (mobile, desktop, etc.)
• placement: Ad placement location
• publisher_platform: Publisher platform (Facebook, Audience Network, etc.)
• impression_device: Device type for impressions

Action breakdown dimensions

Configure action breakdown dimensions to analyze conversion actions:

• action_type: Type of conversion action
• action_destination: Destination of the conversion action
• action_carousel_card_id: Carousel card identifier
• action_carousel_card_name: Carousel card name
• action_video_sound: Video sound setting
• action_video_type: Video type

Time increment

Configure the aggregation period for ad_insights data:

• all_days: A single bucket covering the full time range (Insights API default).
• monthly: One bucket per calendar month.
• An integer number of days as a string (for example, "1" for daily buckets, "7" for weekly buckets).

The Insights API doesn't support hourly time increments.

Action report time

Configure the timestamp used to report action statistics:

• impression: Conversions are reported on the date of the impression that drove them.
• conversion: Conversions are reported on the date the conversion occurred.
• mixed: Click-through conversions use impression time, view-through conversions use conversion time.
• lifetime: Lifetime conversions for the entity.

Attribution windows

Configure attribution windows for the actions.

• 1d_click, 7d_click: Click-through attribution windows
• 28d_click: Click-through attribution window. Deprecated by Meta. Might not be returned by newer API versions.
• 1d_view: View-through attribution window
• 7d_view, 28d_view: View-through attribution windows. Deprecated by Meta. Might not be returned by newer API versions.

You can specify multiple values (for example, ["7d_click", "1d_view"]). If action_attribution_windows isn't set, the connector uses your Meta Ads account's default attribution settings. For a list of values, see Meta's Insights API reference.

Lookback window

Configure how far back the connector reingests data (in days) on each sync:

Behavior:

• Time-range re-ingestion: On each sync after the first, the connector pulls data for [last_sync_cursor - <N> days, today] so late-arriving conversions are captured. If custom_insights_lookback_window is unset, the connector reingests the last 7 days by default.
• Attribution fallback: When you set custom_insights_lookback_window explicitly and you have not set action_attribution_windows, the connector also passes <N>d_click,1d_view as the attribution window to the Insights API. To control attribution independently of the lookback, set action_attribution_windows.

API versions

The Meta Ads connector uses the Meta Marketing API (Graph API). Databricks keeps the connector up to date with the latest stable API version.