Facebook Ads is Meta’s advertising platform that allows businesses to create and manage digital advertising campaigns across Facebook, Instagram, and other Meta-owned platforms. It provides tools for targeting audiences, tracking performance, and optimizing ad spend for maximum return on investment.

​
Configuring Facebook Ads as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Facebook Ads option from the list of connectors. Click Next and you’ll be prompted to add your access.

​
1. Add account access

You’ll need to authorize Nekt to access your Facebook Ads data. Click on the Facebook Authorization button and log in with your Facebook account. Grant the necessary permissions for the ad accounts you want to extract data from. After authentication, select the specific Ad Account for this source and define a start date for data retrieval. Facebook’s API allows fetching reports up to 36 months in the past. You can also enable advanced reports for gender, country, age and device platform segmentations, but be aware that this will increase extraction times. Additionally, you can configure attribution windows and lookback periods in the Advanced Settings. Once you’re done, click Next.

​
2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.
Tip: The stream can be found more easily by typing its name.
Select the streams and click Next.

​
3. Configure data streams

Customize how you want your data to appear in your catalog. Select a name for each table (which will contain the fetched data) and the type of sync.
  • Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix and make this process faster!
  • Sync Type: you can choose between INCREMENTAL and FULL_TABLE.
    • Incremental: every time the extraction happens, we’ll get only the new data - which is good if, for example, you want to keep every record ever fetched.
    • Full table: every time the extraction happens, we’ll get the current state of the data - which is good if, for example, you don’t want to have deleted data in your catalog.
Once you are done configuring, click Next.

​
4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times). Optionally, you can determine when to execute a full sync. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while. Once you are ready, click Next to finalize the setup.

​
5. Check your new source

You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your Catalog, you need at least one successful source run.

​
Streams and Fields

Below you’ll find all available data streams from Facebook Ads and their corresponding fields:
Stream for managing ad campaigns and their settings.Key Fields:
  • id - Unique identifier for the campaign
  • name - Name of the campaign
  • objective - The objective of the campaign (e.g., brand awareness, conversions)
  • status - The status of the campaign (e.g., active, paused)
  • daily_budget - The daily budget for the campaign
  • lifetime_budget - The lifetime budget for the campaign
  • start_time - The start time of the campaign
  • stop_time - The stop time of the campaign
  • created_time - When the campaign was created
  • updated_time - When the campaign was last updated
Budget & Spending:
  • budget_remaining - The remaining budget for the campaign
  • spend_cap - Maximum amount that can be spent on the campaign
  • budget_rebalance_flag - Whether budget rebalancing is enabled
  • last_budget_toggling_time - Last time the budget was modified
  • bid_strategy - The bidding strategy used for the campaign
Campaign Settings:
  • account_id - The ID of the ad account
  • buying_type - The buying type of the campaign (e.g., auction, fixed price)
  • configured_status - The configured status of the campaign
  • effective_status - The effective status of the campaign
  • pacing_type - Array of pacing types for the campaign
  • primary_attribution - Primary attribution setting
  • source_campaign_id - ID of the source campaign if this is a copy
  • boosted_object_id - ID of the boosted object
  • topline_id - ID of the topline
Special Ad Settings:
  • special_ad_category - Category for special ads (e.g., housing, employment)
  • special_ad_categories - Array of special ad categories
  • special_ad_category_country - Array of countries for special ad targeting
Advanced Features:
  • can_create_brand_lift_study - Whether brand lift studies are available
  • can_use_spend_cap - Whether spend caps can be used
  • has_secondary_skadnetwork_reporting - Whether secondary SKAdNetwork reporting is enabled
  • is_skadnetwork_attribution - Whether SKAdNetwork attribution is enabled
  • smart_promotion_type - Type of smart promotion
  • ad_strategy_group_id - ID of the ad strategy group
  • ad_strategy_id - ID of the ad strategy
Labels:
  • adlabels - Array of labels attached to the campaign, each containing:
    • id - Label ID
    • name - Label name
    • created_time - When the label was created
    • updated_time - When the label was last updated
Stream for managing ad sets, which control targeting, budget, and scheduling for a group of ads.Key Fields:
  • id - Unique identifier for the ad set
  • name - Name of the ad set
  • campaign_id - The ID of the campaign this ad set belongs to
  • status - The status of the ad set
  • daily_budget - The daily budget for the ad set
  • lifetime_budget - The lifetime budget for the ad set
  • start_time - The start time of the ad set
  • end_time - The end time of the ad set
  • created_time - When the ad set was created
  • updated_time - When the ad set was last updated
Budget & Bidding:
  • account_id - The ID of the ad account
  • bid_strategy - The bid strategy for the ad set
  • bid_amount - The bid amount
  • bid_info - Detailed bid information including:
    • CLICKS - Bid for clicks
    • ACTIONS - Bid for actions
    • REACH - Bid for reach
    • IMPRESSIONS - Bid for impressions
    • SOCIAL - Bid for social impressions
  • budget_remaining - Remaining budget
  • daily_min_spend_target - Minimum daily spend target
  • lifetime_min_spend_target - Minimum lifetime spend target
  • lifetime_spend_cap - Maximum lifetime spend
Optimization & Delivery:
  • billing_event - The billing event type
  • optimization_goal - The optimization goal
  • optimization_sub_event - Sub-event for optimization
  • pacing_type - Array of pacing types
  • destination_type - Type of destination
  • is_dynamic_creative - Whether dynamic creative is enabled
  • source_adset_id - ID of source ad set if this is a copy
Targeting:
  • targeting - Complex targeting object containing:
    • age_max - Maximum age
    • age_min - Minimum age
    • genders - Array of targeted genders
    • geo_locations - Geographic targeting settings
    • interests - Targeted interests
    • behaviors - Targeted behaviors
    • custom_audiences - Custom audience targeting
    • excluded_custom_audiences - Excluded custom audiences
    • device_platforms - Targeted devices
    • publisher_platforms - Targeted publishing platforms
    • facebook_positions - Ad positions on Facebook
    • instagram_positions - Ad positions on Instagram
    • excluded_publisher_categories - Excluded publisher categories
    • And many more targeting options…
Performance & Learning:
  • learning_stage_info - Information about the learning stage:
    • status - Current learning status
    • conversions - Number of conversions
    • last_sig_edit_ts - Last significant edit timestamp
    • attribution_windows - Array of attribution windows
Labels & Metadata:
  • adlabels - Array of labels attached to the ad set
  • attribution_spec - Attribution specifications
  • review_feedback - Review feedback
  • rf_prediction_id - RF prediction ID
Stream for managing individual ads within an ad set.Key Fields:
  • id - Unique identifier for the ad
  • name - Name of the ad
  • adset_id - The ID of the ad set this ad belongs to
  • campaign_id - The ID of the campaign this ad belongs to
  • status - The status of the ad
  • created_time - When the ad was created
  • updated_time - When the ad was last updated
Creative & Content:
  • creative - The creative object containing:
    • id - Creative ID
    • creative_id - Alternative creative ID reference
  • tracking_specs - Array of tracking specifications:
    • application - Application tracking
    • post - Post tracking
    • conversion_id - Conversion tracking
    • action_type - Types of actions to track
    • fb_pixel - Facebook pixel tracking
    • And many more tracking options…
  • conversion_specs - Array of conversion specifications
  • conversion_domain - Domain for conversions
Bidding & Budget:
  • bid_type - Type of bidding
  • bid_amount - Bid amount
  • bid_info - Detailed bidding information
Status & Configuration:
  • account_id - The ID of the ad account
  • effective_status - The effective status of the ad
  • configured_status - The configured status
  • last_updated_by_app_id - ID of the app that last updated the ad
  • source_ad_id - ID of the source ad if this is a copy
Additional Fields:
  • recommendations - Array of recommendations containing:
    • blame_field - Field causing the issue
    • code - Recommendation code
    • confidence - Confidence level
    • importance - Importance level
    • message - Recommendation message
    • title - Recommendation title
  • adlabels - Array of labels attached to the ad
Stream for managing ad creatives, which are the visual components of an ad. This stream extracts creative data from the ads stream context, providing incremental sync based on ad updates.
Field Modes: You can configure the extraction level using:
  • Basic (default) - Essential creative fields for faster processing
  • Advanced - Includes all media and configuration details
Basic Fields (always included):
  • id - Unique identifier for the creative
  • account_id - The ID of the ad account
  • name - Name of the creative
  • title - The title of the creative
  • body - The body text of the creative
  • status - Status of the creative
  • actor_id - The ID of the actor (e.g., page) associated with the creative
  • authorization_category - Category for authorization
  • call_to_action_type - Type of call to action button
  • enable_direct_install - Whether direct install is enabled
  • link_url - The URL the ad links to
  • object_id - ID of the object
  • object_type - Type of object
  • object_url - URL of the object
  • use_page_actor_override - Whether to override the page actor
Advanced Fields (included only in advanced mode):Media & Assets:
  • image_hash - Hash of the image used
  • image_url - The URL of the image used in the creative
  • video_id - The ID of the video used in the creative
  • thumbnail_id - ID of the thumbnail
  • thumbnail_url - URL of the thumbnail
  • playable_asset_id - ID of the playable asset
Links & URLs:
  • link_destination_display_url - Display URL for the link
  • link_og_id - Open Graph ID for the link
  • object_store_url - Store URL for the object
  • template_url - Template URL
  • url_tags - URL parameters for tracking
Instagram Integration:
  • instagram_user_id - ID of the Instagram user
  • instagram_permalink_url - Permalink URL for Instagram
  • instagram_story_id - ID of the Instagram story
  • effective_instagram_story_id - Effective ID of the Instagram story
  • effective_instagram_media_id - Effective ID of the Instagram media
  • source_instagram_media_id - Source Instagram media ID
Advanced Configuration:
  • applink_treatment - Treatment for app links
  • branded_content_sponsor_page_id - ID of the sponsor page for branded content
  • bundle_folder_id - ID of the bundle folder
  • categorization_criteria - Criteria for categorization
  • category_media_source - Source of category media
  • degrees_of_freedom_spec - Degrees of freedom specification
  • destination_set_id - ID of the destination set
  • dynamic_ad_voice - Voice setting for dynamic ads
  • effective_authorization_category - Effective authorization category
  • effective_object_story_id - Effective ID of the object story
  • object_story_id - ID of the object story
  • place_page_set_id - ID of the place page set
Ad Context Fields (always included):
  • ad_id - ID of the parent ad
  • ad_updated_time - Last update time of the parent ad (used for incremental sync)
Stream for retrieving performance data for ads, ad sets, and campaigns.Identifiers & Time:
  • ad_id - The ID of the ad
  • adset_id - The ID of the ad set
  • campaign_id - The ID of the campaign
  • account_id - The ID of the ad account
  • date_start - The start date of the data
  • date_stop - The stop date of the data
Basic Metrics:
  • impressions - Number of times the ad was shown
  • reach - Number of unique people who saw the ad
  • frequency - Average number of times each person saw the ad
  • clicks - Number of clicks on the ad
  • unique_clicks - Number of unique clicks
  • ctr - Click-through rate
Cost Metrics:
  • spend - Amount spent on the ad
  • cpc - Cost per click
  • cpm - Cost per thousand impressions
  • cpp - Cost per 1,000 people reached
  • cost_per_unique_click - Cost per unique click
  • cost_per_action_type - Cost per action type
Conversion Metrics:
  • conversions - Number of conversions
  • cost_per_conversion - Cost per conversion
  • conversion_rate_ranking - Ranking of conversion rate
  • conversion_values - Values of conversions
  • cost_per_conversion - Cost per conversion
  • website_purchase_roas - Return on ad spend for website purchases
  • purchase_roas - Overall return on ad spend
Engagement Metrics:
  • social_spend - Spend on social impressions
  • social_impressions - Number of social impressions
  • actions - Detailed breakdown of different types of actions
  • video_p25_watched_actions - Video views at 25%
  • video_p50_watched_actions - Video views at 50%
  • video_p75_watched_actions - Video views at 75%
  • video_p95_watched_actions - Video views at 95%
  • video_p100_watched_actions - Complete video views
  • video_avg_time_watched_actions - Average video watch time
  • video_play_actions - Number of video plays
Quality & Relevance:
  • quality_ranking - Quality ranking of the ad
  • engagement_rate_ranking - Ranking of engagement rate
  • quality_score_organic - Organic quality score
  • quality_score_ectr - Expected click-through rate score
  • quality_score_ecvr - Expected conversion rate score
Demographic Breakdowns: When advanced reports are enabled:
  • age - Age group
  • gender - Gender
  • country - Country
  • region - Region
  • device_platform - Device platform

​
Data Model

The following diagram illustrates the relationships between the core data streams in Facebook Ads. The arrows indicate the join keys that link the different entities, providing a clear overview of the data structure.

​
Use Cases for Data Analysis

This guide outlines valuable business intelligence use cases when consolidating Facebook Ads data, along with ready-to-use SQL queries that you can run on Explorer.

​
Campaign Performance Analysis

​
1. Campaign Performance Metrics

Track the overall performance of your campaigns, including detailed conversion metrics. Business Value:
  • Identify which campaigns deliver the best value for money
  • Understand the relationship between quality scores and performance
  • Optimize budget allocation based on performance metrics

SQL code

WITH
	campaign_metrics AS (
		SELECT
			c."name" AS "campaign_name",
			c."objective",
			c."status",
			c."buying_type",
			SUM(TRY_CAST (ai."impressions" AS BIGINT)) AS "total_impressions",
			SUM(TRY_CAST (ai."reach" AS BIGINT)) AS "total_reach",
			SUM(TRY_CAST (ai."clicks" AS BIGINT)) AS "total_clicks",
			SUM(TRY_CAST (ai."spend" AS DOUBLE)) AS "total_spend",
			AVG(TRY_CAST (ai."frequency" AS DOUBLE)) AS "avg_frequency",
			SUM(TRY_CAST (ai."clicks" AS DOUBLE)) * 100.0 / NULLIF(SUM(TRY_CAST (ai."impressions" AS DOUBLE)), 0) AS "ctr",
			SUM(TRY_CAST (ai."spend" AS DOUBLE)) / NULLIF(SUM(TRY_CAST (ai."clicks" AS DOUBLE)), 0) AS "cpc",
			SUM(TRY_CAST (ai."spend" AS DOUBLE)) * 1000.0 / NULLIF(SUM(TRY_CAST (ai."impressions" AS DOUBLE)), 0) AS "cpm"
		FROM
			"nekt_raw"."facebook_ads_campaigns" c
			LEFT JOIN "nekt_raw"."facebook_ads_adsinsights" ai ON c."id" = ai."campaign_id"
		WHERE
			c."effective_status" = 'ACTIVE'
			AND date_parse (ai."date_start", '%Y-%m-%d') >= CURRENT_DATE - INTERVAL '30' DAY
		GROUP BY
			c."name",
			c."objective",
			c."status",
			c."buying_type"
	)
SELECT
	"campaign_name",
	"objective",
	"total_spend",
	"total_impressions",
	"total_reach",
	"total_clicks",
	"avg_frequency",
	"ctr",
	"cpc",
	"cpm"
FROM
	campaign_metrics

​
2. Creative Performance and Content Analysis

Analyze how different creative elements and content types perform across your campaigns, helping optimize your creative strategy. Business Value:
  • Identify which creative formats drive the best engagement
  • Understand the impact of different call-to-action types
  • Optimize creative elements based on performance data
  • Guide future creative development with data-driven insights

SQL code

WITH
	creative_metrics AS (
		SELECT
			cr.name AS creative_name,
			cr.title,
			cr.body,
			cr.call_to_action_type,
			cr.object_type,
			COALESCE(cr.video_id, 'image') AS content_type,
			SUM(TRY_CAST (ai.impressions AS BIGINT)) AS total_impressions,
			SUM(TRY_CAST (ai.reach AS BIGINT)) AS total_reach,
			SUM(TRY_CAST (ai.clicks AS BIGINT)) AS total_clicks,
			SUM(TRY_CAST (ai.spend AS DECIMAL(20, 2))) AS total_spend,
			AVG(TRY_CAST (ai.frequency AS DECIMAL(10, 2))) AS avg_frequency,
			CAST(
				SUM(TRY_CAST (ai.clicks AS DOUBLE)) * 100.0 / NULLIF(SUM(TRY_CAST (ai.impressions AS DOUBLE)), 0) AS DECIMAL(10, 2)
			) AS ctr,
			SUM(
				CASE
					WHEN action.action_type = 'video_view' THEN TRY_CAST (action.value AS DECIMAL(20, 2))
					ELSE 0
				END
			) AS total_video_views,
			AVG(
				CASE
					WHEN action.action_type = 'video_view' THEN TRY_CAST (action.value AS DECIMAL(20, 2))
					ELSE NULL
				END
			) AS avg_video_completion_rate
		FROM
			nekt_raw.facebook_ads_creatives cr
			LEFT JOIN nekt_raw.facebook_ads_ads a ON cr.id = a.creative.id
			LEFT JOIN nekt_raw.facebook_ads_adsinsights ai ON a.id = ai.ad_id
			CROSS JOIN UNNEST (ai.actions) AS t ("action")
		WHERE
			date_parse (ai.date_start, '%Y-%m-%d') >= CURRENT_DATE - INTERVAL '30' DAY
		GROUP BY
			cr.name,
			cr.title,
			cr.body,
			cr.call_to_action_type,
			cr.object_type,
			cr.video_id
	)
SELECT
	creative_name,
	content_type,
	call_to_action_type,
	object_type,
	total_impressions,
	total_reach,
	total_clicks,
	total_spend,
	ctr,
	CAST(
		total_spend / NULLIF(total_clicks, 0) AS DECIMAL(10, 2)
	) AS cost_per_click,
	CASE
		WHEN content_type != 'image' THEN total_video_views
		ELSE NULL
	END AS video_views,
	CASE
		WHEN content_type != 'image' THEN avg_video_completion_rate
		ELSE NULL
	END AS video_completion_rate
FROM
	creative_metrics
ORDER BY
	total_clicks DESC

​
3. Time-Based Performance Analysis

Track campaign performance trends over time to identify patterns and optimize campaign timing. Business Value:
  • Understand daily and weekly performance patterns
  • Identify best-performing days and times
  • Optimize campaign scheduling and budget pacing
  • Track performance trends for better planning

SQL code

WITH
	daily_metrics AS (
		SELECT
			date_parse (ai.date_start, '%Y-%m-%d') AS date,
			date_format (date_parse (ai.date_start, '%Y-%m-%d'), '%W') AS day_of_week,
			SUM(TRY_CAST (ai.impressions AS BIGINT)) AS total_impressions,
			SUM(TRY_CAST (ai.reach AS BIGINT)) AS total_reach,
			SUM(TRY_CAST (ai.clicks AS BIGINT)) AS total_clicks,
			SUM(TRY_CAST (ai.spend AS DECIMAL(20, 2))) AS total_spend,
			SUM(TRY_CAST (ai.clicks AS DOUBLE)) * 100.0 / NULLIF(SUM(TRY_CAST (ai.impressions AS DOUBLE)), 0) AS ctr,
			SUM(TRY_CAST (ai.spend AS DOUBLE)) / NULLIF(SUM(TRY_CAST (ai.clicks AS DOUBLE)), 0) AS cpc,
			COUNT(DISTINCT ai.campaign_id) AS active_campaigns,
			SUM(
				CASE
					WHEN action.action_type = 'purchase' THEN TRY_CAST (action.value AS DECIMAL(20, 2))
					ELSE 0
				END
			) AS total_conversions
		FROM
			nekt_raw.facebook_ads_adsinsights ai
			CROSS JOIN UNNEST (ai.actions) AS t (action)
		WHERE
			date_parse (ai.date_start, '%Y-%m-%d') >= CURRENT_DATE - INTERVAL '30' DAY
		GROUP BY
			ai.date_start
	),
	weekly_summary AS (
		SELECT
			day_of_week,
			AVG(total_impressions) AS avg_daily_impressions,
			AVG(total_reach) AS avg_daily_reach,
			AVG(total_clicks) AS avg_daily_clicks,
			AVG(total_spend) AS avg_daily_spend,
			AVG(ctr) AS avg_ctr,
			AVG(cpc) AS avg_cpc,
			AVG(total_conversions) AS avg_daily_conversions,
			AVG(active_campaigns) AS avg_active_campaigns
		FROM
			daily_metrics
		GROUP BY
			day_of_week
	),
	daily_vs_average AS (
		SELECT
			dm.*,
			ws.avg_daily_spend AS typical_daily_spend,
			ws.avg_daily_clicks AS typical_daily_clicks,
			ws.avg_daily_conversions AS typical_daily_conversions,
			ROUND(
				(total_spend - ws.avg_daily_spend) * 100.0 / NULLIF(ws.avg_daily_spend, 0),
				2
			) AS spend_vs_typical,
			ROUND(
				(total_clicks - ws.avg_daily_clicks) * 100.0 / NULLIF(ws.avg_daily_clicks, 0),
				2
			) AS clicks_vs_typical,
			ROUND(
				(total_conversions - ws.avg_daily_conversions) * 100.0 / NULLIF(ws.avg_daily_conversions, 0),
				2
			) AS conversions_vs_typical
		FROM
			daily_metrics dm
			JOIN weekly_summary ws ON dm.day_of_week = ws.day_of_week
	)
SELECT
	date,
	day_of_week,
	total_impressions,
	total_reach,
	total_clicks,
	CAST(total_spend AS DECIMAL(20, 2)) AS total_spend,
	CAST(ctr AS DECIMAL(10, 2)) AS ctr,
	CAST(cpc AS DECIMAL(10, 2)) AS cpc,
	total_conversions,
	active_campaigns,
	CAST(typical_daily_spend AS DECIMAL(20, 2)) AS typical_daily_spend,
	CAST(spend_vs_typical AS DECIMAL(10, 2)) AS spend_vs_typical_pct,
	CAST(clicks_vs_typical AS DECIMAL(10, 2)) AS clicks_vs_typical_pct,
	CAST(conversions_vs_typical AS DECIMAL(10, 2)) AS conversions_vs_typical_pct
FROM
	daily_vs_average
ORDER BY
	date DESC
This analysis provides valuable insights into:
  • Daily performance trends
  • Day-of-week patterns
  • Performance against typical metrics
  • Campaign activity levels
  • Spend and conversion efficiency
You can use these insights to:
  • Adjust campaign scheduling
  • Optimize budget allocation across days
  • Identify and investigate performance anomalies
  • Plan campaign launches around high-performing periods
  • Improve budget pacing strategies