Configure Facebook Ads as a Source in your Pipeline

Perform the following steps to configure your Facebook Ads Source:

1. Click Pipelines in the Navigation Bar.

2. Click + Create Pipeline in the Pipelines List View.

3. On the Select Source Type page, select Facebook Ads.

4. On the Select Destination Type page, select the type of Destination you want to use.

5. On the Select Pipeline Type page, click Edge, and then click Continue.

   

   Note: This page appears only if the selected Destination type is supported in Edge and your Team has an existing Facebook Ads Pipeline with the same Destination type. Otherwise, you can proceed to create an Edge Pipeline.

6. In the Configure Source screen, specify the following:

   

   • Source Name: A unique name for your Source, not exceeding 255 characters. For example, Facebook Ads Source.

   • Authentication Method: Select how you want to authenticate your Facebook Ads account:

     

     • Grant User Access: Recommended for most users. Click the Authenticate your Facebook Ads account button to connect your Facebook Ads account with Hevo. In the pop-up window, log in to your Facebook account, review the permissions Hevo requests to access your ad account data, and grant the required permissions to complete the authorization.

     • Use System User Token: Recommended for agencies managing multiple ad accounts. Paste the access token generated from your Meta Business Manager account.

   • Account Selection: From the drop-down, select whether to sync all ad accounts accessible to your authenticated account or only specific ones:

     • Sync All Accounts: Hevo syncs data for all ad accounts accessible to your authorized Facebook account, including any accounts added later.

     • Sync Specific Accounts: Select the ad accounts you want to sync from the Accounts to sync drop-down for which you want to ingest the data.

   • Historical Sync Duration: The duration for which you want to ingest existing data from the Source. This cannot be changed after the Pipeline is created. Default value: 3 Months.

   • Sync Metadata: Syncs metadata objects, such as Ads, Ad Sets, Campaigns, and their related objects, in addition to Ads Insights data. This option is enabled by default.

   • Custom Reports: Hevo allows you to create your own reports by choosing relevant report fields. Each report syncs to its own Destination table. For each report, specify the following:

     

     • Report Name: Specify a unique name for the Destination table where Hevo loads the data for this report.

     • Aggregation: Determines how data is grouped by time in the report. Default value: Day.

     • Fields: The metrics and dimensions to include in the report. At least one field is required.

     • Breakdowns (Optional): Categories used to group your report data, such as age, gender, country, region, or platform.

     • Action Breakdowns (Optional): Categories used to group action and conversion metrics by attributes such as action type, device, or destination.

     • Show Advanced Options: Enable this toggle to specify the following attribution settings:

       • Action Report Time: Determines when actions and conversions are counted in the report. Default value: impression.

       • Click Attribution Window: The number of days between a person clicking your ad and taking an action, such as an install or subscribe. Default value: 7 days.

       • View Attribution Window: The number of days between a person clicking your ad and taking an action, such as an install or subscribe. Default value: 7 days.

       • Engaged-view Attribution Window: The number of days between a person having an engaged view of your ad and taking an action. Default value: None.

       • Use unified attribution setting: When enabled, results use the unified attribution settings defined at the ad set level rather than account-level settings. Default value: disabled.

     Note:

     • Click Save after configuring each report. Reports that are not saved before you click Test & Continue are not included in the Pipeline.

     • If you add a new report or edit an existing one, trigger a manual resync of its Destination table to apply the changes and load the data using the updated configuration.

7. Click Test & Continue to test the connection to your Facebook Ads Source.

   Note: If any custom report is configured incorrectly, such as with an unsupported field and breakdown combination, an invalid aggregation, or a duplicate table name, clicking Test & Continue fails the Source configuration. Hevo lists all configuration issues in your custom reports. You can fix these issues by editing the reports before retrying.

---

Data Replication

Hevo replicates data for all the objects selected on the Configure Objects page during Pipeline creation. By default, all supported objects and their available fields are selected. However, you can modify this selection while creating or editing the Pipeline.

Selecting a parent object automatically includes all its associated child objects for replication. Child objects cannot be selected or deselected individually.

Hevo ingests the following types of data from your Source objects:

• Historical Data: The first run of the Pipeline ingests all available historical data for the selected objects and loads it into the Destination.

• Incremental Data: Once the historical load is complete, new and updated records for objects are ingested as per the sync frequency.

For the following objects, Hevo ingests only the incremental data in subsequent Pipeline runs using the updated_time field.

• Ad

• Ad Set

• Ad Label

• Campaign

• Custom Audience

For all other objects, Hevo ingests the entire data during each Pipeline run.

Facebook Ads currently enforces rate limits at the ad account level. If this limit is exceeded, a rate limit exception occurs. To understand how Hevo handles such scenarios, read Handling Rate Limit Exceptions.

Note: You can create a Pipeline with this Source only using the Merge load mode. The Append mode is not supported for this Source.

---

Schema and Primary Keys

Hevo uses the following schema to upload the records to the Destination. For a detailed view of the objects, fields, and relationships, click the ERD.

---

Data Model

The following is the list of tables (objects) that are created at the Destination when you run the Pipeline:

• Metadata Objects

• Ads Insights Reports

Metadata Objects

Hevo ingests the following entity metadata objects in addition to the Ads Insights Reports, when the Sync Metadata option is enabled:

Ads Insights Reports

Hevo ingests the following Ads Insights reporting objects, each showing ad performance metrics grouped by a different breakdown. All the objects use the same Facebook Marketing API Ads Insights endpoint, with the selected breakdown determining the data returned.

---