Collecting data from Facebook Ads

This guide explains how to collect data from Facebook Ads. To learn how to collect data from a different data source, go back to the Available data sources in Adverity overview.


For a list of the fields that you can collect from Facebook Ads, see Facebook Ads.

  • Facebook Ads can collect a maximum of 1 million rows per single report. To fetch more data than this, split your fetch into smaller date ranges in the Initial Fetch step of creating a datastream.


Before you start collecting data from Facebook Ads, perform all of the following actions:

  • Ensure that the account you use to connect to Facebook Ads has the correct roles and permissions to collect the data. Edit these roles and permissions in Facebook Business Manager. For more information, see the Facebook documentation.

  • Add the Employee or higher business manager role to the account.

  • For an ad account, add the View performance permission.

  • Add the View Page performance permission to the classic page.

Depending on your specific configuration, the following additional permissions may be required:

  • Leads Access or Manage Page: To access lead form results.

  • Manage catalogue: To obtain metadata for advertised catalog objects.

  • Manage line of business: To retrieve data specific for attribution reports.

Alternatively, if you do not use Facebook Business Manager, configure the roles and permissions on the page level. For more information, see the Facebook documentation.

Creating a datastream to collect data from Facebook Ads

The basics of creating a datastream to collect data from any data source are explained in our guide to Creating a datastream. This guide contains information about the specific steps to create a datastream to fetch data from Facebook Ads.

Authorization: Allow Adverity to access Facebook Ads

  1. If you choose Access using your credentials or Access using someone else's credentials, in Set up or edit Ad Accounts, you or the person granting access must choose one of the following options:

    • Choose Grant access to all Ad Accounts, including those created in the future to allow Adverity to access all existing Ad Accounts and all Ad Accounts created in the future.

    • Choose Select specific Ad Accounts to which you want to grant access to determine the specific Ad Accounts that you want Adverity to access. Adverity will not automatically have access to Ad Accounts created in the future. You will need to grant Adverity access to any Ad Accounts created in the future.

    If you use your credentials to grant Adverity access to Facebook Ads, all the Ad Accounts available to you using your credentials will be visible in the Authorizations page to all Adverity users with permission to edit this authorization.

    If someone else uses their credentials to grant Adverity access to Facebook Ads, the same applies to the Ad Accounts available using their credentials.

    This is important to consider if you do not want all Adverity users with permission to edit the authorization to be able to see the details of the Ad Accounts. For more information about user permissions, see Managing user permissions.

Configuration: Choose the data you want to collect from Facebook Ads

To choose what data to collect and customize the Facebook Ads datastream configuration, follow these steps:

  1. (Optional) Rename your datastream.

  1. In Businesses, Accounts, and Campaigns, select the businesses, accounts, and campaigns for which to collect data. If you do not select any items in a drop-down list, Adverity collects data for all items in the drop-down list.

  1. In Fields, change the list of fields that you want to see in your data extract.

    The actions, action_values, and conversions fields are group fields. This means that if you select one or more of these fields, and later select the Force action fields checkbox, this datastream will fetch all fields in the selected groups, even if the column is empty.

    This could mean that your data extract will contain lots of empty columns. If you only want to keep some of these columns, you can use the cut custom script instruction to choose which columns to keep.

    Alternatively, if you know which columns you want to include in your data extract, you can use the extendmissing custom script instruction to only add these columns. You can do this instead of using the Force action fields option.

    For more information about action fields, including a list of all fields you can collect by selecting these group fields, see the Facebook Ads documentation.

For information on configuring other Facebook Ads fields, see Advanced Facebook Ads tips.

What's next?

Troubleshooting Facebook Ads

The status of a campaign, ad set or ad is not correct when fetching data from Facebook Ads

If the status of an object is incorrect, for example if an ad is inactive but its status is shown as active when fetching data for a long date range, this is because the metadata for the authorization used in this datastream is out of date.

To resolve this issue, follow the steps in Synchronizing metadata for the authorization used in this datastream.

Advanced Facebook Ads tips

Rate limiting

For information on rate limiting, see the Facebook documentation.

Configuring advanced data collection options for Facebook Ads

This section explains the advanced configuration options for your Facebook Ads datastream. You can adjust these settings in the Configuration step of the datastream creation wizard.

  1. In the General section of the page, adjust the following settings:


    Select how collected data is broken down in the data extract. For example, select age to view a breakdown of the age groups interacting with your ad campaigns.

    Action breakdowns

    Select how collected data is broken down in the data extract in terms of actions on a campaign. For example, select action_reaction to view a breakdown by the number of reactions each campaign received.


    Select the time unit in which you want to collect data. Choose one of the following options:

    • Total

    • Monthly

    • Daily

    • Custom

  2. In the Media Screenshots section of the page, adjust the following settings:

    Save media screenshots

    To take screenshots of your ads, select this checkbox and populate Ad Preview fields below.

    The screenshots are saved in the same storage as the Facebook Ads data extracts. For more information, see Setting up storage for data extracts. The screenshots are stored until you delete them manually from the storage, or delete the Facebook Ads datastream.

    Ad preview fields

    To take screenshots of your ads, select at least one field that will contain the link to the screenshot.

    (Recommended) Select ad_preview_default_url to generate a screenshot.

  3. To view advanced Facebook Ads datastream settings, click Show advanced settings and adjust the following settings:

    Use unified attribution settings

    Select this checkbox to apply the attribution settings defined at the ad set level in the Facebook administration. This allows you to apply default attribution settings to all ads within an ad set.

    If this checkbox is enabled, Adverity ignores your selection in the Action attribution windows field.

    Action attribution windows

    An attribution window is the time period between a user clicking on or viewing an ad, and performing an action (such as a purchase or download) as a result of the ad click or view. In Action attribution window, select the time period for which to collect attribution data.

    For each action selected in the Action breakdowns field, a column will be placed next to the action column in the data extract, displaying the number of actions that occurred within the selected action attribution window.

    Pivot action fields

    Select this checkbox to display action fields as rows instead of columns in the data extract. Each action is broken down by row, with the columns action_type and action_values. This setting only is only effective if you select an action in the Action breakdowns field.

    Translate custom conversions

    Select this checkbox to collect the names for custom conversions.

    Force action fields

    Select this checkbox to create a column for each possible action field for the action_type breakdown in the data extract, even if the action field is empty. By default, Facebook does not return empty values. This feature resolves destination issues where certain destinations may require a set number of columns to be loaded. For more information on action fields, see the Facebook documentation.

    Include future campaigns

    Select this checkbox to collect data on campaigns that have not run yet.

    Adset targeting fields

    Select the adset targeting fields to include in your data extract. Each selected adset targeting field will be displayed as a separate column in the data extract

    By default, the adset targeting fields are contained in a single JSON string. Adset targeting fields defines which fields from this JSON string will be included in the fetched data.

    Action report time

    Ad impressions and conversion actions can occur on different dates. A recorded action can be attributed to one of the following:

    • The date when an impression occurred.

    • Time when a conversion action occurred.

    Some actions can only be attributed to the date of a conversion, and these actions are not reported by Facebook Ads if you select Impression in the Action report time field. Adverity recommends the Mixed option because it returns data on both impressions and conversion actions.

    To specify which actions to report, select one of the following options:

    • (Default, Recommended) Select Mixed to report the following:

      • The date of an impression that occurs on your ad (for example ad-views and ad-clicks).

      • The conversion action dates that occur off your ad (for example purchases on your website).

    • Select Conversion to report all off-ad and off-Facebook action dates.

    • Select Impression (only data before May 3, 2021) to report all impression dates. This option is only supported for impression data before May 3, 2021. For more information on the discontinuation of impression collection, see the Facebook documentation.

    For more information on off-Facebook actions, see the Facebook documentation.

    Product ID limit

    Enter the maximum number of product IDs to be returned for each ad set for the product_id breakdown. For example, a carousel ad campaign may have up to five products included in the ad, each with its own product ID.

    Custom Filter

    To filter the data to collect from Facebook Ads, provide a set of filters in JSON format. For example, to find data with the ID 123, enter the following:

    [{"field": "id", "operator": "EQUAL", "value": "123"}]

    For more information on the parameters that can be filtered, see the Facebook documentation.

Obtaining the campaign results metric

The results_by_adveritymetric shows you how well a campaign performed, calculated based on campaign objectives and metrics.

To add the results_by_adveritymetric to your datastream, follow these steps:

  1. Select the workspace you work with in Adverity and then, in the platform navigation menu, click Datastreams.

  2. Open the Facebook Ads datastream by clicking on its name.

  3. In the top navigation panel, click Settings.

  4. In the Fields section, write results_by_adverity and select the value from the drop-down list.

  5. Click Save.

  6. In the top right corner, click Fetch now.

  7. Choose the time period for which data is collected.

  8. Click Fetch.

The results metric provided by Facebook cannot be fetched from the Facebook Ads connector because it is only available in the Facebook Ads user interface and cannot be retrieved using the API. Adverity calculates the results metric through a different metric called results_by_adverity. Therefore, the results metric in Facebook Ads may differ from the results_by_adverity metric in Adverity.

For more information on results, see the Facebook documentation:

List of all campaign objectives and metrics used for calculating the results_by_adveritymetric:

Campaign objective

Metric used for calculation

App installs


Brands awareness




Event responses

Lead generation


Link clicks


Local awareness




Offer claims


Page likes

Post engagement


Product catalog sales




Store visits


Video views


Facebook Ads store visits

The store visits objective allows you to create Facebook ad campaigns to increase sales at physical stores.

The store visits optimization (called store traffic as well) is currently only available to users on the Facebook allow list. Contact your Facebook representative for access. For more information, see Facebook documentation.

Video guide: How to fetch ad performance data from Facebook Ads

This video guide explains how to create and configure a datastream to collect your ad performance data from Facebook Ads.