Facebook Ads (Meta Ads)

Facebook Ads (Meta Ads) is Meta's advertising platform for creating, managing, and analyzing ad campaigns across Facebook, Instagram, Messenger, and the Audience Network. By connecting it to Coupler.io

Why connect Facebook Ads to Coupler.io?

• Automate reporting — Schedule regular data refreshes so your dashboards and spreadsheets always have the latest campaign performance.

• Combine with other sources — Merge Facebook Ads data with Google Ads, Google Analytics, CRM, or e-commerce data for a full-funnel view of your marketing.

• Save hours of manual work — No more copy-pasting from Ads Manager. Coupler.io pulls the data you need on autopilot.

• Flexible destinations — Export to AI tools, Google Sheets, Excel, BigQuery, Looker Studio, or other supported destinations.

Prerequisites

Before connecting, make sure you have:

• A Facebook account with access to at least one Ad Account in Meta Business Suite

• Admin or Advertiser permissions on the Ad Account you want to pull data from

Quick start

Start with a Reports and Insights report for the last 60 days, using the default metrics (spend, impressions, clicks, CPC, CPM, CTR). Proceed to the Data sets or AI agent to get a quick snapshot of your campaign performance and verify everything is connected correctly.

How to connect

Facebook Ads uses OAuth authentication — you sign in with your Facebook account directly.

1

In Coupler.io, create a new data flow and select Facebook Ads as the source. Click Connect and sign in with your Facebook account.

2

Grant Coupler.io the requested permissions to access your ad data.

3

Select the Ad Account(s) you want to pull data from.

4

Choose a report type (see the most popular ones below).

5

For Reports and Insights, configure:

• Date range — Set the start and end dates using the date picker.

• Metrics and dimensions — Select the columns you want (e.g., spend, impressions, clicks, CTR).

• Attribution settings — Use your ad account defaults or specify manually.

6

Choose your destination and run the import.

Reports overview

Name	Description
Reports and Insights	Performance metrics like spend, impressions, clicks, and conversions.
List of Ads	All your ads with statuses, bid amounts, and settings.
List of Campaigns	Campaign-level data including status, objective, and budget.
List of Ad Sets	Ad set details with optimization goals and budgets.
List of Sponsored Leads	Leads collected through lead generation forms.
List of Ad Creatives	Creative assets available in your account.
List of Ads with Ad Creatives	Ads combined with the creative details used in each.
List of Activities	Audit log of account changes and billing/funding activity.
List of Business invoices	Monthly invoices for your Facebook Business, with billed amounts per ad account and campaign.

Facebook Ads data overview

Facebook Ads in Coupler.io gives you access to nine report types (called entities), each designed for a different use case. Below you'll find what data is available, which metrics you can track, and how to break down your reports.

Report types

Report type	What it contains	When to use it
Reports and Insights	Performance metrics like spend, impressions, clicks, conversions, and more	Analyzing campaign performance, building dashboards, tracking ROI
List of Sponsored Leads	Lead form submissions with contact details, submission time, and source campaign/ad	Tracking lead generation, syncing leads to CRM or sales workflows
List of Campaigns	Campaign statuses, objectives, budgets, and scheduling details	Auditing campaign setup, monitoring active/paused campaigns
List of Ad Sets	Ad set statuses, optimization goals, budgets, and targeting details	Reviewing ad set efficiency and configuration
List of Ads	Individual ad statuses, bid amounts, and issue flags	Monitoring ad health and identifying problem ads
List of Ad Creatives	Creative assets (images, videos, carousels) with text, links, and media details	Reviewing all available creative assets in your account
List of Ads with Ad Creatives	Ads combined with their linked creative details	Analyzing which creatives drive the best results
List of Activities	Audit log of who changed what and when across campaigns, ad sets, ads, and the account itself — including funding activity like charges to your payment method	Auditing account changes and reviewing billing/funding activity
List of Business invoices	Monthly invoices for bill-to legal entities on your Facebook Business, with billed amounts broken down per ad account and per campaign	Reconciling ad spend against invoices, finance reporting

---

Reports and Insights

This is the most data-rich report type. It gives you access to all performance metrics, conversion tracking, and breakdowns. The sections below cover everything available in Coupler.io's metric and dimension picker for this entity.

Dimensions (entity-related columns)

Dimensions identify what you're reporting on. Select them to control which columns appear in your report.

Account

Name	Description
Account Id	The unique identifier for the ad account.
Account currency	The currency used for billing in the ad account.
Account name	The name of the ad account.

Campaign

Name	Description
Campaign Id	The unique identifier for the campaign.
Campaign name	The name of the campaign.

Ad group (Ad set)

Name	Description
Ad group Id	The unique identifier for the ad set.
Ad group name	The name of the ad set.

Ad

Name	Description
Ad Id	The unique identifier for the ad.
Ad name	The name of the ad.

Other dimensions

Name	Description
Created date	The date the campaign, ad set, or ad was created.
Updated date	The date the campaign, ad set, or ad was last updated.
Objective	The advertising objective selected for the campaign (e.g., Conversions, Traffic).
Optimization goal	The event the ad delivery system is optimizing for (e.g., Landing Page Views).
Place page name	The name of the Facebook Page associated with the ad.
Date	The date for the reported data, in YYYY-MM-DD format.
End date	The last day of the time range for the reported data.

Entity aggregation level. Coupler.io returns insights for the lowest entity for which you selected dimensions. If you select Campaign name and Ad set name, the report is returned at the Ad set level. If you only select Campaign name, the report is returned at the Campaign level.

Looking for UTM parameters? UTM parameters (utm_source, utm_campaign, utm_medium, etc.) are not available in Reports and Insights. They are part of the ad creative configuration. Use the List of Ad Creatives or List of Ads with Ad Creatives entity to access the url_tags and link_url fields.

Available metrics

Performance metrics

Name	Description
Clicks	The total number of clicks on your ad.
Impressions	The number of times your ad was on screen.
Reach	The number of people who saw your ad at least once.
Frequency	The average number of times each person saw your ad.
Full view impressions	The number of times your ad was viewed in its entirety.
Full view reach	The number of people who fully viewed your ad.
Quality ranking	A ranking of your ad's perceived quality vs. ads competing for the same audience.
Conversion rate ranking	A ranking of your ad's expected conversion rate vs. ads with the same optimization goal.
Qualifying question qualify answer rate	The percentage of answers to a qualifying question that were qualifying.

Click metrics

Name	Description
CTR	Click-through rate (clicks / impressions).
Unique CTR	The percentage of people who saw your ad and performed a click.
Unique clicks	The number of people who performed a click.
Inline link clicks	Clicks on links within the ad creative that led to a destination on or off Facebook.
Inline link click CTR	The percentage of times people saw your ad and performed an inline link click.
Unique inline link clicks	The number of people who performed an inline link click.
Outbound clicks	Clicks that lead people off of Facebook-owned properties.
Outbound clicks CTR	The percentage of times people saw your ad and performed an outbound click.
Unique outbound clicks	The number of people who performed an outbound click.
Unique outbound clicks CTR	The percentage of people who saw your ad and performed an outbound click.
Website CTR	The percentage of impressions that led to clicks on your website link.
Instant experience clicks to open	Clicks on your ad that opened an Instant Experience.
Instant experience clicks to start	Clicks on the start button within your Instant Experience.

Cost metrics

Name	Description
Amount spend	Total amount spent on your campaign, ad set, or ad.
CPC	Cost per click (link).
CPM	Cost per 1,000 impressions.
Cost per 1000 people reached	The average cost to reach 1,000 people.
Cost per inline link click	The average cost per inline link click.
Cost per inline post engagement	The average cost per inline post engagement.
Cost per outbound click	The average cost per outbound click.
Cost per unique click	The average cost per unique person who clicked.
Cost per unique inline link click	The average cost per unique person who clicked an inline link.
Cost per unique outbound click	The average cost per unique person who performed an outbound click.
Cost per estimated ad recallers	The average cost per estimated ad recaller.
Cost per DDA count by conversions	The average cost per conversion from a data-driven attribution model.
Purchase ROAS	Return on ad spend from purchase conversions.
Website purchase ROAS	Return on ad spend from website purchase conversions.
Mobile app purchase ROAS	Return on ad spend from mobile app purchases.
Social spend	The amount spent to deliver ads with social context.

Engagement metrics

Name	Description
Engagement rate ranking	A ranking of your ad's expected engagement rate vs. ads competing for the same audience.
Inline post engagement	Actions (likes, comments, shares) taken directly on the ad.

Video metrics

Name	Description
Video views	Times your video was played for a specified duration (e.g., 2s or ThruPlay).
Video ThruPlay	Times your video was played to completion, or for at least 15 seconds.
Cost per Video ThruPlay	The average cost for each ThruPlay.
2-second continuous video plays	Times your video was played for at least 2 continuous seconds.
3-Second Video Views - Total	Times your video was watched for at least 3 seconds.
3-Second Video Views - Cost	The average cost for each 3-second video view.
3-Second Video Views - Unique	The number of people who watched your video for at least 3 seconds.
30 seconds plays	Times your video was played for at least 30 seconds (or to completion if shorter).
Plays at 25%	Times your video was played to 25% of its length.
Plays at 50%	Times your video was played to 50% of its length.
Plays at 75%	Times your video was played to 75% of its length.
Plays at 95%	Times your video was played to 95% of its length.
Plays at 100%	Times your video was played to 100% of its length.
Average play time	The average duration people watched your video.
Canvas average view percent	The average percentage of an Instant Experience that people viewed.
Canvas average view time	The average time people spent viewing an Instant Experience.
Estimated ad recall rate	Estimated percentage of people who would remember seeing your ad within two days.
Estimated ad recallers	Estimated number of people who would remember seeing your ad within two days.

Conversion metrics

Conversion metrics track actions that people take after seeing or clicking your ad. Every conversion event is available in up to five variants:

Variant	What it measures
Total	The total count of conversions.
Unique	The number of unique users who triggered the conversion.
Cost	The average cost per conversion.
Unique Cost	The average cost per unique user who converted.
Value	The total monetary value from the conversion.

Looking for revenue / conversion value? Use the Value variant of the relevant conversion event. For example, to get purchase revenue, select Conversions: Purchases (Omni) - Value. This corresponds to what Ads Manager shows as "Purchase conversion value."

Looking for the "Calls placed" metric? Use Conversions: Call Confirmation Clicks - Total. This tracks the number of confirmation clicks after a user taps the call button in a call ad. Small discrepancies with Ads Manager can occur due to attribution settings or reporting timezone differences.

Conversion events

Below are all available conversion events, grouped by source.

Standard pixel events

These are tracked via the Meta Pixel or Conversions API on your website.

• Adds Payment Info

• Adds To Cart (FB pixel)

• Adds To Wishlist

• Checkouts Initiated

• Completed Registration

• Content Views

• Initiates Checkout

• Landing Page Views

• Leads

• Link Clicks

• Outbound Clicks

• Purchases (FB pixel)

• Searches (FB pixel)

• Views Content

Omni-channel events

Cross-channel conversions that combine web, app, and offline sources.

• Adds to Cart (Omni)

• App Installs (Omni)

• Checkouts Initiated (Omni)

• Credit Spends (Omni)

• Purchases (Omni)

• Registrations Completed (Omni)

• Searches (Omni)

Mobile app events

Tracked via the Facebook SDK in your mobile app.

• Mobile App Achievements

• Mobile App Adds To Cart

• Mobile App Adds to Wishlist

• Mobile App Applications Submitted

• Mobile App Appointments Scheduled

• Mobile App Canceled Subscriptions

• Mobile App Checkouts

• Mobile App Contacts

• Mobile App Content Views

• Mobile App Credit Spends

• Mobile App Donations

• Mobile App Feature Unlocks

• Mobile App Installs

• Mobile App Location Searches

• Mobile App Payment Details

• Mobile App Products Customized

• Mobile App Purchases

• Mobile App Ratings

• Mobile App Recurring Subscription Payments

• Mobile App Registrations

• Mobile App Searches

• Mobile App Starts

• Mobile App Subscriptions

• Mobile App Trials Started

• Mobile App Tutorial Completions

• Other Mobile App Actions

Website events

Tracked on your website via Pixel or Conversions API for specific actions.

• Website Applications Submitted

• Website Appointments Scheduled

• Website Canceled Subscriptions

• Website Contacts

• Website Donations

• Website Location Searches

• Website Products Customized

• Website Recurring Subscription Payments

• Website Subscriptions

• Website Trials Started

• Web purchases

• Web checkouts

• Web App purchases

• Web In-Store purchases

Offline events

Conversions from offline data sets (e.g., in-store transactions uploaded to Meta).

• Offline App Appointments Scheduled

• Offline App Location Searches

• Offline Applications Submitted

• Offline Canceled Subscriptions

• Offline Contacts

• Offline Donations

• Offline Products Customized

• Offline Recurring Subscription Payments

• Offline Subscriptions

• Offline Trials Started

On-Facebook events

Actions that happen on Facebook or Instagram properties.

• Page Engagement

• Page Likes

• Page Photo Views

• Post Comments

• Post Engagement

• Post Reactions

• Post Saves

• Post Shares

• On-Facebook Purchases

• On-Facebook Workflow Completions

• On Facebook Applications Submitted

• On Facebook Donations

• On-Facebook leads coming from Messenger and Instant Forms

• All On-Facebook Leads

• All offsite leads plus all On-Facebook leads

Messaging events

• Messaging Conversations Started

• New Messaging Conversations

• Blocked Messaging Conversations

Other events

• Achievements Unlocked

• App Activations

• App Installs

• App Uses

• Applications Submitted

• Appointments Scheduled

• Call Confirmation Clicks

• Canceled Subscriptions

• Check-ins

• Contacts

• Credit Spends

• Donations

• Event Responses

• In-App Ad Clicks

• In-App Ad Impressions

• Levels Achieved

• Location Searches

• Products Customized

• Purchases

• Ratings Submitted

• Recurring Subscription Payments

• Registrations Completed

• Searches

• Subscriptions

• Trials Started

• Tutorials Completed

• DDA count by conversions

Custom conversions

Custom conversions let you track advertiser-defined goals based on URL rules or pixel events. They appear as a separate metric group in Coupler.io's column picker under Custom conversions. The exact metrics available depend on which custom conversions you've configured in your Meta ad account.

Each custom conversion provides three variants: Total, Cost, and Value.

Examples of custom conversions (account-specific — yours will differ):

• Activation

• Begin Registration

• Complete registration

• Google traffic

Custom events

Custom events are non-standard events you fire from your Pixel, SDK, or Conversions API using fbq('trackCustom', ...). They appear in Coupler.io under the Custom event metric group.

Each custom event provides three variants: Total, Cost, and Value.

Examples of custom events (account-specific — yours will differ):

• Activation

• BeginRegistration

• Scroll 50%

Custom pixel events defined by the advertiser. This is a catch-all metric available for any advertiser-defined custom pixel event. It also provides five variants: Total, Unique, Cost, Unique Cost, and Value.

Breakdowns (dimensions)

Breakdowns let you split your Reports and Insights data by specific dimensions. You can use one or combine several — but not all combinations are allowed.

Available breakdowns

Breakdown	What it shows
Age	Performance by age group.
Gender	Performance by gender.
Country	Performance by country.
Region	Performance by region.
Comscore Markets	Performance by Comscore Market Area (US only). Replaces the previously available DMA breakdown.
Publisher platform	Which platform delivered your ads (Facebook, Instagram, Messenger, Audience Network).
Impression device	Performance by device type (mobile, desktop, tablet).
Device platform	The operating system of the device.
Product id	Performance by product (for catalog/dynamic ads).
Frequency value	Distribution of impressions by frequency count.
Hourly stats aggregated by audience time zone	Performance by hour in the viewer's time zone.
Hourly stats aggregated by advertiser time zone	Performance by hour in the advertiser's time zone.

Starting August 6, 2026, Meta requires Impression device (including any combination that includes it), Frequency value, and Hourly stats aggregated by audience time zone to be enabled per ad account in Ads Manager. Until enabled, these breakdowns return no data. See Common Issues for how to fix it.

Period breakdowns

You can also split data by time period using Split data by period:

• Daily — One row per day

• Weekly — One row per week

• Monthly — One row per month

• Totals only — Aggregated totals for the entire date range

Common metric combinations

Here are some useful combinations depending on what you're tracking:

• Campaign efficiency — Spend, Impressions, Clicks, CTR, CPC, Conversions, Cost per conversion

• Audience reach — Reach, Frequency, Impressions + Age/Gender breakdown

• Platform comparison — Spend, Clicks, CTR, Conversions + Publisher platform breakdown

• Geographic performance — Spend, Impressions, Clicks, Conversions + Country/Region breakdown

• Placement analysis — Spend, CTR, CPC + Publisher platform/Impression device breakdown

• Video performance — Video views, ThruPlay, Plays at 25%/50%/75%/100%, Average play time

• E-commerce — Purchases (FB pixel) Total/Value, Purchase ROAS, Adds To Cart, Checkouts Initiated

---

List of Campaigns

Structural data about your campaigns. No performance metrics — use Reports and Insights for that.

Metrics

Name	Description
budget_remaining	The amount of budget remaining for the campaign.

Identification & Status

Name	Description
id	The unique identifier for the campaign.
name	The name of the campaign.
Ad account name	The name of the ad account that owns the campaign.
account_id	The ID of the ad account.
status	Current status (e.g., ACTIVE, PAUSED).
configured_status	Status as configured by the user.
effective_status	Final status after considering own status and other factors.
buying_type	Buying type (e.g., AUCTION, RESERVED).

Budget & Bidding

Name	Description
bid_strategy	The bidding strategy for the campaign.
budget_rebalance_flag	Whether the budget is rebalanced across ad sets.
daily_budget	The daily budget (in cents).
lifetime_budget	The lifetime budget (in cents).
spend_cap	The maximum amount the campaign can spend.
can_use_spend_cap	Whether a spend cap can be used.
pacing_type	The pacing type for budget spending.

Objective & Category

Name	Description
objective	Campaign objective (e.g., LINK_CLICKS, CONVERSIONS).
special_ad_categories	Array of special ad categories (e.g., HOUSING, EMPLOYMENT).
special_ad_category	Primary special ad category.
special_ad_category_country	Countries for which the special ad category is declared.
smart_promotion_type	The type of smart promotion.

Scheduling

Name	Description
created_time	Timestamp when the campaign was created.
updated_time	Timestamp when the campaign was last updated.
start_time	Campaign start time.
stop_time	Campaign end time.
last_budget_toggling_time	Last time the budget was toggled.

Promoted Object

Name	Description
promoted_object.application_id	The ID of the application being promoted.
promoted_object.custom_conversion_id	The ID of the custom conversion being promoted.
promoted_object.custom_event_str	The custom event string for promotion.
promoted_object.custom_event_type	The type of custom event (e.g., ADD_TO_CART).
promoted_object.event_id	The ID of the event being promoted.
promoted_object.object_store_url	The URL of the object store.
promoted_object.offer_id	The ID of the offer being promoted.
promoted_object.offline_conversion_data_set_id	The ID of the offline conversion data set.
promoted_object.page_id	The ID of the Facebook Page being promoted.
promoted_object.pixel_id	The ID of the Meta Pixel.
promoted_object.pixel_rule	The rule associated with the Meta Pixel.
promoted_object.pixel_aggregation_rule	The aggregation rule for the Meta Pixel.
promoted_object.place_page_set_id	ID of the place page set.
promoted_object.product_catalog_id	ID of the product catalog.
promoted_object.product_set_id	The ID of the product set.
promoted_object.retention_days	The retention period in days.

Miscellaneous

Name	Description
adlabels	Labels for organizational purposes.
boosted_object_id	The ID of the boosted object (for boosted posts).
brand_lift_studies	Brand lift studies associated with the campaign.
can_create_brand_lift_study	Whether a brand lift study can be created.
is_skadnetwork_attribution	Whether the campaign uses SKAdNetwork attribution (iOS 14+).
issues_info	Information about any issues with the campaign.
recommendations	Recommendations for improving performance.
source_campaign_id	The ID of the source campaign if this was copied.
topline_id	The ID of the topline campaign.

---

List of Ad Sets

Structural and configuration data for your ad sets.

Metrics

Name	Description
budget_remaining	The amount of budget remaining for the ad set.
lifetime_imps	Total number of impressions allowed during the ad set's lifetime.

Identification & Status

Name	Description
id	The unique identifier for the ad set.
name	The name of the ad set.
Ad account name	The name of the ad account.
account_id	The ID of the ad account.
campaign_id	The ID of the parent campaign.
status	Current status (e.g., ACTIVE, PAUSED).
configured_status	Status as configured by the user.
effective_status	Effective status considering own status, campaign status, etc.

Budget & Bidding

Name	Description
bid_amount	Bid amount (in cents).
bid_strategy	Bidding strategy (e.g., LOWEST_COST_WITH_BID_CAP).
daily_budget	Daily budget (in cents).
lifetime_budget	Lifetime budget (in cents).
daily_min_spend_target	Minimum daily spend target.
daily_spend_cap	Maximum daily spend cap.
lifetime_min_spend_target	Minimum lifetime spend target.
lifetime_spend_cap	Maximum lifetime spend cap.

Scheduling

Name	Description
created_time	Timestamp when the ad set was created.
updated_time	Timestamp when the ad set was last updated.
start_time	Ad set start time.
end_time	Ad set end time.

Optimization & Delivery

Name	Description
optimization_goal	Optimization goal (e.g., REACH, IMPRESSIONS, LINK_CLICKS).
optimization_sub_event	Sub-event used for optimization.
billing_event	Event that triggers billing (e.g., IMPRESSIONS, CLICKS).
pacing_type	Pacing type for budget spending.
frequency_control_specs	Specifications for controlling ad frequency.
destination_type	Destination type (e.g., WEBSITE, APP).
attribution_spec	Attribution specification for the ad set.
is_dynamic_creative	Whether the ad set uses dynamic creative.
creative_sequence	Sequence of creatives to be shown to users.

Targeting

Name	Description
targeting.age_max	Maximum age for the target audience.
targeting.age_min	Minimum age for the target audience.
targeting.custom_audiences	Custom audiences to target.
targeting.excluded_custom_audiences	Custom audiences to exclude.
targeting.geo_locations.countries	Countries to target.
targeting.geo_locations.country_groups	Country groups to target.
targeting.geo_locations.location_types	Types of geographic locations to target.
targeting.excluded_geo_locations.countries	Countries to exclude.
targeting.excluded_geo_locations.country_groups	Country groups to exclude.
targeting.excluded_geo_locations.location_types	Location types to exclude.
targeting.publisher_platforms	Platforms (e.g., facebook, instagram).
targeting.facebook_positions	Placements on Facebook (e.g., feed, story).
targeting.instagram_positions	Placements on Instagram (e.g., feed, story).
targeting.device_platforms	Device platforms (e.g., mobile, desktop).

Promoted Object

Name	Description
promoted_object.application_id	The ID of the application being promoted.
promoted_object.custom_conversion_id	The ID of the custom conversion being promoted.
promoted_object.custom_event_str	The custom event string.
promoted_object.custom_event_type	The type of custom event (e.g., ADD_TO_CART).
promoted_object.event_id	The ID of the event being promoted.
promoted_object.object_store_url	The URL of the object store.
promoted_object.offer_id	The ID of the offer being promoted.
promoted_object.offline_conversion_data_set_id	The ID of the offline conversion data set.
promoted_object.page_id	The ID of the Facebook Page being promoted.
promoted_object.pixel_id	The ID of the Meta Pixel.
promoted_object.pixel_rule	The rule associated with the Meta Pixel.
promoted_object.pixel_aggregation_rule	The aggregation rule for the Meta Pixel.
promoted_object.place_page_set_id	ID of the place page set.
promoted_object.product_catalog_id	ID of the product catalog.
promoted_object.product_set_id	The ID of the product set.
promoted_object.retention_days	The retention period in days.

Learning Stage & Misc

Name	Description
learning_stage_info.status	Learning stage status (LEARNING, LEARNING_LIMITED, COMPLETED).
learning_stage_info.attribution_windows	Attribution windows used during the learning stage.
learning_stage_info.conversions	Conversions recorded during the learning stage.
learning_stage_info.last_sig_edit_ts	Timestamp of the last significant edit that reset learning.
adlabels	Labels for organizational purposes.
asset_feed_id	The ID of the asset feed.
instagram_actor_id	The ID of the Instagram account acting as the ad's source.
issues_info	Information about any issues with the ad set.
multi_optimization_goal_weight	Weight for multi-optimization goals.
recommendations	Recommendations for improving performance.
recurring_budget_semantics	Whether the budget is recurring.
review_feedback	Feedback from the ad review process.
rf_prediction_id	The ID of the reach and frequency prediction.
source_adset_id	The ID of the source ad set if this was copied.
time_based_ad_rotation_intervals	Intervals for time-based ad rotation.
use_new_app_click	Whether the new app click model is used.

---

List of Ads

Structural data for individual ads. No performance metrics — use Reports and Insights for performance data.

Group	Name	Description
Identification & Status	id	The unique identifier for the ad.
	name	The name of the ad.
	Ad account name	The name of the ad account.
	account_id	The ID of the ad account.
	campaign_id	The ID of the parent campaign.
	adset_id	The ID of the parent ad set.
	creative.id	The ID of the creative used in this ad.
	status	Current status (e.g., ACTIVE, PAUSED).
	configured_status	Status as configured by the user.
	effective_status	Effective status considering parent campaign/ad set status.
	source_ad_id	The ID of the original ad if this was copied.
Scheduling	created_time	Timestamp when the ad was created.
	updated_time	Timestamp when the ad was last updated.
	last_updated_by_app_id	The ID of the app that last updated the ad.
	conversion_domain	The domain used for conversion tracking.
Miscellaneous	adlabels	Labels for organizational purposes.
	bid_amount	Bid amount (in cents).
	issues_info	Information about issues that might affect delivery.
	preview_shareable_link	A shareable link to preview the ad.
	recommendations	Recommendations for improving performance.
	tracking_specs	Tracking specifications for the ad.

---

List of Ad Creatives

Creative assets, including images, videos, carousels, text, links, and media details. No performance metrics.

Key dimension groups include:

• Identification & Status — id, name, status, account_id, actor_id, adlabels

• Content & Body — body (main ad text), title (headline)

• Media & Assets — image_hash, image_url, video_id, thumbnail_id, thumbnail_url

• Links & URLs — link_url, url_tags, link_destination_display_url, link_og_id, instagram_permalink_url, object_url

• Asset Feed Specification — dynamic creative fields including asset_feed_spec.bodies, asset_feed_spec.titles, asset_feed_spec.descriptions, asset_feed_spec.images, asset_feed_spec.videos, asset_feed_spec.call_to_action_types, asset_feed_spec.link_urls, and many more

• Object Story Specification — object_story_id, plus nested fields for link_data, photo_data, video_data, text_data, and template_data (including call-to-action, image crops, child attachments for carousels, branded content, etc.)

• Degrees of Freedom (Automated Enhancements) — enrollment statuses for Meta's automated creative features like adapt_to_placement, add_text_overlay, image_animation, image_background_gen, text_optimizations, video_to_image, and more

• Miscellaneous — call_to_action_type, object_type, product_set_id, platform_customizations, playable_asset_id, template_url, and others

---

List of Ads with Ad Creatives

Combines ad-level fields with their linked creative details. No performance metrics.

This report merges the List of Ads dimensions (id, name, status, updated_time, account_id) with all Ad Creative dimensions prefixed with adcreatives. — including the full asset feed spec, object story spec, and degrees of freedom spec fields described above.

This entity does not include performance metrics (spend, clicks, impressions, etc.). To analyze which creatives drive the best results, create two data sources: (1) a Reports and Insights source at the Ad level for performance metrics, and (2) a List of Ads with Ad Creatives source for creative details (image URLs, thumbnails, ad text). Then use Coupler.io's data stitching (Join) to combine them on Ad Id.

---

List of Activities

The ad account's activity/audit log — who changed what and when. Covers changes across campaigns, ad sets, ads, and the account itself, such as campaign status updates, budget changes, and audience updates. It also includes billing and funding activity, such as charges to your payment method. No performance metrics.

Name	Description
actor_id	The ID of the person or app that performed the action.
actor_name	The name of the person or app that performed the action.
application_id	The ID of the app used to perform the action, if applicable.
application_name	The name of the app used to perform the action.
event_time	The timestamp of the activity.
date_time_in_timezone	The date and time of the activity, in the ad account's timezone.
event_type	The category of the activity (e.g., account update, ad creation, billing charge).
translated_event_type	A human-readable description of the event type.
object_id	The ID of the object that was changed (ad, ad set, campaign, account, etc.).
object_name	The name of the object that was changed.
object_type	The type of object that was changed.
extra_data	Additional JSON-encoded details about the change. You can extract needed data to separate column using formula based columns and JSON_EXTRACT formula.

event_type groups activities by the object they affect:

• Account — status changes, spend limit updates, user role changes, image library changes

• Campaign — creation, name/run status/duration updates, budget changes

• Ad set — creation, budget, bidding, targeting, and optimization goal updates

• Ad — creation, creative updates, run status changes, ad review approval/decline

• Audience — creation, updates, sharing, and unsharing

• Billing & funding — charges, failed charges, chargebacks, chargeback reversals, refunds, funding source added/removed

List of Business invoices

Monthly invoices for the bill-to legal entities on your Facebook Business, with a line item per campaign billed within each invoice.

Invoice fields

Name	Description
id	Internal id for the invoice.
ad_account_ids	The list of ad account ids this invoice is about.
advertiser_name	The name of the advertising party listed on the invoice.
amount	The amount of the invoice.
amount_due	The amount left to be paid — the billed amount minus the amount already paid.
billed_amount_details	Details of the billed amount, including currency, net, tax, and total amount.
billing_period	The billing period associated with the invoice.
cdn_download_uri	An ephemeral CDN URL that can be used to download the invoice.
currency	The currency of the invoice.
download_uri	The download URI for the invoice PDF.
due_date	The date by which the invoice is due.
entity	The Facebook entity name for the transaction.
invoice_date	The date the invoice was created.
invoice_id	The actual invoice id for the transaction.
invoice_type	The type of invoice, e.g. Invoice or Credit Memo.
liability_type	The liability type associated with usage of this funding source.
payment_status	The payment status of the invoice, e.g. Paid, Partially Paid.
payment_term	When payment is expected, e.g. "Net 30" means payment is expected within 30 days.
type	The type of the invoice.

Campaign breakdown fields

Each invoice includes a line item per campaign it billed, with these fields:

Name	Description
ad_account_id	The id of the ad account.
campaign_id	The id of the campaign.
campaign_name	The name of the campaign.
billed_amount_details	The breakdown spend of this campaign.
clicks	The total number of clicks for the campaign charged in the invoice.
conversions	The total number of conversions for the campaign charged in the invoice.
impressions	The total number of impressions for the campaign charged in the invoice.
description	The campaign's description on the invoice line item.
tags	Customer tags for the campaign.

---

Use cases by role

• Marketers — Track campaign performance daily, compare ad creatives, and identify top-performing audiences using demographic and platform breakdowns.

• Finance teams — Monitor ad spend across accounts, calculate ROI with spend vs. conversion data, and export to spreadsheets for budget reconciliation.

• E-commerce managers — Analyze product-level ad performance using Product ID breakdowns, track ROAS, and correlate ad spend with sales data.

• Business owners — Get high-level dashboards combining spend, reach, and conversions across all campaigns without needing to open Ads Manager.

Platform-specific notes

• Attribution windows — Facebook attributes conversions within specific time windows (e.g., 1-day view, 7-day click). You can configure this in Coupler.io under Advanced settings — either inherit your ad account defaults or specify manually. Mismatched attribution settings are the most common cause of data discrepancies.

• Data latency — The Facebook Ads API may not have complete data for the most recent 1–2 days. For reliable reporting, use yesterday's date or earlier as your end date.

• Incompatible breakdowns — Some breakdown combinations are not supported by the Facebook API. For example, you cannot combine demographic breakdowns (age, gender) or geographic breakdowns (country, region) with hourly breakdowns. If you select an incompatible combination, the import may fail.

• Action breakdown inflation — When using action breakdowns (like action type or action destination), the sum of broken-down values may exceed the total. This is because a single action can be attributed to multiple breakdown values.

• Ad insights timezone — Ad insights data is retrieved in the ad account's timezone.

Facebook Ads common issues

Here are the most common issues you might run into when working with the Facebook Ads source in Coupler.io, along with how to fix them.

Connection issues

OAuth token expired

Facebook access tokens can expire or be revoked. If your imports start failing, go to the Sources page in Coupler.io and reconnect your Facebook account.

Permissions not granted

Make sure you granted all requested permissions during the OAuth flow. If you skipped any, disconnect and reconnect your Facebook account.

Two-factor authentication

If you recently enabled 2FA on your Facebook account, you may need to re-authenticate in Coupler.io.

Missing data or accounts

Ad account not showing up

You need Admin or Advertiser access to the ad account in Meta Business Suite. If you were recently granted access, try disconnecting and reconnecting your Facebook credentials.

No data returned

Check that the selected ad account has active or past campaigns for the date range you specified. An empty report usually means no ads ran during that period.

Missing recent data

The Facebook Ads API has a data latency of 1–2 days. Data for today or yesterday may be incomplete. Use yesterday's date or two days ago as your end date for reliable results.

No data for Impression device, Frequency value, or Hourly stats (audience time zone) breakdowns

As of August 6, 2026, Meta requires these breakdowns to be enabled per ad account before its Marketing API returns results for them:

• Impression device (impression_device) — including any breakdown combination that includes it

• Frequency value (frequency_value)

• Hourly stats aggregated by audience time zone (hourly_stats_aggregated_by_audience_time_zone)

Until an ad account is enabled, imports using these breakdowns return no results — even if you've used them successfully before. This applies across all Marketing API versions and isn't specific to Coupler.io.

To fix it:

1. In Ads Manager, enable the breakdown for the affected ad account (only needed if you haven't already used it there).

2. Re-run your Coupler.io data flow.

Once enabled, you will get full history, including data from before enablement.

These breakdowns aren't being removed — they remain available once enabled. If your data flow doesn't use any of them, no action is needed.

Permission errors

"Insufficient permissions" error

Your Facebook user must have access to the ad account at the Admin or Advertiser level. Check your roles in Meta Business Suite > Business Settings > People.

"User does not have sufficient permissions for this action on this page"

This typically occurs when getting Page-related reports. To fix it:

1. The page owner should go to Facebook Profile Access Settings and verify you are not added as a user with Page or Task access that limits your scope.

2. Check your permissions in Facebook Business Manager: open the Business that owns the page, open your username settings, and confirm you have Partial access to the page.

3. If you're using the new Pages experience, you need Partial Access to the linked Facebook account.

4. After fixing permissions, remove Coupler.io from Business Integrations on your Facebook account, then delete and recreate the Facebook connection in Coupler.io.

Ad account access revoked

If someone removed your access to an ad account, imports for that account will fail. Contact the account owner to restore access.

Facebook Pages or Instagram Profiles not showing up

If a Facebook Page or Instagram Profile is missing from the selection dropdown in Coupler.io:

1. Check page permissions. You need Administrator access to the Page, or Page Editor access via Business Manager. With the new Pages experience, you need Partial Access to the linked Facebook account.

2. Reconnect your Facebook / Instagram connection. Click Reconnect if you see an error below the Pages/Profiles field. Log in to Facebook, approve any missed permissions, and re-select your Page or Profile.

3. Check app permissions in your Facebook account. Go to Facebook > Settings > Business integrations > View and Edit for Coupler.io. Make sure the needed page is selected under "Read content posted on the Page" and "Show a list of the Pages you manage."

If a page was connected but later disappeared, it's often because Facebook didn't provide the scope consent screen during the initial connection — especially when only one page was selected. Reconnecting and re-approving permissions typically resolves this.

Data discrepancies

Reach metric appears inflated in dashboards

Reach counts unique users over a time period — it is not summable. If you export daily Reach and aggregate it in Looker Studio, Google Sheets, or any other tool, you will double-count users who saw ads on multiple days, producing totals higher than what Ads Manager shows.

To match Ads Manager's Reach figure for a date range:

• Use "Split data by period: Totals only" in Coupler.io so the API returns a single deduplicated Reach value for the entire period.

• If you need daily granularity, display Reach per-row (e.g., per day or per campaign) and do not sum it in your dashboard.

CTR, CPC, CPM and other ratio metrics show incorrect totals

Ratio metrics like CTR (click-through rate), CPC (cost per click), and CPM (cost per 1,000 impressions) cannot be summed. If your dashboard tool (e.g., Looker Studio) uses SUM as the default aggregation, the resulting totals will be meaningless.

Instead, create calculated fields in your dashboard that recompute the ratio from raw totals:

• CTR = Clicks / Impressions

• CPC = Spend / Clicks

• CPM = (Spend / Impressions) × 1,000

This ensures correct values at every aggregation level.

ROAS values are different

There may be a case where a higher ROAS metric is shown in the Facebook Ads UI than in Coupler.io-imported data.

This might happen when using a different attribution window in Coupler.io settings compared to what you use in Facebook Ads.

From ROAS Ad Rules - Marketing API - Documentation - Meta for Developers :

"This attributes all mobile app purchase values within 7 days of users who clicked on the ad in the lookback window, excluding the most recent 7 days since they include immature data. If the user clicked on the ad yesterday, we do not include that user in the ROAS computation, since they still have 6 days of potential purchases.

Check what attribution setting you are using and make sure it matches the one you use in FB Ads:

Numbers don't match Ads Manager

The most common cause is mismatched attribution settings. In Coupler.io Advanced settings, make sure the action attribution window matches what you use in Ads Manager. If nothing is selected in Coupler.io, a 7-day click window is used by default.

Other things to check:

1. Time aggregation — Verify that "Split data by period" in Coupler.io (Daily, Weekly, Monthly, or Totals) matches what you're viewing in Ads Manager.

2. Entity aggregation level — Coupler.io returns insights for the lowest entity for which you selected dimensions. If you selected Campaign name and Ad set name, the report is at the Ad set level. If you compare that to a Campaign-level report in Ads Manager, numbers will differ.

3. Breakdowns — Make sure the breakdowns in Coupler.io match those in Ads Manager. For example, if Coupler.io breaks down by Publisher platform but Ads Manager doesn't, the numbers won't align.

Overinflated numbers with breakdowns

When using action breakdowns (like action type or action destination), totals may appear higher than expected. This is because a single action can be counted across multiple breakdown values. For accurate totals, avoid action breakdowns.

Daily vs. monthly totals don't add up

If you switch between "Daily" and "Totals only" in Split by period, rounding and attribution differences may cause slight variations.

Filters hiding deleted or archived entities

When you use any filter in Advanced settings, Facebook's API applies a default status filter that returns only ACTIVE objects. This means deleted or archived ads/ad sets/campaigns are excluded, and totals will be lower than what you see in the parent-level report in Ads Manager.

To include deleted and archived entities, add an explicit status filter alongside your other filters.

Conversion counts lower than Ads Manager (1-day engaged-view attribution)

Meta Ads Manager can display conversions attributed to a 1-day engaged-view window. This attribution window is not available through the Facebook Ads API, so Coupler.io cannot pull those conversions.

If you see fewer purchases or other conversions in Coupler.io than in Ads Manager, check whether Ads Manager is including 1-day engaged-view attribution. The difference is the conversions attributed to that window. To get the closest match, explicitly set your attribution windows in Coupler.io's Advanced settings to 7-day click + 1-day view and compare against the same setting in Ads Manager.

API errors

"Request to Facebook API has failed" (status 400 / deprecated metric)

This usually means a metric you selected has been deprecated by Meta. The error message from the API is:

(#100) The value must be a valid insights metric

To fix it:

1. Open your data flow in Coupler.io and go to the column selection step.

2. Look for any metric highlighted with a warning or that you don't recognize.

3. Remove the deprecated metric and re-run the import.

Meta periodically deprecates metrics across API versions. If you're unsure which metric is causing the issue, try removing recently added metrics one at a time until the import succeeds.

"Async Job failed" error

Facebook generates large ad reports asynchronously. If the job fails, you'll see an error like:

An error occurred during fetching data from Facebook: 'Async Job failed'

Common causes:

• Temporary issues on Facebook's side — the report generation infrastructure may be overloaded.

• Rate limits — the ad account has too many concurrent report requests.

• Report too large — the combination of date range, breakdowns, and metrics produces a dataset that exceeds Facebook's processing limits.

To resolve:

1. Re-run the import after waiting a few minutes — transient failures often resolve on their own.

2. Narrow the date range or change the "Split by" interval to reduce report size.

3. If the same account consistently fails, split the data flow into multiple sources with smaller date ranges.

"Call was not successful" error

This is a generic error from the Facebook API, sometimes accompanied by a status 500 response:

An error occurred during fetching data from Facebook: 'Call was not successful'

It can be caused by:

• Temporary Facebook API server issues

• Permission problems on the ad account

• Account-specific limitations or restrictions

In most cases, retrying after a few minutes resolves the issue. If it persists, verify that your Facebook connection is still active and that you have the required permissions on the ad account.

Rate limits

Import fails with rate limit error

Facebook limits how many API requests can be made per ad account. If you have multiple data flows pulling from the same ad account simultaneously, some may hit rate limits. Space out your scheduled refreshes or reduce the number of concurrent imports for the same account.

Large date ranges timing out

Very long date ranges with many breakdowns can exceed API limits. Try narrowing the date range or reducing the number of breakdowns and metrics.

Facebook Ads FAQ

Answers to the most frequently asked questions about using the Facebook Ads source in Coupler.io.

What report types are available?

Coupler.io supports nine Facebook Ads report types: Reports and Insights, List of Sponsored Leads, List of Campaigns, List of Ad Sets, List of Ads, List of Ad Creatives, List of Ads with Ad Creatives, List of Activities, and List of Business invoices. See the Data Overview for details on each.

Can I pull data from multiple ad accounts?

Yes. When configuring the source, you can select multiple ad accounts. Keep in mind that each ad account counts as a separate account toward your Coupler.io plan limit.

What date range can I pull?

For Reports and Insights and Leads, you set a start and end date using the date picker. There's no hard limit on the date range, but very large ranges with many breakdowns can be slow or hit API limits.

Why doesn't my data match what I see in Ads Manager?

The most common reason is a mismatch in attribution settings. Make sure the attribution window in Coupler.io (under Advanced settings) matches what you use in Ads Manager. Also verify that date ranges, breakdowns, and report types match. See Common Issues for detailed troubleshooting.

Why is data for today missing or incomplete?

The Facebook Ads API typically has a 1–2 day data latency. Data for the current day (and sometimes yesterday) may not be fully processed yet. Set your end date to yesterday for the most reliable results.

What are breakdowns and should I use them?

Breakdowns split your data by dimensions like age, gender, country, device, or publisher platform. They're useful for deeper analysis, but each breakdown multiplies the number of rows in your report. Only use breakdowns you actually need. See Best Practices for tips.

Why is my Impression device, Frequency value, or Hourly stats breakdown returning no data?

Starting August 6, 2026, Meta requires these breakdowns to be enabled per ad account in Ads Manager: Impression device (including any combination that includes it), Frequency value, and Hourly stats aggregated by audience time zone. Until you enable a breakdown for the ad account, Facebook's API returns no results for it, even if you used it before. See Common Issues for how to fix it.

Can I filter data by campaign or ad?

Yes. In the Advanced settings, you can add filters using Facebook's Graph API syntax. For example, to pull only campaigns containing "Brand" in the name: [{"field":"campaign.name","operator":"CONTAIN","value":"Brand"}]

How does Coupler.io count Facebook Ads accounts for billing?

Facebook Ads is a tenant-based source. Coupler.io counts each ad account you select in the setup wizard as one account toward your plan limit. It doesn't matter how many report types or data flows you create — what matters is the number of unique ad accounts used per credential. See Accounts Limit Calculation for full details.

Can I schedule automatic data refreshes?

Yes. After setting up your data flow, you can configure a refresh schedule (hourly, daily, weekly, etc.) under the data flow settings. Your destination will be updated automatically.

Can I change the currency of my Facebook Ads data?

No — the currency is determined by your ad account settings in Meta. Coupler.io pulls monetary values (spend, CPC, conversion values, etc.) in whatever currency the ad account uses. Coupler.io's column formatting lets you change the display label (e.g., show € instead of $), but the underlying numbers remain in the original currency. To get data in a different currency, you would need to create a new ad account in Meta with that currency.

Can I pull ad creative images or thumbnails?

Yes. Use the List of Ad Creatives or List of Ads with Ad Creatives entity. The relevant fields are image_url, thumbnail_url, and video_id. Note that these entities do not include performance metrics — to combine creative details with spend, clicks, or conversions, create a separate Reports and Insights source at the Ad level and join the two on Ad Id using Coupler.io's data stitching.

Can I get UTM parameters from my ads?

UTM parameters are part of the ad creative, not the performance report. Use the List of Ad Creatives or List of Ads with Ad Creatives entity to access the url_tags and link_url fields, which contain the UTM parameters configured in your ads. These fields are not available in Reports and Insights.

Why does Reach in my dashboard not match Ads Manager?

Reach is a unique-users metric — it cannot be summed across days, campaigns, or ad sets. If your dashboard aggregates daily Reach rows (e.g., using SUM in Looker Studio), the total will be inflated because users who saw your ad on multiple days get counted more than once.

To match Ads Manager, use "Split data by period: Totals only" in Coupler.io for the same fixed date range. This returns a single deduplicated Reach value from the API. If you need daily granularity, display Reach per-row and avoid summing it.

How do I get ROAS or purchase revenue?

• For return on ad spend, use the Purchase ROAS or Website Purchase ROAS metric.

• For purchase revenue, use the Value variant of the relevant conversion event — e.g., Conversions: Purchases (Omni) - Value or Conversions: Purchases (FB pixel) - Value.

Make sure your attribution window in Coupler.io matches what you use in Ads Manager. Note that the 1-day engaged-view attribution window is not available through the API, so conversion counts may be slightly lower than in Ads Manager. See Common Issues for details.

How do I get performance metrics alongside creative data?

The List of Ads with Ad Creatives entity provides structural and creative data (image URLs, ad text, video IDs) but does not include performance metrics like spend, clicks, or conversions. To combine both:

1. Create a Reports and Insights source at the Ad level with the metrics you need.

2. Create a List of Ads with Ad Creatives source for the creative fields.

3. Use Coupler.io's data stitching (Join) to combine them on Ad Id.

This gives you a unified dataset with creative details and performance numbers.

What if I need help?

If you can't resolve an issue using this documentation, contact Coupler.io support with your importer ID and screenshots showing the data discrepancy.