> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/ppc/facebook-ads.md).
# Facebook Ads (Meta Ads)
Connect Facebook Ads to Coupler.io to automate campaign performance reporting across Facebook, Instagram, Messenger, and Audience Network.
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:
* [x] A Facebook account with access to at least one **Ad Account** in [Meta Business Suite](https://business.facebook.com/)
* [x] **Admin or Advertiser** permissions on the Ad Account you want to pull data from
### Quick start
{% hint style="success" %}
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.
{% endhint %}
### How to connect
Facebook Ads uses **OAuth authentication** — you sign in with your Facebook account directly.
{% stepper %}
{% step %}
In Coupler.io, create a new **data flow** and select **Facebook Ads** as the source.\
Click **Connect** and sign in with your Facebook account.
{% endstep %}
{% step %}
Grant Coupler.io the requested permissions to access your ad data.
{% endstep %}
{% step %}
Select the **Ad Account(s)** you want to pull data from.
{% endstep %}
{% step %}
Choose a **report type** (see the most popular ones below).
{% endstep %}
{% step %}
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.
{% endstep %}
{% step %}
Choose your **destination** and run the import.
{% endstep %}
{% endstepper %}
### 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. |
{% hint style="warning" %}
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](#missing-data-or-accounts) for how to fix it.
{% endhint %}
#### 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](https://app.coupler.io/app/sources) 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](https://business.facebook.com/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](https://www.facebook.com/settings?tab=profile_access) 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](https://business.facebook.com/settings/people): 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](https://www.facebook.com/business/help/2752670058165459?id=418112142508425), you need Partial Access to the linked Facebook account.
4. After fixing permissions, remove Coupler.io from [Business Integrations](https://www.facebook.com/settings/?tab=business_tools) 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](https://developers.facebook.com/docs/marketing-api/ad-rules/guides/roas-ad-rules/) :
>
> "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](#facebook-ads-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](#facebook-ads-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](/sources/category/ppc/facebook-ads/best-practices.md) 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](#missing-data-or-accounts) 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](broken://pages/vjPA7mOwlQhoWcVG3xVV) 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](#facebook-ads-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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.coupler.io/sources/category/ppc/facebook-ads.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
