This integration is powered by Singer's Facebook Ads tap and certified by Stitch. Check out and contribute to the repo on GitHub.
For support, contact Stitch support.
Facebook Ads integration summary
Stitch’s Facebook Ads integration replicates ad, campaign, and adcreative data using the Facebook Marketing API.
Note: This integration does not currently support replicating data for reviews, pages, etc.
Refer to the Schema section for a list of objects available for replication.
Facebook Ads feature snapshot
A high-level look at Stitch's Facebook Ads integration, including release status, useful links, and the features supported in Stitch.
| STITCH | |||
| Release Status |
Released |
Supported By | |
| Stitch Plan |
Free |
Singer GitHub Repository | |
| DATA SELECTION | |||
| Table Selection |
Supported |
Column Selection |
Supported |
| REPLICATION SETTINGS | |||
| Anchor Scheduling |
Supported |
Advanced Scheduling |
Unsupported |
| Table-level Reset |
Unsupported |
Configurable Replication Methods |
Unsupported |
| TRANSPARENCY | |||
| Extraction Logs |
Supported |
Loading Reports |
Supported |
Connecting Facebook Ads
Facebook Ads setup requirements
To set up Facebook Ads in Stitch, you need:
-
Verify your access in Facebook Ads. If the user who creates the integration has restricted permissions - meaning the user doesn’t have access to all campaigns or ads - Stitch may encounter issues replicating data.
Even if you only intend to sync certain pieces of data post-setup, the user completing the initial setup should still have full access.
-
Pause all ad-blocking software currently in use. Because Facebook authentication uses pop ups, you may encounter issues if ad blockers aren’t disabled during the setup.
Step 1: Add Facebook Ads as a Stitch data source
- Sign into your Stitch account.
-
On the Stitch Dashboard page, click the Add Integration button.
-
Click the Facebook Ads icon.
-
Enter a name for the integration. This is the name that will display on the Stitch Dashboard for the integration; it’ll also be used to create the schema in your destination.
For example, the name “Stitch Facebook Ads” would create a schema called
stitch_facebook_adsin the destination. Note: Schema names cannot be changed after you save the integration.
Step 1.1: Select an attribution window
An attribution window is the amount of time for attributing results to ads and the lookback period after those actions occur during which ad results are counted.
We recommend selecting the same attribution window you use in Facebook Ads to prevent discrepancies between Facebook’s UI and data replicated by Stitch. For example: If the attribution window in Facebook Ads is 7 days, you should define this setting as 7 days.
Then, during every replication job, Stitch will replicate the past seven days’ worth of data to account for result attribution. This will ensure that records updated during the attribution period are correctly captured by Stitch.
For more info, see the Attribution windows and data extraction section.
What if clicks and views have different windows in Facebook Ads?
In this case, you should select the greater of the two. For example: If clicks have a window of 7 days and views have a window of 1 day, you should select 7 days as the setting in Stitch. This will ensure that the values for clicks and views are correctly updated.
Step 1.2: Include deleted data
Check the Include data from deleted campaigns, ads, and adsets box to have Stitch replicate data for these deleted objects.
Note: Data for deleted campaigns, ads, and adsets will be included only in Core Object tables.
Step 2: Define the historical sync
The Sync Historical Data setting will define the starting date for your Facebook Ads integration. This means that:
- For tables using Incremental Replication, data equal to or newer than this date will be replicated to your data warehouse.
- For tables using Full Table Replication, all data - including records that are older, equal to, or newer than this date - will be replicated to your data warehouse.
Change this setting if you want to replicate data beyond Facebook Ads’s default setting of 1 year. For a detailed look at historical replication jobs, check out the Syncing Historical SaaS Data guide.
Step 3: Create a replication schedule
In the Replication Frequency section, you’ll create the integration’s replication schedule. An integration’s replication schedule determines how often Stitch runs a replication job, and the time that job begins.
Facebook Ads integrations support the following replication scheduling methods:
To keep your row usage low, consider setting the integration to replicate less frequently. See the Understanding and Reducing Your Row Usage guide for tips on reducing your usage.
Step 4: Authorize Stitch to access Facebook Ads
-
After clicking the Authorize button, a small pop-up window will display.
You’ll be taken through a series of steps to allow Stitch to access data from your Public Profile, Facebook Ads, and related stats.
- Click Okay to advance through these steps.
-
After you’ve finished authorizing Stitch, you’ll be prompted to select the Facebook Ad Account you want to pull data from. Select the desired account by clicking the checkbox in the Connect column.
If you don’t see the profiles that you would expect to, verify your Facebook Ads permissions before reaching out to support.
- Click the Save Connections button.
After your credentials are validated, you’ll be directed back to Stitch (click the All Done button to wrap things up) and the Integration Details page will display.
Step 5: Set tables and columns to replicate
To complete the setup, you’ll need to select the tables and columns you want to replicate to your data warehouse.
Check out the Schema section to learn more about the available tables in Facebook Ads and how they replicate.
- In the list of tables that displays - or in the Tables to Replicate tab, if you skipped this step during setup - locate a table you want to replicate.
-
To track a table, click the checkbox next to the table’s name. A green checkmark means the table is set to replicate.
-
To track a column, click the checkbox next to the column’s name. A green checkmark means the column is set to replicate.
- Repeat this process for all the tables and columns you want to replicate.
- When finished, click the Finalize Your Selections button at the bottom of the screen to save your selections.
Note: If you change these settings while a replication job is still in progress, they will not be used until the next job starts.
Initial and historical replication jobs
After you finish setting up Facebook Ads, its Sync Status may show as Pending on either the Stitch Dashboard or in the Integration Details page.
For a new integration, a Pending status indicates that Stitch is in the process of scheduling the initial replication job for the integration. This may take some time to complete.
Initial replication jobs with Anchor Scheduling
If using Anchor Scheduling, an initial replication job may not kick off immediately. This depends on the selected Replication Frequency and Anchor Time. Refer to the Anchor Scheduling documentation for more information.
Free historical data loads
The first seven days of replication, beginning when data is first replicated, are free. Rows replicated from the new integration during this time won’t count towards your quota. Stitch offers this as a way of testing new integrations, measuring usage, and ensuring historical data volumes don’t quickly consume your quota.
Facebook Ads Replication
Attribution windows and data extraction
When Stitch runs a replication job for Facebook Ads, it will use the value of the Attribution Window setting to query for and extract data for Incremental tables. An attribution window is a period of time for attributing results to ads and the lookback period after those actions occur during which ad results are counted.
For example: If set to 7 days, Stitch will replicate the past seven days’ worth of data every time a replication job runs. While Stitch replicates data in this way to account for updates to records made during the attribution window, it can have a substantial impact on your overall row usage.
In the sections below are examples of how attribution windows impact how Stitch extracts data during historical and ongoing replication jobs.
For historical and full re-replications of Facebook Ads data, Stitch will query for and extract data newer than or equal to the date defined in the Start Date field in the Integration Settings page.
The Start Date, in conjunction with the Attribution Window, will define the minimum date Stitch should query for when extracting historical data. This is calculated as:
Start Date - Attribution Window = Minimum Extraction Date
Example
During the initial set up, the Attribution Window and Start Date settings are defined as:
- Attribution Window: 28 days (default setting)
- Start Date:
07/03/2017, or2017-07-03 00:00:00
To account for the Attribution Window, Stitch would calculate the Minimum Extraction Date value as: 2017-07-03 00:00:00 - 28 days = 2017-06-05 00:00:00
If you were to write a SQL query using this date for the ads table, it might look like this:
SELECT *
FROM facebook_ads.ads
WHERE updated_time >= '2017-06-05 00:00:00' /* Min. Extraction Date */
ORDER BY updated_time
For ongoing replication jobs, Stitch will query for and extract data using the last saved maximum value in the table’s Replication Key column and the Attribution Window setting.
Note: This applies to every replication job that takes place after the historical replication job.
Example
The last maximum saved Replication Key value for the ads table is 2017-10-01 00:00:00.
To account for the Attribution Window of 28 days, we’d subtract this from the last maximum saved Replication Key value:
2017-10-01 00:00:00 - 28 days = 2017-09-03 00:00:00
In this case, Stitch would query for and extract data that is newer than or equal to 2017-09-03 00:00:00 and older than or equal to 2017-10-01 00:00:00.
If this were a SQL query, it might look like this:
SELECT *
FROM ads
WHERE updated_time >= '2017-09-03 00:00:00'
/* max Replication Key value - Attribution Window */
AND updated_time <= '2017-10-01 00:00:00'
/* max Replication Key value from previous job */
ORDER BY updated_time
Attribution windows and row count impact
Due to the attribution window, a high Replication Frequency may not be necessary. Because Stitch will replicate data from the past N days during every replication job, recent data will be re-replicated and count towards your row quota.
To reduce your row usage and replicating redundant data, consider setting the integration to replicate less frequently. For example: every 12 or 24 hours.
Facebook Ads table schemas
There are two types of tables in Stitch’s Facebook Ads integration: Core Object and Insights.
- Core Object tables contain foundational data that’s useful for analysis. These are the
adcreative,ads,adsets, andcampaignstables. To learn more about how Facebook Ads data is structured, we recommend checking out their API guide. - Insights tables contain performance data for every campaign/adset/ad combination, segmented by day and demographics specific to each table. For example: The
ads_insights_age_and_gendertable is segmented by day, age, and gender.
Table and column names in your destination
Depending on your destination, table and column names may not appear as they are outlined below.
For example: Object names are lowercased in Redshift (CusTomERs > customers), while case is maintained in PostgreSQL destinations (CusTomERs > CusTomERs). Refer to the Loading Guide for your destination for more info.
adcreative
| Replication Method : |
Full Table |
Primary Key  :
|
id |
| API endpoint : | |||
The adcreative table contains info about the creatives used in ads in your Facebook Ads account.
This is a Core Object table.
|
id
The ID of the creative. Reference: |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
body
The body of the ad. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
image_url
The URL for the image for the creative. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
account_id
The ID of the account associated with the creative. Reference: |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
actor_id
The actor ID (page ID) of the creative. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
adLabels
Details about the ad labels applied to the creative. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
applink_treatment
The deep link fallback behavior for dynamic product ads if the app is not installed. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
branded_content_sponsor_page_id
The sponsor page ID of the creative. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
call_to_action_type
The call to action button text and header text of legacy ads. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
effective_instagram_story_id
The ID of the Instagram post used in the ad. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
effective_object_story_id
The ID of the page post used in an ad. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
title
The title for an ad link. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
name
The name of the creative in the creative library. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
image_crops
Details about the crop specifications (aspect ratios) for images in different ad placements.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
instagram_actor_id
The Instagram actor ID associated with the creative. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
instagram_permalink_url
The Instagram permalink associated with the creative. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
instagram_story_id
The ID of the Instagram post for creating ads. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
link_og_id
The Open Graph (OG) ID for the link in the creative if the landing page has OG tags. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
object_id
The ID of the promoted object or object that is relevant to the ad and ad type. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
object_story_id
The ID of the page post that is used in the creative. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
object_story_spec
Details about the specifications of a creative that are used to create a new unpublished page post.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
object_type
The type of object being advertised. Possible values are:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
object_url
The destination URL for link ads not connected to a page. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
product_set_id
The ID of the product set for the creative. Reference: |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
status
The status of the creative. Possible values are |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
template_url
The tracking URL for dynamic product ads. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
template_url_spec
Details about the template link specifications used to create ad creatives.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
thumbnail_url
The URL to a thumbnail used for the creative. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
image_hash
The image has for an image used in the creative. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
url_tags
The query string parameters which will replace or be appended to URLs clicked from page post ads, messages of the post, and canvas app install creatives. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
video_id
The ID of the video in the creative. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
link_url
Used to identify a specific landing tab on the page by the page’s tab URL. |
| Replication Method : |
Key-based Incremental |
Replication Key  :
|
updated_time |
|
Primary Key :
|
id : updated_time |
API endpoint : |
The ads table contains info about the ads in your Facebook Ads account.
This is a Core Object table.
updated_time and querying
Because this table uses updated_time as part of the Primary Key, query results might return various versions of the same adgroup.
To reflect the latest state of the adgroup, use the latest updated_time timestamp.
Deleted ads
If the Include data from deleted campaigns, ads, and adsets box in the integration’s settings is checked, this table will include data for deleted ads.
|
id
The ad ID. Reference: |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
updated_time
The last time the ad was updated. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
account_id
The ID of the ad account that the ad belongs to. Reference: |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
campaign_id
The ID of the ad campaign that contains this ad. Reference: |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
adset_id
The ID of the ad set that contains this ad. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
adLabels
Details about the ad labels applied to the ad.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
bid_type
The bid type of the ad. According to Facebook’s documentation, possible values include:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
bid_amount
The bid amount for the ad that will be used in auction instead of the ad set |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
bid_info
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
status
The configured status of the ad. Possible values include:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
creative
Details about the creative used by the ad.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
created_time
The time the ad was created. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
name
The name of the ad. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
effective_status
The effective status of the ad. According to Facebook’s documentation, possible values include:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
targeting
Details about the targeting specs applied to the ad.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
targeting
Targeting specs are ad set attributes that define who sees an ad. Stitch may create subtables named If you have many targeting specs applied to ads, a large number of subtables may be created in your destination.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
last_updated_by_app_id
The ID of the app that last updated the ad. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
recommendations
Details about the recommendations for the ad, if there are any.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
tracking_specs
Tracking specs are actions taken by people interacting with the ad. Note: tracking specs only track - they don’t optimize or charge based on that action occurring.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
conversion_specs
Conversion specs allow Facebook to surface the ad to users most likely to perform a desired decision. For example: adding to a shopping cart, viewing a particular page, or completing a form.
|
ads_insights
| Replication Method : |
Key-based Incremental |
Replication Key :
|
date_start |
|
Primary Key :
|
ad_id : adset_id : campaign_id : date_start |
Official docs : |
The ads_insights table contains entries for each campaign/set/ad combination for each day, along with detailed statistics.
Note: Data for deleted ads, adsets, and campaigns will not appear in this table even if the Include data from deleted campaigns, ads, and adsets option in the integration’s settings is enabled.
Segmented insights data
To analyze data that’s been segmented by various characteristics, consider tracking some of the other ads_insights tables in this integration. The following tables contain the same fields as this one (ads_insights), but include additional dimensions to segment the data:
ads_insights_age_and_gender- Data segmented by age and genderads_insights_country- Data segmented by countryads_insights_platform_and_device- Data segmented by platform and deviceads_insights_region- Data segmented by region
|
ad_id
The ID of the ad. Reference: |
||||
|
adset_id
The ID of the ad set. An ad set is a group of ads that share the same budget, schedule, delivery optimization, and targeting. Reference: |
||||
|
campaign_id
The ID of the campaign. Campaigns contain ad sets and ads. Reference: |
||||
|
date_start
The start date. |
||||
|
date_stop
The end date. |
||||
|
ad_name
The name of the ad. |
||||
|
adset_name
The name of the adset. |
||||
|
campaign_name
The name of the campaign. |
||||
|
clicks
The number of clicks on your ads. |
||||
|
website_ctr
The percentage of times people saw the ad and performed a link click.
|
||||
|
unique_inline_link_click_ctr
The percentage of times people saw the ad and performed a link click. Inline click-through rate uses a fixed 1-day-click attribution window. |
||||
|
frequency
The average number of times each person saw your ad. |
||||
|
account_id
The ID number of your ad account. Reference: |
||||
|
account_name
The name of your ad account. |
||||
|
canvas_avg_view_time
The average total time, in seconds, that people spent viewing a Facebook Canvas. |
||||
|
unique_inline_link_clicks
The number of people who performed an inline link click. |
||||
|
cost_per_unique_action_type
Details about the average cost of unique actions.
|
||||
|
inline_post_engagement
The total number of actions that people take involving the ad. Inline post engagements use a fixed 1-day-click attribution window. |
||||
|
relevance_score
Details about the relevance score of the ad.
|
||||
|
inline_link_clicks
The number of clicks on links to select destinations or experiences, on or off Facebook-owned properties. Inline link clicks use a fixed 1-day-click attribution window. |
||||
|
cpc
The average cost for each click (all). |
||||
|
cost_per_unique_inline_link_click
The average cost of each unique inline link click. |
||||
|
cpm
The average cost for 1,000 impressions. |
||||
|
cost_per_inline_post_engagement
The average cost of each inline post engagement. |
||||
|
inline_link_click_ctr
The percentage of time people saw your ads and performed an inline link click. |
||||
|
cpp
The average cost to reach 1,000 people. |
||||
|
cost_per_action_type
Details about the average cost of a relevant action.
|
||||
|
unique_link_clicks_ctr
The percentage of people who saw the ad and performed a link click. |
||||
|
spend
The estimated total amount of money spent on the campaign, ad set, or ad during its schedule. |
||||
|
cost_per_unique_click
The average cost of each unique click (all). |
||||
|
unique_clicks
The number of people who performed a click (all). |
||||
|
social_spend
The total amount spent so far for the ad showed with social information. Ex: |
||||
|
reach
The number of people who saw the ad at least once.
|
||||
|
canvas_avg_view_percent
The average percentage of the Facebook Canvas that people saw. |
||||
|
objective
The objective selected for the campaign. This reflects the goal you want to achieve with your advertising. |
||||
|
impressions
The number of times the ad was on screen. |
||||
|
unique_ctr
The percentage of people who saw your ad and performed a unique click (all). |
||||
|
cost_per_inline_link_click
The average cost of each inline link click. |
||||
|
ctr
The percentage of times people saw your ad and performed a click (all). |
ads_insights_age_and_gender
| Replication Method : |
Key-based Incremental |
Replication Key :
|
date_start |
|
Primary Key :
|
ad_id : adset_id : campaign_id : date_start : age : gender |
Official docs : |
The ads_insights_age_and_gender table contains entries for each campaign/set/ad combination for each day, along with detailed statistics, segmented by age and gender.
This table contains the same fields as the ads_insights table, with the exception of age and gender.
Note: Data for deleted ads, adsets, and campaigns will not appear in this table even if the Include data from deleted campaigns, ads, and adsets option in the integration’s settings is enabled.
|
ad_id
The ID of the ad. Reference: |
||||
|
adset_id
The ID of the ad set. An ad set is a group of ads that share the same budget, schedule, delivery optimization, and targeting. Reference: |
||||
|
campaign_id
The ID of the campaign. Campaigns contain ad sets and ads. Reference: |
||||
|
date_start
The start date. |
||||
|
age
The age by which the data is segmented. |
||||
|
gender
The gender by which the data is segmented. |
||||
|
date_stop
The end date. |
||||
|
ad_name
The name of the ad. |
||||
|
adset_name
The name of the adset. |
||||
|
campaign_name
The name of the campaign. |
||||
|
clicks
The number of clicks on your ads. |
||||
|
website_ctr
The percentage of times people saw the ad and performed a link click.
|
||||
|
unique_inline_link_click_ctr
The percentage of times people saw the ad and performed a link click. Inline click-through rate uses a fixed 1-day-click attribution window. |
||||
|
frequency
The average number of times each person saw your ad. |
||||
|
account_id
The ID number of your ad account. Reference: |
||||
|
account_name
The name of your ad account. |
||||
|
canvas_avg_view_time
The average total time, in seconds, that people spent viewing a Facebook Canvas. |
||||
|
unique_inline_link_clicks
The number of people who performed an inline link click. |
||||
|
cost_per_unique_action_type
Details about the average cost of unique actions.
|
||||
|
inline_post_engagement
The total number of actions that people take involving the ad. Inline post engagements use a fixed 1-day-click attribution window. |
||||
|
relevance_score
Details about the relevance score of the ad.
|
||||
|
inline_link_clicks
The number of clicks on links to select destinations or experiences, on or off Facebook-owned properties. Inline link clicks use a fixed 1-day-click attribution window. |
||||
|
cpc
The average cost for each click (all). |
||||
|
cost_per_unique_inline_link_click
The average cost of each unique inline link click. |
||||
|
cpm
The average cost for 1,000 impressions. |
||||
|
cost_per_inline_post_engagement
The average cost of each inline post engagement. |
||||
|
inline_link_click_ctr
The percentage of time people saw your ads and performed an inline link click. |
||||
|
cpp
The average cost to reach 1,000 people. |
||||
|
cost_per_action_type
Details about the average cost of a relevant action.
|
||||
|
unique_link_clicks_ctr
The percentage of people who saw the ad and performed a link click. |
||||
|
spend
The estimated total amount of money spent on the campaign, ad set, or ad during its schedule. |
||||
|
cost_per_unique_click
The average cost of each unique click (all). |
||||
|
unique_clicks
The number of people who performed a click (all). |
||||
|
social_spend
The total amount spent so far for the ad showed with social information. Ex: |
||||
|
reach
The number of people who saw the ad at least once.
|
||||
|
canvas_avg_view_percent
The average percentage of the Facebook Canvas that people saw. |
||||
|
objective
The objective selected for the campaign. This reflects the goal you want to achieve with your advertising. |
||||
|
impressions
The number of times the ad was on screen. |
||||
|
unique_ctr
The percentage of people who saw your ad and performed a unique click (all). |
||||
|
cost_per_inline_link_click
The average cost of each inline link click. |
||||
|
ctr
The percentage of times people saw your ad and performed a click (all). |
ads_insights_country
| Replication Method : |
Key-based Incremental |
Replication Key :
|
date_start |
|
Primary Key :
|
ad_id : adset_id : campaign_id : date_start : country |
Official docs : |
The ads_insights_country table contains entries for each campaign/set/ad combination for each day, along with detailed statistics, segmented by country.
This table contains the same fields as the ads_insights table, with the exception of country.
Note: Data for deleted ads, adsets, and campaigns will not appear in this table even if the Include data from deleted campaigns, ads, and adsets option in the integration’s settings is enabled.
|
ad_id
The ID of the ad. Reference: |
||||
|
adset_id
The ID of the ad set. An ad set is a group of ads that share the same budget, schedule, delivery optimization, and targeting. Reference: |
||||
|
campaign_id
The ID of the campaign. Campaigns contain ad sets and ads. Reference: |
||||
|
date_start
The start date of the ad. |
||||
|
country
The country by which the data is segmented. |
||||
|
date_stop
The end date of the ad. |
||||
|
ad_name
The name of the ad. |
||||
|
adset_name
The name of the adset. |
||||
|
campaign_name
The name of the campaign. |
||||
|
clicks
The number of clicks on your ads. |
||||
|
website_ctr
The percentage of times people saw the ad and performed a link click.
|
||||
|
unique_inline_link_click_ctr
The percentage of times people saw the ad and performed a link click. Inline click-through rate uses a fixed 1-day-click attribution window. |
||||
|
frequency
The average number of times each person saw your ad. |
||||
|
account_id
The ID number of your ad account. Reference: |
||||
|
account_name
The name of your ad account. |
||||
|
canvas_avg_view_time
The average total time, in seconds, that people spent viewing a Facebook Canvas. |
||||
|
unique_inline_link_clicks
The number of people who performed an inline link click. |
||||
|
cost_per_unique_action_type
Details about the average cost of unique actions.
|
||||
|
inline_post_engagement
The total number of actions that people take involving the ad. Inline post engagements use a fixed 1-day-click attribution window. |
||||
|
relevance_score
Details about the relevance score of the ad.
|
||||
|
inline_link_clicks
The number of clicks on links to select destinations or experiences, on or off Facebook-owned properties. Inline link clicks use a fixed 1-day-click attribution window. |
||||
|
cpc
The average cost for each click (all). |
||||
|
cost_per_unique_inline_link_click
The average cost of each unique inline link click. |
||||
|
cpm
The average cost for 1,000 impressions. |
||||
|
cost_per_inline_post_engagement
The average cost of each inline post engagement. |
||||
|
inline_link_click_ctr
The percentage of time people saw your ads and performed an inline link click. |
||||
|
cpp
The average cost to reach 1,000 people. |
||||
|
cost_per_action_type
Details about the average cost of a relevant action.
|
||||
|
unique_link_clicks_ctr
The percentage of people who saw the ad and performed a link click. |
||||
|
spend
The estimated total amount of money spent on the campaign, ad set, or ad during its schedule. |
||||
|
cost_per_unique_click
The average cost of each unique click (all). |
||||
|
unique_clicks
The number of people who performed a click (all). |
||||
|
social_spend
The total amount spent so far for the ad showed with social information. Ex: |
||||
|
reach
The number of people who saw the ad at least once.
|
||||
|
canvas_avg_view_percent
The average percentage of the Facebook Canvas that people saw. |
||||
|
objective
The objective selected for the campaign. This reflects the goal you want to achieve with your advertising. |
||||
|
impressions
The number of times the ad was on screen. |
||||
|
unique_ctr
The percentage of people who saw your ad and performed a unique click (all). |
||||
|
cost_per_inline_link_click
The average cost of each inline link click. |
||||
|
ctr
The percentage of times people saw your ad and performed a click (all). |
ads_insights_platform_and_device
| Replication Method : |
Key-based Incremental |
Replication Key :
|
date_start |
|
Primary Key :
|
ad_id : adset_id : campaign_id : date_start : publisher_platform : platform_position : impression_device |
Official docs : |
The ads_insights_country table contains entries for each campaign/set/ad combination for each day, along with detailed statistics, segmented by publisher platform, platform position, and device.
This table contains the same fields as the ads_insights table, with the exception of the following fields:
publisher_platformplatform_positionimpression_device
Note: Data for deleted ads, adsets, and campaigns will not appear in this table even if the Include data from deleted campaigns, ads, and adsets option in the integration’s settings is enabled.
|
ad_id
The ID of the ad. Reference: |
||||
|
adset_id
The ID of the ad set. An ad set is a group of ads that share the same budget, schedule, delivery optimization, and targeting. Reference: |
||||
|
campaign_id
The ID of the campaign. Campaigns contain ad sets and ads. Reference: |
||||
|
date_start
The start date of the ad. |
||||
|
publisher_platform
The publishing platform by which the data is segmented. Ex: |
||||
|
platform_position
The platform position by which the data is segmented. |
||||
|
impression_device
The type of device by which the data is segmented. |
||||
|
date_stop
The end date of the ad. |
||||
|
ad_name
The name of the ad. |
||||
|
adset_name
The name of the adset. |
||||
|
campaign_name
The name of the campaign. |
||||
|
clicks
The number of clicks on your ads. |
||||
|
website_ctr
The percentage of times people saw the ad and performed a link click.
|
||||
|
unique_inline_link_click_ctr
The percentage of times people saw the ad and performed a link click. Inline click-through rate uses a fixed 1-day-click attribution window. |
||||
|
frequency
The average number of times each person saw your ad. |
||||
|
account_id
The ID number of your ad account. Reference: |
||||
|
account_name
The name of your ad account. |
||||
|
canvas_avg_view_time
The average total time, in seconds, that people spent viewing a Facebook Canvas. |
||||
|
unique_inline_link_clicks
The number of people who performed an inline link click. |
||||
|
cost_per_unique_action_type
Details about the average cost of unique actions.
|
||||
|
inline_post_engagement
The total number of actions that people take involving the ad. Inline post engagements use a fixed 1-day-click attribution window. |
||||
|
relevance_score
Details about the relevance score of the ad.
|
||||
|
inline_link_clicks
The number of clicks on links to select destinations or experiences, on or off Facebook-owned properties. Inline link clicks use a fixed 1-day-click attribution window. |
||||
|
cpc
The average cost for each click (all). |
||||
|
cost_per_unique_inline_link_click
The average cost of each unique inline link click. |
||||
|
cpm
The average cost for 1,000 impressions. |
||||
|
cost_per_inline_post_engagement
The average cost of each inline post engagement. |
||||
|
inline_link_click_ctr
The percentage of time people saw your ads and performed an inline link click. |
||||
|
cpp
The average cost to reach 1,000 people. |
||||
|
cost_per_action_type
Details about the average cost of a relevant action.
|
||||
|
unique_link_clicks_ctr
The percentage of people who saw the ad and performed a link click. |
||||
|
spend
The estimated total amount of money spent on the campaign, ad set, or ad during its schedule. |
||||
|
cost_per_unique_click
The average cost of each unique click (all). |
||||
|
unique_clicks
The number of people who performed a click (all). |
||||
|
social_spend
The total amount spent so far for the ad showed with social information. Ex: |
||||
|
reach
The number of people who saw the ad at least once.
|
||||
|
canvas_avg_view_percent
The average percentage of the Facebook Canvas that people saw. |
||||
|
objective
The objective selected for the campaign. This reflects the goal you want to achieve with your advertising. |
||||
|
impressions
The number of times the ad was on screen. |
||||
|
unique_ctr
The percentage of people who saw your ad and performed a unique click (all). |
||||
|
cost_per_inline_link_click
The average cost of each inline link click. |
||||
|
ctr
The percentage of times people saw your ad and performed a click (all). |
ads_insights_region
| Replication Method : |
Key-based Incremental |
Replication Key :
|
date_start |
|
Primary Key :
|
ad_id : adset_id : campaign_id : date_start : region |
Official docs : |
The ads_insights_region table contains entries for each campaign/set/ad combination for each day, along with detailed statistics, segmented by region. This table enables you to view your data by the region (ex: state or province) where people live or were located when they saw your ads, depending on how the location targeting was set.
This table contains the same fields as the ads_insights table, with the exception of region.
Note: Data for deleted ads, adsets, and campaigns will not appear in this table even if the Include data from deleted campaigns, ads, and adsets option in the integration’s settings is enabled.
|
ad_id
The ID of the ad. Reference: |
||||
|
adset_id
The ID of the ad set. An ad set is a group of ads that share the same budget, schedule, delivery optimization, and targeting. Reference: |
||||
|
campaign_id
The ID of the campaign. Campaigns contain ad sets and ads. Reference: |
||||
|
date_start
The start date of the ad. |
||||
|
region
The region by which the data is segmented. |
||||
|
date_stop
The end date of the ad. |
||||
|
ad_name
The name of the ad. |
||||
|
adset_name
The name of the adset. |
||||
|
campaign_name
The name of the campaign. |
||||
|
clicks
The number of clicks on your ads. |
||||
|
website_ctr
The percentage of times people saw the ad and performed a link click.
|
||||
|
unique_inline_link_click_ctr
The percentage of times people saw the ad and performed a link click. Inline click-through rate uses a fixed 1-day-click attribution window. |
||||
|
frequency
The average number of times each person saw your ad. |
||||
|
account_id
The ID number of your ad account. Reference: |
||||
|
account_name
The name of your ad account. |
||||
|
canvas_avg_view_time
The average total time, in seconds, that people spent viewing a Facebook Canvas. |
||||
|
unique_inline_link_clicks
The number of people who performed an inline link click. |
||||
|
cost_per_unique_action_type
Details about the average cost of unique actions.
|
||||
|
inline_post_engagement
The total number of actions that people take involving the ad. Inline post engagements use a fixed 1-day-click attribution window. |
||||
|
relevance_score
Details about the relevance score of the ad.
|
||||
|
inline_link_clicks
The number of clicks on links to select destinations or experiences, on or off Facebook-owned properties. Inline link clicks use a fixed 1-day-click attribution window. |
||||
|
cpc
The average cost for each click (all). |
||||
|
cost_per_unique_inline_link_click
The average cost of each unique inline link click. |
||||
|
cpm
The average cost for 1,000 impressions. |
||||
|
cost_per_inline_post_engagement
The average cost of each inline post engagement. |
||||
|
inline_link_click_ctr
The percentage of time people saw your ads and performed an inline link click. |
||||
|
cpp
The average cost to reach 1,000 people. |
||||
|
cost_per_action_type
Details about the average cost of a relevant action.
|
||||
|
unique_link_clicks_ctr
The percentage of people who saw the ad and performed a link click. |
||||
|
spend
The estimated total amount of money spent on the campaign, ad set, or ad during its schedule. |
||||
|
cost_per_unique_click
The average cost of each unique click (all). |
||||
|
unique_clicks
The number of people who performed a click (all). |
||||
|
social_spend
The total amount spent so far for the ad showed with social information. Ex: |
||||
|
reach
The number of people who saw the ad at least once.
|
||||
|
canvas_avg_view_percent
The average percentage of the Facebook Canvas that people saw. |
||||
|
objective
The objective selected for the campaign. This reflects the goal you want to achieve with your advertising. |
||||
|
impressions
The number of times the ad was on screen. |
||||
|
unique_ctr
The percentage of people who saw your ad and performed a unique click (all). |
||||
|
cost_per_inline_link_click
The average cost of each inline link click. |
||||
|
ctr
The percentage of times people saw your ad and performed a click (all). |
adsets
| Replication Method : |
Key-based Incremental |
Replication Key :
|
updated_time |
|
Primary Key :
|
id : updated_time |
API endpoint : |
The adsets table contains info about the Ad Sets in your Facebook Ads account.
This is a Core Object table.
updated_time and querying
Because this table uses updated_time as part of the Primary Key, query results might return various versions of the same adgroup.
To reflect the latest state of the adgroup, use the latest updated_time timestamp.
Deleted adsets
If the Include data from deleted campaigns, ads, and adsets box in the integration’s settings is checked, this table will include data for deleted adsets.
|
id
The ID of the ad set. Reference: |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
updated_time
The last time the ad set was updated. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
name
The name of the ad set. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
end_time
The end time of the ad set. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
promoted_object
Details about the object an ad set promotes, such as a Page or app.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
account_id
The ad account ID. Reference: |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
daily_budget
The daily budget of the ad set. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
budget_remaining
The remaining budget of the ad set. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
effective_status
The effective status of the ad set. According to Facebook’s documentation, possible values include:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
campaign_id
The ID of the campaign containing this ad set. Reference: |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
created_time
The time the ad set was created. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
start_time
The start time of the ad set. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
lifetime_budget
The lifetime budget of the ad set. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
targeting
Targeting specs are ad set attributes that define who sees an ad. Stitch may create subtables named If you have many targeting specs applied to ads, a large number of subtables may be created in your destination.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
bid_info
Details about the bid information for this ad set.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
adLabels
Details about the ad labels applied to the ad set.
|
campaigns
| Replication Method : |
Key-based Incremental |
Replication Key :
|
updated_time |
|
Primary Key :
|
id |
API endpoint : |
The campaigns table contains info about the campaigns in your Facebook Ads account. Facebook defines campaigns as “a grouping of ad sets organized by the same business objective.”
This is a Core Object table.
Deleted campaigns
If the Include data from deleted campaigns, ads, and adsets box in the integration’s settings is checked, this table will include data for deleted campaigns.
|
id
The campaign ID. Reference: |
|
|
updated_time
The last time the campaign was updated. |
|
|
name
The name of the campaign. |
|
|
objective
The objective of the campaign. |
|
|
account_id
The ID of the ad account that owns the campaign. Reference: |
|
|
effective_status
The effective status of the campaign. According to Facebook’s documentation, possible values include:
|
|
|
buying_type
The campaign buying type. Possible values are:
|
|
|
spend_cap
The spend cap for the campaign. |
|
|
start_time
The campaign’s start time. |
|
|
end_time
The campaign’s end time. |
|
|
ads
The IDs of the ads associated with the campaign.
|
| Related | Troubleshooting |
Questions? Feedback?
Did this article help? If you have questions or feedback, feel free to submit a pull request with your suggestions, open an issue on GitHub, or reach out to us.