Meta Ads ingestion 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 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
Prebuilt reports (21 tables)	Ready-made ad_insights variants with a fixed configuration per report.
custom_report	User-defined insights report. Configure the report with custom_report_options and name the output with destination_table.

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
• 1d_view: View-through attribution window
• 7d_view, 28d_view: View-through attribution windows. Deprecated by Meta and no longer supported by the connector.

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. The lookback window applies to ad_insights, custom_report, and prebuilt reports. If unset, it defaults to 7 days.

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

Prebuilt reports

Prebuilt reports are ready-to-use ad_insights variants. Each prebuilt report issues a Meta /insights call with a fixed level, breakdown, and action-breakdown combination — no configuration is required. Unlike ad_insights, prebuilt reports are not configurable.

To ingest a prebuilt report, set source_table to the report name. connector_options are optional. A prebuilt report runs with none (using the defaults), but you can set start_date in meta_ads_options to control the date range.

Available prebuilt reports

Each prebuilt report maps to a fixed Meta /insights request.

Report (source_table)	Category	Level	Breakdowns	Action breakdowns	Metric set
basic_ad_report	Basic	ad	—	action_type	Core metrics
basic_ad_set_report	Basic	adset	—	action_type	Core metrics
basic_campaign_report	Basic	campaign	—	action_type	Core metrics
basic_all_levels_report	Basic	ad	—	action_type	Core metrics (with ad, ad set, campaign names)
delivery_device_report	Delivery	ad	device_platform	action_type	Core metrics
delivery_platform_report	Delivery	ad	publisher_platform	action_type	Core metrics
delivery_platform_and_device_report	Delivery	ad	publisher_platform, device_platform	action_type	Core metrics
delivery_purchase_roas_report	Delivery	ad	—	action_type	Conversion / ROAS
demographics_age_report	Demographics	ad	age	action_type	Core metrics
demographics_gender_report	Demographics	ad	gender	action_type	Core metrics
demographics_age_and_gender_report	Demographics	ad	age, gender	action_type	Core metrics
demographics_country_report	Demographics	ad	country	action_type	Core metrics
demographics_region_report	Demographics	ad	region	action_type	Core metrics
demographics_dma_region_report	Demographics	ad	comscore_market	action_type	Core metrics
action_canvas_component_report	Action	ad	—	action_type	Conversion / ROAS
action_carousel_card_report	Action	ad	—	action_carousel_card_id, action_carousel_card_name	Conversion / ROAS
action_conversion_device_report	Action	ad	device_platform	action_type	Conversion / ROAS
action_product_id_report	Action	ad	product_id	action_type	Conversion / ROAS
action_reactions_report	Action	ad	—	action_reaction	actions, action_values
action_video_sound_report	Action	ad	—	action_video_sound	Video engagement
action_video_view_type_report	Action	ad	—	action_video_type	Video engagement

Each prebuilt report uses one of three metric sets, which determine the columns included in the output:

Metric set	Columns
Core metrics	reach, impressions, frequency, spend, cpm, cpc, cost_per_inline_link_click, ctr, inline_link_click_ctr, inline_link_clicks, actions, cost_per_action_type (array)
Conversion / ROAS	inline_link_clicks, outbound_clicks, website_purchase_roas, mobile_app_purchase_roas (array)
Video engagement	video_thruplay_watched_actions, video_30_sec_watched_actions, video_p25_watched_actions, video_p50_watched_actions, video_p75_watched_actions, video_p100_watched_actions, video_avg_time_watched_actions (array)

Output columns

Every prebuilt report row includes date_start, date_stop, account_id, the report's entity and hierarchy columns (for example ad_id, adset_id, campaign_id, and names where applicable), any breakdown column (for example age, device_platform), the derived breakdown_hash, and the primary key insight_id. The metric columns depend on the report's metric set. Action and ROAS columns are typed as array<string>.

Prebuilt report behavior

• Each row is uniquely identified by insight_id. The connector syncs data incrementally, using date_stop as the cursor.
• The report configuration — level, breakdowns, action_breakdowns, time_increment (daily), attribution windows (7d_click, 1d_view), and action_report_time (mixed) — is fixed per report and cannot be overridden using meta_ads_options.
• You can optionally set start_date (default: 36 months before today) and custom_insights_lookback_window (default: 7 days) in meta_ads_options.

custom_report configuration options

custom_report lets you define your own ad_insights-style report with a custom level, breakdown, and action-breakdown combination and ingest it into a table you name. Use it when no prebuilt report matches your needs and you want full control over the /insights configuration.

To ingest a custom report, set source_table to custom_report, choose a destination_table name, and configure the report under connector_options.meta_ads_options.custom_report_options. You can add multiple custom_report objects to one pipeline, each with a distinct destination_table.

Object structure:

{
  "table": {
    "source_schema": "<meta-ads-account-id>",
    "source_table": "custom_report",
    "destination_catalog": "<catalog>",
    "destination_schema": "<schema>",
    "destination_table": "<your-report-name>",
    "connector_options": {
      "meta_ads_options": {
        "start_date": "<YYYY-MM-DD>",
        "custom_insights_lookback_window": 7,
        "custom_report_options": {
          "level": "ad",
          "breakdowns": ["country"],
          "action_breakdowns": ["action_type"],
          "time_increment": "1",
          "action_report_time": "mixed",
          "action_attribution_windows": ["7d_click", "1d_view"]
        }
      }
    }
  }
}

custom_report_options

Each option mirrors the corresponding ad_insights option:

Option	Description
level	Granularity: account, campaign, adset, or ad.
breakdowns	Dimensions that segment all metrics (for example, ["country", "age"]).
action_breakdowns	Dimensions that segment action/conversion metrics (for example, ["action_type"]).
time_increment	Aggregation period: all_days, monthly, or an integer number of days as a string (for example, "1" for daily).
action_report_time	When actions are counted: impression, conversion, mixed, or lifetime.
action_attribution_windows	Attribution windows for actions (for example, ["7d_click", "1d_view"]).

Shared meta_ads_options

Option	Description	Default when unset
start_date	Earliest date to ingest, YYYY-MM-DD.	36 months before the current date
custom_insights_lookback_window	Number of days to re-ingest on each subsequent sync (captures late conversions).	7 days

You must set destination_table on the table object so multiple custom reports can coexist in one pipeline.

Each row is uniquely identified by insight_id. The connector syncs data incrementally, using date_stop as the cursor.

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.