Meta Ads
API Documentation: Meta Ads Insights API documentation
High-Level Information:
The Meta Ads Insights and Graph API allow you to access detailed data related to your advertising campaigns on the Meta platform (Facebook, Instagram, and other Meta properties)
Source Setup Guide
Step 1
in the Edit Source form to the left.
Step 2
Follow the authentication flow (OAuth) in Facebook to grant Extract the required permissions.
Step 3
Ensure that your email and profile picture are visible, and verify that the source status is Connected.
Step 4 (optional) Add Custom reports
When creating a custom report, you can configure the following options:
- Report Name
- Breakdowns: Define how the results will be broken down. Certain combinations are available when using more than one breakdown. For details, refer to the Combining Breakdowns section.
- Action Breakdowns: Specify how to break down action results. Multiple breakdowns are supported, with the default value being
["action_type"]. - Fields: Choose the metrics to include in your report.
- Time Breakdown
- Action Report Time: Sets the time frame for action statistics in the report.
- Action Attribution Windows: Define the attribution window for actions.
For more information, visit the Meta Ads Insights API documentation.
Connection Setup Guide
Once you conneted Meta Ads to a destination, you will also need to configure:
- Connection Pull Schedule: Determines how frequently data is extracted from the source.
- Backfill (Days): Specifies the duration for which historical data will be retrieved during each connection run.
- Accounts Whitelist: Select specific ad accounts to sync, or all of them.
- Destination specific settings: different settings such as "Dataset Name" or "Target Schema" (depanding on your destination)
- Schema Migration Policy: Controls how Extract will handle schema changes from the sourcee source.
Configuration
Provide the following configuration values when setting up the Meta Ads source:
- Access Token: A Meta (Facebook) Graph API access token with permissions to read Ads data for the ad accounts you want to sync.
- Ad Account IDs: One or more ad account IDs to pull data from (for example,
act_1234567890). If you manage multiple accounts, include each account you want to sync. - Start Date: The earliest date to begin syncing data from. Data before this date will not be requested.
Notes:
- The connector reads data via the Meta Graph API and will paginate through results where applicable.
- For Insights-style reporting, the connector may request data in date batches. If you request a very large date range or high-cardinality breakdowns, Meta may return errors indicating the request is too large; in that case, reduce the requested scope (for example, narrow the date range or selected breakdowns) and retry.
Connector Information
Schema ERD
Explore the interactive entity relationship diagram for Meta Ads.
Data Streams
account_recommendations
action_canvas_component
action_carousel_card
action_conversion_device
action_product_id
action_reactions
action_video_sound
action_video_view_type
ad_account
ad_action_canvas_component
ad_action_carousel_card
ad_action_conversion_device
ad_action_reactions
ad_action_video_sound
ad_action_video_view_type
ad_activity
ad_campaign_frequency_control
ad_campaign_issues_info
ad_conversion_specs
ad_creative_labels
ad_creative
ad_delivery_platform
ad_image
ad_insights
ad_labels
ad_recommendation
ad_study_cells
ad_study_objectives
ad_study
ad_tracking_specs
ad_video
ad
adgroup_issues_info
adset_action_canvas_component
adset_action_carousel_card
adset_action_conversion_device
adset_action_reactions
adset_action_video_sound
adset_action_video_view_type
adset_labels
adset_targeting_optimization_types
adset
basic_ad_set
basic_ad
basic_all_levels
basic_campaign
business_invoice
campaign_action_canvas_component
campaign_action_carousel_card
campaign_action_conversion_device
campaign_action_reactions
campaign_action_video_sound
campaign_action_video_view_type
campaign_ad_study
campaign_labels
campaign
custom_audience
custom_conversion
delivery_device
delivery_platform_and_device
delivery_platform
delivery_purchase_roas
demographics_age_and_gender
demographics_age
demographics_country
demographics_dma_region
demographics_gender
demographics_region
label
reservation
video_thumbnail
Metadata
ad_account
ad
ad_campaign_frequency_control
ad_campaign_issues_info
ad_conversion_specs
ad_creative
ad_creative_labels
ad_image
ad_labels
ad_recommendation
ad_study
ad_tracking_specs
ad_video
adgroup_issues_info
adset
adset_labels
adset_targeting_optimization_types
campaign
campaign_labels
custom_audience
custom_conversion
label
reservation
video_thumbnail
Pre Build Reports
action_canvas_component
action_carousel_card
action_product_id
action_reactions
action_video_sound
action_video_view_type
ad_insights
basic_ad
basic_ad_set
basic_all_levels
basic_campaign
delivery_device
delivery_platform
delivery_platform_and_device
delivery_purchase_roas
demographics_age
demographics_age_and_gender
demographics_country
demographics_dma_region
demographics_dma_region
demographics_region
ad_activity
Notes
- Events with an
event_timeolder than 7 days are skipped and not sent to Meta Conversions API. - You must provide at least one
user_data.*field.user_data.*fields withnullvalues are ignored; if all provideduser_data.*fields arenull, the event is rejected. user_data.fbclidis automatically converted into Meta’sfbcformat before sending.- Any
nullfields are stripped from the final payload before it is sent. - For
Purchaseevents, additional validation is applied to ensure required purchase fields are present before the event is sent.
Troubleshooting
Events are skipped because they are older than 7 days
If an event’s event_time is more than 7 days in the past, the connector skips it and does not send it to Meta.
Fix: Ensure event_time is an RFC3339 timestamp and is within the last 7 days.
Invalid event, you must provide at least one user_data.* fields
This error occurs when the event does not include any user_data.* fields.
Fix: Include at least one user_data.* field (for example, user_data.em, user_data.ph, user_data.client_ip_address, etc.).
Invalid event, you must provide at least one non-null user_data.* field
This error occurs when user_data.* fields are present, but all of them are null. The connector ignores null user_data.* values, and then fails validation if no non-null user data remains.
Fix: Provide at least one user_data.* field with a non-null value.
Purchase events fail validation
For event_name: "Purchase", Meta requires specific purchase fields. The connector validates purchase events and will fail the run if required purchase fields are missing.
Fix: Ensure your Purchase events include the required purchase fields in custom_data (for example, custom_data.currency and custom_data.value) and that they are not null.