--- title: "Facebook Ads" slug: "facebook-ads" description: "Get the most out of your Facebook Ads data with Dataddo. Learn how to create a data source, correctly select metrics, dimensions, and data labels, and more." updated: 2026-07-09T08:26:10Z published: 2026-07-09T08:26:10Z canonical: "docs.dataddo.com/facebook-ads" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.dataddo.com/llms.txt > Use this file to discover all available pages before exploring further. # Facebook Ads **Facebook Ads** is an advertising platform. Businesses and individuals use it to create and run targeted ad campaigns on Facebook. It includes tools for audience targeting, ad creation, and performance tracking. Refer to this page to see [all available endpoints from the Facebook Ads API](/docs/facebook-ads-fields-references). If you have multiple Facebook Ads accounts and would like to extract the same data from all of them, it's possible through [multi-account extraction](/docs/multi-account-extraction). Contact our Solutions team to enable this feature. ## Authentication Methods Facebook Ads supports more than one way to connect. Pick one when you create the authorizer in Dataddo: - **Facebook account** - sign in with Facebook and approve access (recommended). - **Meta Admin Center** - connect through the Meta Admin Center. - **Your own Facebook app** - use your own Facebook app credentials (for advanced setups). ## Authorize Connection to Facebook Ads To authorize this service, use **OAuth 2.0** to share specific data with Dataddo while keeping usernames, passwords, and other information private. 1. On the **Authorizers** page, click on [Authorize New Service](https://app.dataddo.com/service/new) and select your service. 2. Follow the on-screen prompts to grant Dataddo the necessary permissions to **access and retrieve** your data. 3. **[Optional]** Once your ***authorizer*** is created, click on it to **change the label** for easier identification. Ensure that the account you're granting access to holds at least **admin-level permissions**. If necessary, assign a team member with the required permissions with the [authorizer role](https://docs.dataddo.com/docs/user-roles#authorizer) to authenticate the service for you. For more information, see our article on [***authorizers***](https://docs.dataddo.com/docs/authorized-services). ### Using System User The best practice is to create a dedicated **Admin System User** in Facebook (Meta) Business Manager. Here is the step-by-step guide: 1. Go to business facebook manager and create a Business Manager account if you don’t already have one. 2. Add your Facebook page to your Business Manager. 3. Create a Facebook App: In the facebook developer portal create a new app (or use an existing one). 4. Add a System User: In Business Manager, navigate to Business Settings > Users > System Users. 5. Click Add to create a new system user (give it a name and assign it a role, usually “Admin” for full access). 6. Assign Assets and Permissions: Assign your Facebook page as an asset to the system user. 7. Grant the system user the necessary permissions for the page. 8. Generate a System User Access Token: In the system user’s settings, click Generate New Token. (Select your app and the required permissions.) 9. Use the System User Access Token to generate a System Page Access Token ## Data Coverage Facebook Ads exposes the following datasets. Each dataset maps to a table you can extract. Example fields are a representative sample; each dataset returns more columns. The Date range column shows whether a dataset extracts a selected relative window or all available data (see below). | Dataset | Description | Example fields | Date range | | --- | --- | --- | --- | | Account Reach (Unified Attribution) | Performance metrics calculated using Facebook’s Unified Attribution Setting. Data is returned without demographic breakdown and reflects the attribution window configured in the ad account. | Account Id, Date Start, Date Stop, Account Name, Action Type, Action Value (+2 more) | Yes | | Account Performance by Age & Gender (Unified Attribution) | Performance metrics broken down by age and gender. Metrics are calculated using Facebook’s Unified Attribution Setting and may vary depending on the selected attribution window. | Account Id, Date Start, Date Stop, Account Name, Action Type, Action Value (+4 more) | Yes | | Account | Data for the account | Account Id, Id, Account Status, Ad Account Promotable Objects, Age, Agency Client Declaration (+58 more) | No | | Action Types | Data for the actions | Ad Id, Adset Id, Account Id, Campaign Id, Account Name, Action Type (+6 more) | Yes | | Ad Action Metrics by Publisher Platform | Ad-level action metrics broken down by action type and publisher platform, with one row per action type per ad. | Ad Id, Action Type, Account Id, Account Name, Action Value, Ad Name (+7 more) | Yes | | Age Gender Breakdowns Ad Insights | Insights for Ads with the Age and Gender Breakdowns | Account Id, Ad Id, Account Currency, Account Name, Action Values, Actions (+111 more) | Yes | | Ad Creatives | Data for the visual rendering of the ad itself | Account Id, Id, Actor Id, Ad Disclaimer Spec, Adlabels, Applink Treatment (+60 more) | No | | Ad Creatives (by Ads) | Data for the visual rendering of the ad itself | Creative Id, Account Id, Ad Id, Ad Name, Ad Status, Adset Id (+57 more) | No | | Ad Images | Get ad image data and URLs | Id, Account Id, Created Time, Creatives, Hash, Height (+10 more) | No | | Platform Position Device Ad Insights | Insights for Ads with the Platform, Position and Device Breakdowns | Account Id, Ad Id, Account Currency, Account Name, Action Values, Actions (+112 more) | Yes | | Ad Reach (Unified Attribution) | Performance metrics calculated using Facebook’s Unified Attribution Setting. Data is returned without demographic breakdown and reflects the attribution window configured in the ad level. | Account Id, Ad Id, Adset Id, Campaign Id, Date Start, Date Stop (+8 more) | Yes | | Ad Performance by Age & Gender (Unified Attribution) | Performance metrics broken down by age and gender. Metrics are calculated using Facebook’s Unified Attribution Setting and may vary depending on the selected attribution window. | Account Id, Ad Id, Adset Id, Campaign Id, Date Start, Date Stop (+10 more) | Yes | | Ad Sets Insights | Statistics for AdSets | Id, Account Id, Adlabels, Adset Schedule, Asset Feed Id, Attribution Spec (+56 more) | No | | User Segment Key Ad Insights | Insights for Ads with the User Segment Key Breakdown | Account Id, Ad Id, Account Currency, Account Name, Action Values, Actions (+111 more) | Yes | | Video Asset Ad Insights | Insights for Ads with the Video Asset Breakdown | Account Id, Ad Id, Account Currency, Account Name, Action Values, Actions (+110 more) | Yes | | Ad Videos | Videos used in Ad creatives | Id, Ad Breaks, Backdated Time, Backdated Time Granularity, Boost Eligibility Info, Content Category (+32 more) | No | | Ads | Data for the ads | Id, Account Id, Ad Active Time, Ad Review Feedback, Ad Schedule End Time, Ad Schedule Start Time (+23 more) | No | | Adset Reach (Unified Attribution) | Performance metrics calculated using Facebook’s Unified Attribution Setting. Data is returned without demographic breakdown and reflects the attribution window configured in the adset level. | Account Id, Adset Id, Campaign Id, Date Start, Date Stop, Account Name (+6 more) | Yes | | Adset Performance by Age & Gender (Unified Attribution) | Performance metrics broken down by age and gender. Metrics are calculated using Facebook’s Unified Attribution Setting and may vary depending on the selected attribution window. | Account Id, Adset Id, Campaign Id, Date Start, Date Stop, Account Name (+8 more) | Yes | | Business Client Ad Accounts | Relations between Business and Ad accounts | Account Id, Id, Account Status, Ad Account Promotable Objects, Age, Agency Client Declaration (+60 more) | Yes | | Campaign DMA Insights | Insights for Campaigns with Designated Market Area Breakdown | Account Id, Account Currency, Account Name, Action Values, Actions, Ad Click Actions (+106 more) | Yes | | Campaign Maximum Date Preset | Insights for Campaigns with Max Date Preset | Account Id, Account Currency, Account Name, Action Values, Actions, Ad Click Actions (+105 more) | No | | Campaign Reach (Unified Attribution) | Performance metrics calculated using Facebook’s Unified Attribution Setting. Data is returned without demographic breakdown and reflects the attribution window configured in the campaign level. | Account Id, Account Name, Campaign Id, Date Start, Date Stop, Action Type (+4 more) | Yes | | Campaign Performance by Age & Gender (Unified Attribution) | Performance metrics broken down by age and gender. Metrics are calculated using Facebook’s Unified Attribution Setting and may vary depending on the selected attribution window. | Account Id, Campaign Id, Date Start, Date Stop, Account Name, Action Type (+6 more) | Yes | | Campaigns Insights | Statistics for Campaigns | Id, Account Id, Adlabels, Bid Strategy, Boosted Object Id, Brand Lift Studies (+33 more) | No | | Connected Instagram Accounts | Get data of connected Instagram accounts | Id, Biography, Followers Count, Follows Count, Has Profile Pic, Ig Id (+8 more) | No | | Custom Audiences Insights | Statistics for Custom Audiences | Account Id, Id, Approximate Count Lower Bound, Approximate Count Upper Bound, Customer File Source, Data Source (+20 more) | No | | Facebook Custom Conversions | List of custom conversions for a Facebook ad account | ID, Business ID, Business Name, Creation Time, Custom Event Type, Default Conversion Value (+8 more) | No | | Facebook Ads Insights | Access Facebook Ads Insights data | Account currency, Account ID, Account name, Add payment info (value), Add to cart (value), Add to wishlist (value) (+558 more) | Yes | | Promote Pages | Statistics for Promote Pages | Id, About, Access Token, Ad Campaign, Affiliation, App Id (+139 more) | No | ## How Data Extraction Works What each extraction pulls depends only on whether a dataset supports a date range (see the Date range column above): - **Date range supported (Yes):** the source reads a relative window (for example "last 7 days"), and that window slides forward with the current date. Every run re-reads the window, so a range of "1 day ago" always pulls the previous day (D-1). Each run replaces the window's data rather than adding older history. To load records from before the window, run a full data re-sync with a wider range. See [Data Backfilling](/docs/data-backfilling). - **No date range (No):** every run pulls all currently available data. Set the relative date range when you create the source. ## Metadata Columns When you create a source, you can add these Dataddo metadata columns to the extracted data: - **dataddo_hash** - a fingerprint built from each record's key fields. It works as a natural key, so it is ideal for upserts (updating existing rows in your destination instead of creating duplicates). - **dataddo_extraction_timestamp** - the date and time the row was extracted. Use it to track how records change over time, for example to build slowly changing dimensions. ## Hash Sensitive Fields Some datasets include columns with personal data, such as names, email addresses, or phone numbers. When you create a source, you can turn on **Hash Sensitive Fields** and use the **Select Columns for Sensitive Computation** picker to choose which of these columns to protect. Dataddo replaces the selected values with a hash before the data leaves Dataddo, so the raw personal data is never written to your destination. ## How to Create a Facebook Ads Data Source Creating a data source takes you through five steps, shown in the progress bar at the top of the wizard. Each step is explained below. **1. Pick the connector** On the **Sources** page, click **Create Source**, then select the connector from the catalog. Use the search bar or the category tabs if you do not see it right away. You can rename the source at any time using the pencil icon next to its name. **2. Choose the account** This step selects what Dataddo reads from. - **Authorizer:** Select an account you have already authorized from the drop-down. If you have none yet, choose **Add new account** and follow the prompts. If no authorizer is selected, Dataddo asks you to authorize before you continue. - **What to extract from:** Select the exact entity you want to pull data from. Depending on the service this may be labelled an account, property, profile, workspace, or similar, sometimes with a sub-level to choose as well. - **Multiple accounts:** To pull the same data from every entity you can access, turn on **Automatically collect data from all ...**. This is multi-account extraction. Leave it off to choose them by hand. **3. Build the data model** Choose exactly what to extract. What you can pick depends on the connector, and the wizard may group the fields differently for each one. - **Values:** the measures you want, often called metrics, such as sessions, clicks, or revenue. - **Breakdowns:** the fields you group or split those values by, often called dimensions or attributes, such as date, country, or campaign. - **Context metadata (when available):** identifier fields that Dataddo derives from your selection, such as the account or property ID. They let you tell rows apart when you combine several sources. Some connectors limit which fields can be queried together; the wizard flags this where it applies. Click **Test on Sample Data** at any point to preview the result before you continue. **4. Add metadata columns (optional)** Two optional columns help your destination handle the data. - **Dataddo Hash (Include Row Hash):** a fingerprint built from the columns you pick. It works as a natural key, so your destination can deduplicate rows and run upserts instead of creating duplicates. Turn it on, then select the columns that uniquely identify a row. - **Dataddo Extraction Timestamp:** the time each row was extracted. Use it to watermark the data, for example to build slowly changing dimensions or to track when a value last changed. **5. Set the schedule** Decide how often Dataddo runs the extraction. - **Frequency:** how often the pipeline runs, for example daily. Click **Show advanced settings** to also set the exact hour and minute (UTC). - **Date range:** the relative window each run extracts, for example "Yesterday". The window moves forward on every run. - **Historical data:** a new source starts from the current window. To load older data, run a [full data re-sync](https://docs.dataddo.com/docs/data-backfilling) after the source is created. - **Allow Empty Data Extractions:** when on, a run that returns no data records zero rows instead of failing. Turn it on if the source can legitimately have periods with no data. Click **Save**. Your data source is ready. ## Limitations ### Attributes Selection You can select Facebook Ads attributes based on the **reporting level**. The reporting level is a hierarchy-type report: - 1st level: **Account** - 2nd level: **Campaign** - 3rd level: **Adset** - 4th level: **Ad** Find more information in [Facebook's official documentation](https://developers.facebook.com/docs/marketing-api/reference/adgroup/#Reading). ### Historical Data Limitation The Facebook Ads API has two limitations for historical data: - You may load up to **90 days per extraction batch**. - In total, you may extract up to **37 months** of historical data. For more information, refer to our [guide for data backfilling](/docs/data-backfilling). ### Limited Data Breakdown Combinations Due to the Facebook Ads API, **not all** data insight breakdown combinations are viable. Dataddo offers a list of all possible combinations what are supported and won't cause issues for your ***data source***. Refer to Facebook's official documentation for [the list of possible data insight breakdown combinations](https://developers.facebook.com/docs/marketing-api/insights/breakdowns#combiningbreakdowns). However, if you require a combination that **is supported but not available in Dataddo**, please contact our Solutions team. ### Number of Metrics The Facebook Ads API allows you to select up to **200 metrics per source**. ### Number of Rows Under normal circumstances, the Facebook Ads API sets a hard limit on the total number of rows that can be extracted per call. To overcome this limitation, Dataddo supports automatic pagination to make multiple calls and retrieve all your data. ### Using Audience Breakdowns Using both **demographic** and **geographical** dimensions to to break down the metrics according to the audience categories **might lead to data discrepancies**. This is caused by underlying calculations which are based on [data sampling](/docs/data-sampling). As such, while the data will have correct percentage values, the absolute values can be distorted. ## Troubleshooting ### Data Preview Unavailable No data preview when you click on **Test Data** might be caused by an issue with your ***source*** configuration. The most common causes are: - **Date range**: Try a smaller date range. You can load the rest of your data afterward using [manual data load](https://docs.dataddo.com/docs/data-backfilling). - **Insufficient permissions**: Please make sure your authorized account has at least admin-level permissions. - **Invalid metrics, attributes, or breakdowns**: You may not have any data for the selected metrics, attributes, or breakdowns. - **Incompatible combination of metrics, attributes, or breakdowns**: Your selected combination cannot be queried together. Please refer to the service's documentation to view a full list of metrics that can be included in the same ***data source***. ### Authorization Error Broken Facebook ***sources*** that return the following error messages when **testing the extraction** (broken ***source*** > three dots > **Test Extraction**) must be [reauthorized](/docs/authorized-services#how-to-reauthorize-your-account): ``` "response_status": "401 Unauthorized" ``` ``` "Www-Authenticate": "OAuth \"Facebook Platform\" \"invalid_token\" \"You cannot access the app till you log in to www.facebook.com and follow the instructions given.\"" ``` ``` "response_body": "{\"error\":{\"message\":\"You cannot access the app till you log in to www.facebook.com and follow the instructions given.\",\"type\":\"OAuthException\",\"code\":190,\"error_data\":\"{\\\"checkpoint_url\\\":\\\"https:\\\\\\/\\\\\\/www.facebook.com\\\"}\",\"error_subcode\":459,\"fbtrace_id\":\"AUWZQsg7Opr7SEpp_lk9wUa\"}}" ``` **DATADDO TIP** Once reauthorized, make sure to [load the missing data](/docs/data-backfilling). You can also click the [**Debug & Restart**](/docs/en/troubleshooting#how-to-fix-a-broken-source) icon next to the broken source and Dataddo will show you step-by-step how to reauthorize your account and execute a manual data load. ### Unable to Find Facebook Sub-Accounts If your access rights have changed or you gained access to a new Facebook account, it's possible that your other accounts will not be immediately listed in Dataddo. To fix this, try the following steps: **Fully Reauthorize the Service** 1. Go to the [Authorizers](https://app.dataddo.com/authorizers) tab in Dataddo and delete the Facebook ***authorizer***. Deleting an Authorizer Please keep in mind that you will first need to **delete all sources created with the *authorizer***. This will also affect your ***flows***. You can also temporarily switch the ***source*** using the authorizer to a different account before deletion. 2. Go to your Facebook settings and navigate to the [Business integrations](https://www.facebook.com/settings?tab=business_tools&ref=settings) tab. 3. Find Dataddo and click on **Remove**. 4. Now, go back to the Authorizers tab in Dataddo and [authorize](https://app.dataddo.com/service/new) your Facebook account again. **Check Your Account Permissions** If the method above doesn't work, please check your Facebook account's permissions. To access insights, make sure the permissions are **at least on the analyst/admin level**. ### Metric and Ad Recall Data Don't Match The **Reach** and **Recall** metrics cannot be summed to get the totals for longer time periods. As these metrics measure the **daily unique users** who view your ad (= reach) or will remember the ad (=ad recall), it is **not possible to get data for a specific time period and/or aggregate the data**. To avoid this, you can 1. Get **daily** breakdowns: The daily values will match, but not when summed up over a longer time period. 2. Extract data **weekly or monthly**: These weekly/monthly values will match. Simply create a **new source** and a **new flow** with the particular breakdown (for example, a source and a flow with daily breakdowns/synchronizations). Read more about the metrics, and why the data may not be matching [here](https://blog.dataddo.com/why-the-numbers-in-your-bi-tool-dont-always-match-your-source-data?_gl=1*ipsbl8*_ga*MjAwMjE2NTU4NC4xNjUxNzM0NTI4*_ga_NQ4TN4KP4V*MTY1MTc2NzQwMC40LjEuMTY1MTc2Nzg4OS4z). ### Show Image Asset URL as an Image To have **Image Asset URLs** show as images in your destination, configure **Advanced Settings** during ***data source*** creation: 1. For the **Breakdown**, select **Image Asset**. - This breakdown adds the following fields to your table: `Image Asset ID`, `Image Asset Hash`, `Image Asset Name`, and `Image Asset URL`. 2. In your destination (e.g. [Looker Studio](/docs/looker-studio)), change the **URL type** of the `Image Asset URL` field to **image** . ## Related Articles Now that you have successfully created a ***data source***, see how you can connect your data to a dashboarding app or a data storage. **Sending Data to Dashboarding Apps** - [Simple Data Integration to Dashboards](https://docs.dataddo.com/docs/simple-data-integration-to-dashboards) - [Data Backfilling to Dashboarding Apps](https://docs.dataddo.com/docs/data-backfilling-to-dashboarding-apps) **Sending Data to Data Storages** - [Batch Ingestion to Data Warehouses](https://docs.dataddo.com/docs/ingestion-to-data-warehouses) - [Data Backfilling to Storages](https://docs.dataddo.com/docs/data-backfilling-to-storages) **Other Resources** - [Troubleshooting](https://docs.dataddo.com/docs/troubleshooting) - [Extraction Logs](https://docs.dataddo.com/docs/extraction-logs) - [Data Duplication](https://docs.dataddo.com/docs/data-duplication)