App Connectors: Facebook Ads

👤 This documentation is intended for Site Administrators and/or Database Administrators.

Connectors are Periscope Data’s built-in mechanisms for customers to connect to and ingest from popular data sources.

Note: Connectors are supported for customers with Data Engine on your Warehouse or Warehouse infrastructure. Site administrators can contact their Account Manager if interested in enabling Connectors.

<div>
<UL>
<LI><a href="#PreparingaConnector">Preparing to add a Connector</a></LI>
<LI><a href="#AddingaConnector">Adding a Connector</a></LI>
<LI><a href="#SetUpIngestion">Set Up Ingestion</a></LI>
<UL>
<LI><a href="#SetupDatabasePermissions">Setup Database Permissions</a></LI>
<LI><a href="#HowToSetUpIngestion">How To Set Up Ingestion</a></LI>
<LI><a href="#SelectAnAttributionWindow">Select an Attribution Window</a></LI>
<LI><a href="#ReauthorizeaConnector">Reauthorize a Connector</a></LI>
<LI><a href="#SuspendIngestionforaConnector">Suspend Ingestion for a Connector</a></LI>
</UL>
<LI><a href="#DeleteaConnector">Delete a Connector</a></LI>
<LI><a href="#SupportedConnectors">Supported Connectors</a></LI>
<LI><a href="#FacebookAdsSchemas">Facebook Ads Schemas</a></LI>
</UL>
</div>
<HR>

<a name="PreparingaConnector"></a>

Preparing to add a Connector

To connect to Facebook Ads account please make sure to have the following prior to attempting a connection:

  1. A Facebook user account that has access to all ads and campaign data in the account you wish to connect. Even if you only intend to ingest a portion of the data, the user should still have full access.
  2. Please disable any ad-blocking software during initial setup. Facebook Authentication uses pop-ups, and ad-blocking software could interfere with this process.

<a name="AddingaConnector"></a>

<a href="#top">Back to top</a>

Adding a Connector

To add a Connector, administrators can first click Settings menu in the bottom left hand corner.

Then, click the App Connections option:

In the top right corner, click the green Connect Source button.


From the Data Source Type dropdown, select the 'Facebook Ads' option:

Enter the display name for the Connector in the Display Name section of the Connect Source menu, then enter the Facebook Ads account ID for the ad account you wish to ingest from. Click here for information on where to find this.

Select your Attribution window and whether or not you would like to include deleted data, then click “Add”. A second window will open to Facebook’s login page. Enter the credentials for the user that is associated with the FacebookAds account you want to ingest from.

Note: If you have applied 2 factor authentication to your Facebook Account, you will be prompted to complete the 2nd authentication step BEFORE you see these screens. Once the 2nd authentication step is complete, you will see the prompts below.

Select the option to “Continue as” the user you logged into Facebook with.


Ensure that “Access your Facebook ads and related stats” is set to “Yes” on the next screen. Click “Done”

The next screen will confirm that you have successfully linked Periscope Data to the Facebook account. Click “OK”.


A screen will appear directing with information on how to navigate back to Periscope Data.  Either select “closing” to redirect back to the Connectors page, or wait as the window will automatically close in 5 seconds and redirect to the Connectors page.


The process of establishing a new connection will take a few minutes as all of the tables that are associated with that source are being discovered. During this time a spinning Periscope Data icon will appear.


Available tables from the connected data source will appear as they become available.

In the event that the connection was unsuccessful, a Connection failed screen will appear. Please verify that the Facebook Ads account is correct and that the Facebook user account selected for permissioning has full access to ads and campaign data.

<a name="SetUpIngestion"></a>

<a href="#top">Back to top</a>

Setup Ingestion

There are no specific table permissions that need to be set for Facebook Ads.

<a name="SetUpDatabasePermissions"></a>

Setup Database Permissions

In order to ingest data into Periscope, certain database permissions will need to be updated the first time a connector is added.

Periscope Warehouse:

Periscope will create a new database user and grant the necessary permissions to load data into your warehouse from your connected Sources. Periscope will also grant the Read User the necessary schema permissions so you can query your Sources' data from within Periscope.

Data Engine on Your Warehouse:

In order to ingest data into your Redshift or Snowflake warehouse using Periscope App Connectors, Periscope requires a database user that can perform write operations on your database. Create permissions are required to create the necessary database objects to load and store your data. Read permissions on system tables are required to validate the existence and structure of existing database objects.

You will need to grant the following privileges to the database user you wish to use for the App Connectors function:

Snowflake:

<body>
<blockquote>
<br>GRANT CREATE ON WAREHOUSE warehouse_name TO periscope_ingest;
<br>GRANT CREATE ON DATABASE database_name TO periscope_ingest;
</blockquote>
</body>

Redshift:

<body>
<blockquote>
<br>GRANT CREATE ON DATABASE database_name TO periscope_ingest;
<br>GRANT SELECT ON ALL TABLES IN SCHEMA information_schema TO periscope_ingest;
<br>GRANT SELECT ON ALL TABLES IN SCHEMA pg_catalog TO periscope_ingest;
</blockquote>
</body>

You can add the above permissions to the existing Warehouse Admin created for Data Engine, but Periscope recommends providing an additional user to perform the App Connectors function.This will ensure that one service account is not responsible for too many actions.

If you want to query the data imported into your warehouse using the Connectors feature, you must also grant query permissions on the newly-created schema and its tables to the read user. The name of the schema will be the Display Name of the connected Source. After the first replication job has been completed, run the following commands to grant permissions to query the schema from within Periscope:

Snowflake:

<body>
<blockquote>
<br>GRANT USAGE ON SCHEMA database_name.schema_name TO ROLE periscope_read;
</blockquote>
</body>

Redshift:

<body>
<blockquote>
<br>GRANT USAGE ON SCHEMA schema_name TO periscope_read;
<br>GRANT SELECT ON ALL TABLES IN SCHEMA schema_name TO periscope_read;
</blockquote>
</body>

Note: The following IPs will need to be whitelisted for access to the destination database server:

  • 52.23.137.21/32
  • 52.204.223.208/32
  • 52.204.228.32/32
  • 52.204.230.227/32

<a name="HowToSetUpIngestion"></a>

<a href="#top">Back to top</a>

How to Setup Ingestion

Tables listed for the connector are available for ingestion into the warehouse. To select a table for ingestion, click on the box to the left of the table’s name.

Once a table has been selected, a list of columns that are available for ingestion will appear “Columns Selected for Ingestion”.

To select specific columns for ingestion, click on the box to the left of the column’s name.

Once the desired tables and columns have been selected, click Save in the bottom right.

<a name="SelectAnAttributionWindow"></a>

<a href="#top">Back to top</a>

Select an Attribution Window

An attribution window is the number of days between when a person viewed or clicked your ad and subsequently took an action. You can learn more about Attribution Windows in FaceBook Ads Manager here. We recommend selecting the same attribution window you use in Facebook Ads to prevent discrepancies between Facebook’s UI and data ingested into your warehouse. For example: If the attribution window in Facebook Ads is 7 days, you should define this setting as 7 days. In this scenario, Periscope will ingest the last 7 days of data to your warehouse, ensuring that records updated during the attribution period are captured. If clicks and views have different windows in your Facebook Ads account, select the greater of the two. For example: if clicks have a window of 7days and views have a window of 1 day, you should select 7 days and the attribution window.

Include Deleted Data

Check the 'Include data from deleted campaigns, ads, and adsets' box if you wish to have these deleted objects  ingested into your warehouse.

Note: Data for deleted campaigns, ads, and adsets will be included only in Core Object tables.

Once an Attribution Window has been selected and a selection has been made for Deleted Data, an Update Interval will need to be selected.

The 'Fetch Records Newer Than' field indicates the date from which the ingestion of the data into the warehouse should begin.  Select the fetch records date by clicking into the 'Fetch Records Newer Than' box.  

Notes:

1. The fetch records date will default to one year in the past if a date is not manually selected.To select an Update Interval, use the dropdown menu under Update Interval. Select the desired frequency for which the data should be ingested into the warehouse. 

2. The selected Update Interval and Fetch Records Newer Than date will apply for all tables and columns within a Connector that have been selected for ingestion and ingestion. Tables and columns within a given Connector cannot have differing Update Intervals and/or Fetch Records Newer Than dates.

Save the Update Interval and Fetch Records Newer Than data by clicking Save in the lower right corner of the section. It will take a few minutes for the data to be ingested into the warehouse. After a few minutes, navigate to the Database Connections tab from the Settings menu.

Select the appropriate warehouse from the dropdown menu and click on the refresh icon next to the schema for the warehouse.

Once the schema has been refreshed, the source name that was entered when the Connector was set up will appear in the schema browser and data will now be queryable.

<a name="ReauthorizeaConnector"></a>

<a href="#top">Back to top</a>

Reauthorize a Connector

In the event that changes have been made to the Facebook account associated with the Facebook Ads Connector, the Connector will need to reauthorized.  To reauthorize an account, click Reauthorize in the Ingestion page with the appropriate Connector selected from the dropdown menu.


Similar to when setting up a new Connector, a second screen will open with a prompt to select the appropriate Facebook account that is associated with the connector. Please select the appropriate Facebook account.

Click Allow once prompted to allow periscopedata.com to access the FacebookAccount.

‍Note: If you are reauthorizing a previously added account, you may see a screen that says “You’ve previously linked Periscope Data Connector to Facebook”.

Once permissions are allowed, a screen will appear directing with information on how to navigate back to Periscope Data. Either select closing to redirect back to the Connectors page, or wait as the window will automatically close in 5 seconds and redirect to the Connectors page.

<a name="SuspendIngestionforaConnector"></a>

<a href="#top">Back to top</a>

Suspend Ingestion for a Connector

In the event that ingestion for a Connector should be suspended, please select the Connector from the dropdown menu within the Ingestion page and toggle on Suspend Ingest from the Update Interval menu. Lastly, please click Save within this menu to save the changes made.

Note: It may be necessary to scroll within the menu to see this option.

<a name="DeleteaConnector"></a>

<a href="#top">Back to top</a>

Delete a Connector

To delete a Connector, navigate to the App Connections page from the Settings menu and select the name of the Connector to be deleted from the dropdown menu.

Click Delete in the bottom left:

In the Delete Source window, follow the instructions provided by typing the name of the Connector to be deleted in the field provided.

Once the name of the Connector has been entered, the Delete button will become available. Click the Delete button to delete the Connector.

<a name="SupportedConnectors"></a>

<a href="#top">Back to top</a>

Supported Connectors

Periscope Data currently supports the below Connectors:

The below list details future Connectors:

  • Google Sheets
  • Google Analytics

<a name="FacebookAdsSchemas"></a>

<a href="#top">Back to top</a>

Facebook Ads Schemas

There are two types of tables in Periscope’s Facebook Ads integration: Core Object and Insights. Primary keys are noted in bold within the table schemas.

Core Object tables contain foundational data that’s useful for analysis. These are the adcreative, ads, adsets, and campaigns tables. To learn more about how Facebook Ads data is structured, please see  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_gender table is segmented by day, age, and gender.

<details>
<summary><b><big><a href="https://developers.facebook.com/docs/marketing-api/reference/ad-creative/">Adcreative (Core Object)</a></big></b></summary>
<body>
<table style="border-collapse:collapse;">
<tr>
<th style="width:200px;text-align:left">Column</th>
<th style="width:200px;text-align:left">Data-Type</th>
<th style="width:200px;text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><b>id</b></td>
<td>STRING</td>
<td>The ID of the creative.</td>
</tr>
<tr>
<td>body</td>
<td>STRING</td>
<td>The body of the ad.</td>
</tr>
<tr>
<td>image_url</td>
<td>STRING</td>
<td>The URL for the image for the creative.</td>
</tr>
<tr>
<td>account_id</td>
<td>STRING</td>
<td>The ID of the account associated with the creative.</td>
</tr>
<tr>
<td>actor_id</td>
<td>STRING</td>
<td>The actor ID (page ID) of the creative.</td>
</tr>
<tr>
<td>adLabels</td>
<td>ARRAY</td>
<td>Details about the ad labels applied to the creative.</td>
</tr>
<tr>
<td>applink_treatment</td>
<td>STRING</td>
<td>The deep link fallback behavior for <a href="https://developers.facebook.com/docs/marketing-api/dynamic-product-ads/ads-management">dynamic product ads</a> if the app is not installed.</td>
</tr>
<tr>
<td>branded_content_sponsor_page_id</td>
<td>STRING</td>
<td>The sponsor page ID of the creative.</td>
</tr>
<tr>
<td>call_to_action_type</td>
<td>STRING</td>
<td>The call to action button text and header text of legacy ads.</td>
</tr>
<tr>
<td>effective_instagram_story_id</td>
<td>STRING</td>
<td>The ID of the Instagram post used in the ad.</td>
</tr>
<tr>
<td>effective_object_story_id</td>
<td>STRING</td>
<td>The ID of the page post used in an ad.</td>
</tr>
<tr>
<td>title</td>
<td>STRING</td>
<td>The title for an ad link.</td>
</tr>
<tr>
<td>name</td>
<td>STRING</td>
<td>The name of the creative in the creative library.</td>
</tr>
<tr>
<td>image_crops</td>
<td>ARRAY</td>
<td>Details about the crop specifications (aspect ratios) for images in different ad placements.</td>
</tr>
<tr>
<td>instagram_actor_id</td>
<td>STRING</td>
<td>The Instagram actor ID associated with the creative.</td>
</tr>
<tr>
<td>instagram_permalink_url</td>
<td>STRING</td>
<td>The Instagram permalink associated with the creative.</td>
</tr>
<tr>
<td>instagram_story_id</td>
<td>STRING</td>
<td>The ID of the Instagram post for creating ads.</td>
</tr>
<tr>
<td>link_og_id</td>
<td>STRING</td>
<td>The Open Graph (OG) ID for the link in the creative if the landing page has OG tags.</td>
</tr>
<tr>
<td>object_id</td>
<td>STRING</td>
<td>The ID of the <a href="https://developers.facebook.com/docs/marketing-api/reference/ad-campaign/promoted-object/v5.0">promoted object</a> or object that is relevant to the ad and ad type.</td>
</tr>
<tr>
<td>object_story_id</td>
<td>STRING</td>
<td>The ID of the page post that is used in the creative.</td>
</tr>
<tr>
<td>object_story_spec</td>
<td>OBJECT</td>
<td>Details about the specifications of a creative that are used to create a new unpublished page post.</td>
</tr>
<tr>
<td>object_type</td>
<td>STRING</td>
<td>The type of object being advertised. See Facebook docs for a list of allowed values.</td>
</tr>
<tr>
<td>object_url</td>
<td>STRING</td>
<td>The destination URL for link ads not connected to a page.</td>
</tr>
<tr>
<td>product_set_id</td>
<td>STRING</td>
<td>The ID of the product set for the creative.</td>
</tr>
<tr>
<td>status</td>
<td>STRING</td>
<td>The status of the creative. Possible values are ACTIVE or DELETED.</td>
</tr>
<tr>
<td>template_url</td>
<td>STRING</td>
<td>The tracking URL for dynamic product ads.</td>
</tr>
<tr>
<td>template_url_spec</td>
<td>OBJECT</td>
<td>Details about the template link specifications used to create ad creatives.</td>
</tr>
<tr>
<td>thumbnail_url</td>
<td>STRING</td>
<td>The URL to a thumbnail used for the creative.</td>
</tr>
<tr>
<td>image_hash</td>
<td>STRING</td>
<td>The image hash for an image used in the creative.</td>
</tr>
<tr>
<td>url_tags</td>
<td>STRING</td>
<td>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.</td>
</tr>
<tr>
<td>video_id</td>
<td>STRING</td>
<td>The ID of the video in the creative.</td>
</tr>
<tr>
<td>link_url</td>
<td>STRING</td>
<td>Used to identify a specific landing tab on the page by the page’s tab URL.</td>
</tr>
</table>
</body>
</details>


The adcreative table contains info about the creatives used in ads in your Facebook Ads account.

<details>
<summary><b><big><a href="https://developers.facebook.com/docs/marketing-api/reference/adgroup">Ads (Core Object)</a></big></b></summary>
<body>
<table style="border-collapse:collapse;">
<tr>
<th style="width:200px;text-align:left">Column</th>
<th style="width:200px;text-align:left">Data-Type</th>
<th style="width:200px;text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><b>id</b></td>
<td>STRING</td>
<td>The ad ID.</td>
</tr>
<tr>
<td><b>updated_time</b></td>
<td>DATE-TIME</td>
<td>The last time the ad was updated.</td>
</tr>
<tr>
<td>account_id</td>
<td>STRING</td>
<td>The ID of the ad account that the ad belongs to.</td>
</tr>
<tr>
<td>campaign_id</td>
<td>STRING</td>
<td>The ID of the ad campaign that contains this ad.</td>
</tr>
<tr>
<td>adset_id</td>
<td>STRING</td>
<td>The ID of the ad set that contains this ad.</td>
<tr>
<td>adLabels</td>
<td>ARRAY</td>
<td>Details about the ad labels applied to the ad.</td>
</tr>
<tr>
<td>bid_type</td>
<td>STRING</td>
<td>The bid type of the ad.</a> if the app is not installed.</td>
</tr>
<tr>
<td>bid_amount</td>
<td>INTEGER</td>
<td>The bid amount for the ad that will be used in auction instead of the ad set bid_amount, if specified.</td>
</tr>
<tr>
<td>status</td>
<td>STRING</td>
<td>The configured status of the ad.</td>
</tr>
<tr>
<td>creative</td>
<td>OBJECT</td>
<td>Details about the creative used by the ad.</td>
</tr>
<tr>
<td>created_time</td>
<td>DATE-TIME</td>
<td>Time the ad was created.</td>
</tr>
<tr>
<td>name</td>
<td>STRING</td>
<td>The name of the ad.</td>
</tr>
<tr>
<td>effective_status</td>
<td>STRING</td>
<td>The effective status of the ad.</td>
</tr>
<tr>
<td>targeting</td>
<td>OBJECT</td>
<td>Details about the targeting specs applied to the ad.</td>
</tr>
<tr>
<td>targeting</td>
<td>ARRAY</td>
<td>Targeting specs are ad set attributes that define who sees an ad.<br>Periscope may create subtables named ads__targeting__[spec_name] for each targeting spec type that is applied to the ad set. For example:<br>ads__targeting__life_events<br>If you have many targeting specs applied to ads, a large number of subtables may be created in your destination.</td>
</tr>
<tr>
<td>last_updated_by_app_id</td>
<td>STRING</td>
<td>The ID of the app that last updated the ad.</td>
</tr>
<tr>
<td>recommendations</td>
<td>ARRAY</td>
<td>Details about the recommendations for the ad, if there are any.</td>
</tr>
<tr>
<td>tracking_specs</td>
<td>ARRAY</td>
<td>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.</td>
</tr>
<tr>
<td>conversion_specs</td>
<td>ARRAY</td>
<td>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.</td>
</tr>
</table>
</body>
</details>

The ads table contains info about the ads in your Facebook Ads account.

updated_time and querying

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 deleted data” option is set to “True”,  this table will include data for deleted ads.

<html>
<details>
<summary><b><big><a href="https://developers.facebook.com/docs/marketing-api/insights/parameters/v5.0">ads_Insights</a></big></b></summary>
<body>
<table style="border-collapse:collapse;">
<tr>
<th style="width:200px;text-align:left">Column</th>
<th style="width:200px;text-align:left">Data-Type</th>
<th style="width:200px;text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><b>ad_id</b></td>
<td>STRING</td>
<td>The ID of the ad.</td>
</tr>
<tr>
<td><b>adset_id</b></td>
<td>NUMERIC STRING</td>
<td>The ID of the ad set.</td>
</tr>
<tr>
<td><b>campaign_id</b></td>
<td>NUMERIC STRING</td>
<td>The ID of the ad campaign. Campaigns contain ad sets and ads.</td>
</tr>
<tr>
<td><b>date_start</b></td>
<td>DATE-TIME</td>
<td>The start date.</td>
</tr>
<tr>
<td>date_stop</td>
<td>DATE-TIME</td>
<td>The end date.</td>
</tr>
<tr>
<td>ad_name</td>
<td>STRING</td>
<td>The name of the ad.</td>
</tr>
<tr>
<td>adset_name</td>
<td>STRING</td>
<td>The name of the adset.</td>
</tr>
<tr>
<td>campaign_name</td>
<td>STRING</td>
<td>The name of the campaign.</td>
</tr>
<tr>
<td>clicks</td>
<td>INTEGER</td>
<td>The number of clicks on your ads.</td>
</tr>
<tr>
<td>website_ctr</td>
<td>ARRAY</td>
<td>The percentage of times people saw the ad and performed a link click.</td>
</tr>
<tr>
<td>unique_inline_link_click_ctr</td>
<td>NUMBER</td>
<td>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.</td></tr>
<tr>
<td>frequency</td>
<td>NUMBER</td>
<td>The average number of times each person saw your ad.</td>
</tr>
<tr>
<td>account_id</td>
<td>STRING</td>
<td>The ID number of your ad account..</td>
</tr>
<tr>
<td>account_name</td>
<td>STRING</td>
<td>The name of your ad account.</td>
</tr>
<tr>
<td>canvas_avg_view_time</td>
<td>NUMBER</td>
<td>The average total time (in seconds) that people spent viewing a Facebook Canvas.</td>
</tr>
<tr>
<td>unique_inline_link_clicks</td>
<td>INTEGER</td>
<td>The number of people who performed an inline link click.</td>
</tr>
<tr>
<td>cost_per_unique_action_type</td>
<td>ARRAY</td>
<td>Details about the average cost of unique actions.</td>
</tr>
<tr>
<td>inline_post_engagement</td>
<td>INTEGER</td>
<td>The total number of actions that people take involving the ad. Inline post engagements use a fixed 1-day-click attribution window.</td>
</tr>
<tr>
<td>relevance_score</td>
<td>OBJECT</td>
<td>Details about the relevance score of the ad.</td>
</tr>
<tr>
<td>inline_link_clicks</td>
<td>INTEGER</td>
<td>The number of clicks on links to select destinations or experiences.</td>
</tr>
<tr>
<td>cpc</td>
<td>NUMBER</td>
<td>The average cost for each click (all).</td>
</tr>
<tr>
<td>cost_per_unique_inline_link_click</td>
<td>NUMBER</td>
<td>The average cost of each unique inline link click.</td>
</tr>
<tr>
<td>cpm</td>
<td>NUMBER</td>
<td>The average cost for 1000 impressions.</td>
</tr>
<tr>
<td>cost_per_inline_post_engagement</td>
<td>NUMBER</td>
<td>The average cost of each inline post engagement.</td>
</tr>
<tr>
<td>inline_link_click_ctr</td>
<td>NUMBER</td>
<td>The percentage of time people saw your ads and performed an inline link click.</td>
</tr>
<tr>
<td>cpp</td>
<td>NUMBER</td>
<td>The average cost to reach 1000 people.</td>
</tr>
<tr>
<td>cost_per_action_type</td>
<td>ARRAY</td>
<td>Details about the average cost of a relevant action.</td>
</tr>
<tr>
<td>unique_link_clicks_ctr</td>
<td>NUMBER</td>
<td>The percentage of people who saw the ad and performed a link click.</td>
</tr>
<tr>
<td>spend</td>
<td>NUMBER</td>
<td>The estimated total amount of money spent on the campaign</td>
</tr>
<tr>
<td>cost_per_unique_click</td>
<td>NUMBER</td><td>The average cost of each unique click (all).</td>
</tr>
<tr>
<td>unique_clicks</td>
<td>INTEGER</td>
<td>The number of people who performed a click (all).</td>
</tr>
<tr>
<td>social_spend</td>
<td>NUMBER</td>
<td>The total amount spent so far for the ad showed with social information. </td>
</tr>
<tr>
<td>reach</td>
<td>INTEGER</td>
<td>The number of people who saw the ad at least once.</td>
</tr>
<tr>
<td>canvas_avg_view_percent</td>
<td>NUMBER</td>
<td>The average percentage of the Facebook Canvas that people saw.</td>
</tr>
<tr>
<td>objective</td>
<td>STRING</td>
<td>The objective selected for the campaign. This reflects the goal you want to achieve with your advertising.</td>
</tr>
<tr>
<td>impressions</td>
<td>INTEGER</td>
<td>The number of times the ad was on screen.</td>
</tr>
<tr>
<td>unique_ctr</td>
<td>NUMBER</td>
<td>The percentage of people who saw your ad and performed a unique click (all).</td>
</tr>
<tr>
<td>cost_per_inline_link_click</td>
<td>NUMBER</td>
<td>The average cost of each inline link click.</td>
</tr>
<tr>
<td>ctr</td>
<td>NUMBER</td>
<td>The percentage of times people saw your ad and performed a click (all).</td>
</tr>
</table>
</body>
</details>

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.

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 gender

ads_insights_country - Data segmented by country

ads_insights_dma - Data segmented by DMA (Designated Market Area)

ads_insights_platform_and_device - Data segmented by platform and device

ads_insights_region - Data segmented by region


<details>
<summary><b><big><a href="https://developers.facebook.com/docs/marketing-api/insights/parameters/v5.0">Ads_Insights_age_and_gender</a></big></b></summary>
<body>
<table style="border-collapse:collapse;">
<tr>
<th style="width:200px;text-align:left">Column</th>
<th style="width:200px;text-align:left">Data-Type</th>
<th style="width:200px;text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><b>ad_id</b></td>
<td>STRING</td>
<td>The ID of the ad.</td>
</tr>
<tr>
<td><b>adset_id</b></td>
<td>NUMERIC STRING</td>
<td>The ID of the ad set.</td>
</tr>
<tr>
<td><b>campaign_id</b></td>
<td>NUMERIC STRING</td>
<td>The ID of the campaign. Campaigns contain ad sets and ads.</td>
</tr>
<tr>
<td><b>date_start</b></td>
<td>DATE-TIME</td>
<td>The start date.</td>
</tr>
<tr>
<td>age</td>
<td>INTEGER, STRING</td>
<td>The age by which the data is segmented.</td>
</tr>
<tr>
<td>gender</td>
<td>STRING</td>
<td>The gender by which the data is segmented.</td>
</tr>
<tr>
<td>date_stop</td>
<td>DATE-TIME</td>
<td>The end date.</td>
</tr>
<tr>
<td>ad_name</td>
<td>STRING</td>
<td>The name of the ad.</td>
</tr>
<tr>
<td>adset_name</td>
<td>STRING</td>
<td>The name of the adset.</td>
</tr>
<tr>
<td>campaign_name</td>
<td>STRING</td>
<td>The name of the campaign.</td>
</tr>
<tr>
<td>clicks</td>
<td>INTEGER</td>
<td>The number of clicks on your ads.</td>
</tr>
<tr>
<td>website_ctr</td>
<td>ARRAY</td>
<td>The percentage of times people saw the ad and performed a link click.</td>
</tr>
<tr>
<td>unique_inline_link_click_ctr</td>
<td>NUMBER</td>
<td>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.</td>
</tr>
<tr>
<td>frequency</td>
<td>NUMBER</td>
<td>The average number of times each person saw your ad.</td>
</tr>
<tr>
<td>account_id</td>
<td>STRING</td>
<td>The ID number of your ad account..</td>
</tr>
<tr>
<td>account_name</td>
<td>STRING</td>
<td>The name of your ad account.</td>
</tr>
<tr>
<td>canvas_avg_view_time</td>
<td>NUMBER</td>
<td>The average total time (in seconds) that people spent viewing a Facebook Canvas.</td>
</tr>
<tr>
<td>unique_inline_link_clicks</td>
<td>INTEGER</td>
<td>The number of people who performed an inline link click.</td>
</tr>
<tr>
<td>cost_per_unique_action_type</td>
<td>ARRAY</td>
<td>Details about the average cost of unique actions.</td>
</tr>
<tr>
<td>inline_post_engagement</td>
<td>INTEGER</td>
<td>The total number of actions that people take involving the ad. Inline post engagements use a fixed 1-day-click attribution window.</td>
</tr>
<tr>
<td>relevance_score</td>
<td>OBJECT</td>
<td>Details about the relevance score of the ad.</td>
</tr>
<tr>
<td>inline_link_clicks</td>
<td>INTEGER</td>
<td>The number of clicks on links to select destinations or experiences.</td>
</tr>
<tr>
<td>cpc</td>
<td>NUMBER</td>
<td>The average cost for each click (all).</td>
</tr>
<tr>
<td>cost_per_unique_inline_link_click</td>
<td>NUMBER</td>
<td>The average cost of each unique inline link click.</td>
</tr>
<tr>
<td>cpm</td>
<td>NUMBER</td>
<td>The average cost for 1000 impressions.</td>
</tr>
<tr>
<td>cost_per_inline_post_engagement</td>
<td>NUMBER</td>
<td>The average cost of each inline post engagement.</td>
</tr>
<tr>
<td>inline_link_click_ctr</td>
<td>NUMBER</td>
<td>The percentage of time people saw your ads and performed an inline link click.</td>
</tr>
<tr>
<td>cpp</td>
<td>NUMBER</td>
<td>The average cost to reach 1000 people.</td>
</tr>
<tr>
<td>cost_per_action_type</td>
<td>ARRAY</td>
<td>Details about the average cost of a relevant action.</td>
</tr>
<tr>
<td>unique_link_clicks_ctr</td>
<td>NUMBER/td>
<td>The percentage of people who saw the ad and performed a link click.</td>
</tr>
<tr>
<td>spend</td>
<td>NUMBER</td>
<td>The estimated total amount of money spent on the campaign</td>
</tr>
<tr>
<td>cost_per_unique_click</td>
<td>NUMBER</td>
<td>The average cost of each unique click (all).</td>
</tr>
<tr>
<td>unique_clicks</td>
<td>INTEGER</td>
<td>The number of people who performed a click (all).</td>
</tr>
<tr>
<td>social_spend</td>
<td>NUMBER</td>
<td>The total amount spent so far for the ad showed with social information. </td>
</tr>
<tr>
<td>reach</td>
<td>INTEGER</td>
<td>The number of people who saw the ad at least once.</td>
</tr>
<tr>
<td>canvas_avg_view_percent</td>
<td>NUMBER</td>
<td>The average percentage of the Facebook Canvas that people saw.</td>
</tr>
<tr>
<td>objective</td>
<td>STRING</td>
<td>The objective selected for the campaign. This reflects the goal you want to achieve with your advertising.</td>
</tr>
<tr>
<td>impressions</td>
<td>INTEGER</td>
<td>The number of times the ad was on screen.</td>
</tr>
<tr>
<td>unique_ctr</td>
<td>NUMBER</td>
<td>The percentage of people who saw your ad and performed a unique click (all).</td>
</tr>
<tr>
<td>cost_per_inline_link_click</td>
<td>NUMBER</td>
<td>The average cost of each inline link click.</td>
</tr>
<tr>
<td>ctr</td>
<td>NUMBER</td>
<td>The percentage of times people saw your ad and performed a click (all).</td>
</tr>
</table>
</body>
</details>


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

<details>
<summary><b><big><a href="https://developers.facebook.com/docs/marketing-api/insights/parameters/v5.0">ads_insights_country</a></big></b></summary>
<body>
<table style="border-collapse:collapse;">
<tr>
<th style="width:200px;text-align:left">Column</th>
<th style="width:200px;text-align:left">Data-Type</th>
<th style="width:200px;text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><b>ad_id</b></td><td>STRING</td>
<td>The ID of the ad.</td>
</tr>
<tr>
<td><b>adset_id</b></td>
<td>NUMERIC STRING</td>
<td>The ID of the ad set.</td>
</tr>
<tr>
<td><b>campaign_id</b></td>
<td>NUMERIC STRING</td>
<td>The ID of the campaign. Campaigns contain ad sets and ads.</td></tr><tr><td><b>date_start</b></td>
<td>DATE-TIME</td><td>The start date.</td>
</tr>
<tr>
<td>country</td>
<td>STRING</td>
<td>The country by which the data is segmented.</td>
</tr>
<tr>
<td>date_stop</td>
<td>DATE-TIME</td>
<td>The end date.</td>
</tr>
<tr>
<td>ad_name</td>
<td>STRING</td>
<td>The name of the ad.</td>
</tr>
<tr>
<td>adset_name</td>
<td>STRING</td>
<td>The name of the adset.</td>
</tr>
<tr>
<td>campaign_name</td>
<td>STRING</td>
<td>The name of the campaign.</td>
</tr>
<tr>
<td>clicks</td>
<td>INTEGER</td>
<td>The number of clicks on your ads.</td>
</tr>
<tr>
<td>website_ctr</td>
<td>ARRAY</td>
<td>The percentage of times people saw the ad and performed a link click</td>
</tr>
<tr>
<td>unique_inline_link_click_ctr</td>
<td>NUMBER</td>
<td>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.</td></tr>
<tr>
<td>frequency</td>
<td>NUMBER</td>
<td>The average number of times each person saw your ad.</td>
</tr>
<tr>
<td>account_id</td>
<td>STRING</td>
<td>The ID number of your ad account.</td>
</tr
><tr>
<td>account_name</td>
<td>STRING</td>
<td>The name of your ad account.</td>
</tr>
<tr>
<td>canvas_avg_view_time</td>
<td>NUMBER</td>
<td>The average total time (in seconds) that people spent viewing a Facebook Canvas.</td>
</tr>
<tr>
<td>unique_inline_link_clicks</td>
<td>INTEGER</td>
<td>The number of people who performed an inline link click.</td>
</tr>
<tr>
<td>cost_per_unique_action_type</td>
<td>ARRAY</td>
<td>Details about the average cost of unique actions.</td>
</tr>
<tr>
<td>inline_post_engagement</td>
<td>INTEGER</td>
<td>The total number of actions that people take involving the ad. Inline post engagements use a fixed 1-day-click attribution window.</td>
</tr>
<tr>
<td>relevance_score</td>
<td>OBJECT</td>
<td>Details about the relevance score of the ad.</td>
</tr>
<tr>
<td>inline_link_clicks</td>
<td>INTEGER</td>
<td>The number of clicks on links to select destinations or experiences.</td>
</tr>
<tr>
<td>cpc</td>
<td>NUMBER</td>
<td>The average cost for each click (all).</td>
</tr><tr><td>cost_per_unique_inline_link_click</td>
<td>NUMBER</td>
<td>The average cost of each unique inline link click.</td>
</tr>
<tr>
<td>cpm</td>
<td>NUMBER</td>
<td>The average cost for 1000 impressions.</td>
</tr>
<tr>
<td>cost_per_inline_post_engagement</td>
<td>NUMBER</td>
<td>The average cost of each inline post engagement.</td>
</tr>
<tr>
<td>inline_link_click_ctr</td>
<td>NUMBER</td>
<td>The percentage of time people saw your ads and performed an inline link click.</td>
</tr>
<tr>
<td>cpp</td>
<td>NUMBER</td>
<td>The average cost to reach 1000 people.</td>
</tr>
<tr>
<td>cost_per_action_type</td>
<td>ARRAY</td>
<td>Details about the average cost of a relevant action.</td>
</tr>
<tr>
<td>unique_link_clicks_ctr</td>
<td>NUMBER</td>
<td>The percentage of people who saw the ad and performed a link click.</td></tr>
<tr>
<td>spend</td>
<td>NUMBER</td>
<td>The estimated total amount of money spent on the campaign</td>
</tr>
<tr>
<td>cost_per_unique_click</td>
<td>NUMBER</td>
<td>The average cost of each unique click (all).</td>
</tr>
<tr>
<td>unique_clicks</td>
<td>INTEGER</td>
<td>The number of people who performed a click (all).</td>
</tr>
<tr>
<td>social_spend</td>
<td>NUMBER</td>
<td>The total amount spent so far for the ad showed with social information. </td>
</tr>
<tr>
<td>reach</td>
<td>INTEGER</td>
<td>The number of people who saw the ad at least once.</td>
</tr>
<tr>
<td>canvas_avg_view_percent</td>
<td>NUMBER</td>
<td>The average percentage of the Facebook Canvas that people saw.</td>
</tr>
<tr>
<td>objective</td>
<td>STRING</td>
<td>The objective selected for the campaign. This reflects the goal you want to achieve with your advertising.</td>
</tr>
<tr>
<td>impressions</td>
<td>INTEGER</td>
<td>The number of times the ad was on screen.</td>
</tr>
<tr>
<td>unique_ctr</td>
<td>NUMBER</td>
<td>The percentage of people who saw your ad and performed a unique click (all).</td>
</tr>
<tr>
<td>cost_per_inline_link_click</td>
<td>NUMBER</td>
<td>The average cost of each inline link click.</td>
</tr>
<tr>
<td>ctr</td>
<td>NUMBER</td>
<td>The percentage of times people saw your ad and performed a click (all).</td>
</tr>
</table>
</body>
</details>

The ads_insights_countryr 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.

<details>
<summary><b><big><a href="https://developers.facebook.com/docs/marketing-api/insights/parameters/v5.0">ads_insights_dma</a></big></b></summary>
<body>
<table style="border-collapse:collapse;">
<tr>
<th style="width:200px;text-align:left">Column</th>
<th style="width:200px;text-align:left">Data-Type</th>
<th style="width:200px;text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><b>ad_id</b></td>
<td>STRING</td>
<td>The ID of the ad.</td>
</tr>
<tr>
<td><b>adset_id</b></td>
<td>NUMERIC STRING</td>
<td>The ID of the ad set.</td>
</tr>
<tr>
<td><b>campaign_id</b></td>
<td>NUMERIC STRING</td>
<td>The ID of the campaign. Campaigns contain ad sets and ads.</td>
</tr>
<tr>
<td><b>date_start</b></td>
<td>DATE-TIME</td>
<td>The start date.</td>
</tr>
<tr>
<td>dma</td>
<td>STRING</td>
<td>The DMA by which the data is segmented.</td>
</tr>
<tr>
<td>date_stop</td>
<td>DATE-TIME</td>
<td>The end date.</td>
</tr>
<tr>
<td>ad_name</td>
<td>STRING</td>
<td>The name of the ad.</td>
</tr>
<tr>
<td>adset_name</td>
<td>STRING</td>
<td>The name of the adset.</td>
</tr>
<tr>
<td>campaign_name</td>
<td>STRING</td>
<td>The name of the campaign.</td>
</tr>
<tr>
<td>clicks</td>
<td>INTEGER</td>
<td>The number of clicks on your ads.</td>
</tr>
<tr>
<td>website_ctr</td>
<td>ARRAY</td>
<td>The percentage of times people saw the ad and performed a link click.</td>
</tr>
<tr>
<td>unique_inline_link_click_ctr</td>
<td>NUMBER</td>
<td>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.</td>
</tr>
<tr>
<td>frequency</td>
<td>NUMBER</td>
<td>The average number of times each person saw your ad.</td>
</tr>
<tr>
<td>account_id</td>
<td>STRING</td>
<td>The ID number of your ad account..</td>
</tr>
<tr>
<td>account_name</td>
<td>STRING</td>
<td>The name of your ad account.</td>
</tr>
<tr>
<td>canvas_avg_view_time</td>
<td>NUMBER</td>
<td>The average total time (in seconds) that people spent viewing a Facebook Canvas.</td>
</tr>
<tr>
<td>unique_inline_link_clicks</td>
<td>INTEGER</td>
<td>The number of people who performed an inline link click.</td>
</tr>
<tr>
<td>cost_per_unique_action_type</td>
<td>ARRAY</td>
<td>Details about the average cost of unique actions.</td>
</tr>
<tr>
<td>inline_post_engagement</td>
<td>INTEGER</td>
<td>The total number of actions that people take involving the ad. Inline post engagements use a fixed 1-day-click attribution window.</td>
</tr>
<tr>
<td>relevance_score</td>
<td>OBJECT</td>
<td>Details about the relevance score of the ad.</td>
</tr>
<tr>
<td>inline_link_clicks</td>
<td>INTEGER</td>
<td>The number of clicks on links to select destinations or experiences.</td>
</tr>
<tr>
<td>cpc</td>
<td>NUMBER</td>
<td>The average cost for each click (all).</td>
</tr>
<tr>
<td>cost_per_unique_inline_link_click</td>
<td>NUMBER</td>
<td>The average cost of each unique inline link click.</td>
</tr>
<tr>
<td>cpm</td>
<td>NUMBER</td>
<td>The average cost for 1000 impressions.</td>
</tr>
<tr>
<td>cost_per_inline_post_engagement</td>
<td>NUMBER</td>
<td>The average cost of each inline post engagement.</td>
</tr>
<tr>
<td>inline_link_click_ctr</td>
<td>NUMBER</td>
<td>The percentage of time people saw your ads and performed an inline link click.</td>
</tr>
<tr>
<td>cpp</td>
<td>NUMBER</td>
<td>The average cost to reach 1000 people.</td>
</tr>
<tr>
<td>cost_per_action_type</td>
<td>ARRAY</td>
<td>Details about the average cost of a relevant action.</td>
</tr>
<tr>
<td>unique_link_clicks_ctr</td>
<td>NUMBER/td>
<td>The percentage of people who saw the ad and performed a link click.</td>
</tr>
<tr>
<td>spend</td>
<td>NUMBER</td>
<td>The estimated total amount of money spent on the campaign</td>
</tr>
<tr>
<td>cost_per_unique_click</td>
<td>NUMBER</td>
<td>The average cost of each unique click (all).</td>
</tr>
<tr>
<td>unique_clicks</td>
<td>INTEGER</td>
<td>The number of people who performed a click (all).</td>
</tr>
<tr>
<td>social_spend</td>
<td>NUMBER</td>
<td>The total amount spent so far for the ad showed with social information. </td>
</tr>
<tr>
<td>reach</td>
<td>INTEGER</td>
<td>The number of people who saw the ad at least once.</td>
</tr>
<tr>
<td>canvas_avg_view_percent</td>
<td>NUMBER</td>
<td>The average percentage of the Facebook Canvas that people saw.</td>
</tr>
<tr>
<td>objective</td>
<td>STRING</td>
<td>The objective selected for the campaign. This reflects the goal you want to achieve with your advertising.</td>
</tr>
<tr>
<td>impressions</td>
<td>INTEGER</td>
<td>The number of times the ad was on screen.</td>
</tr>
<tr>
<td>unique_ctr</td>
<td>NUMBER</td>
<td>The percentage of people who saw your ad and performed a unique click (all).</td>
</tr>
<tr>
<td>cost_per_inline_link_click</td>
<td>NUMBER</td>
<td>The average cost of each inline link click.</td>
</tr>
<tr>
<td>ctr</td>
<td>NUMBER</td>
<td>The percentage of times people saw your ad and performed a click (all).</td>
</tr>
</table>
</body>
</details>

The ads_insights_dma table contains entries for each campaign/set/ad combination for each day, along with detailed statistics, segmented by DMA (Designated Market Area)..

This table contains the same fields as the ads_insights table, with the exception of dma.

Note: Data for deleted ads, adsets, and campaigns will not appear in this table.

<details>
<summary><b><big><a href="https://developers.facebook.com/docs/marketing-api/insights/parameters/v5.0">ads_insights_platform_and_device</a></big></b></summary>
<body>
<table style="border-collapse:collapse;">
<tr>
<th style="width:200px;text-align:left">Column</th>
<th style="width:200px;text-align:left">Data-Type</th>
<th style="width:200px;text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><b>ad_id</b></td>
<td>STRING</td>
<td>The ID of the ad.</td>
</tr>
<tr>
<td><b>adset_id</b></td>
<td>NUMERIC STRING</td>
<td>The ID of the ad set.</td>
</tr>
<tr>
<td><b>campaign_id</b></td>
<td>NUMERIC STRING</td>
<td>The ID of the campaign. Campaigns contain ad sets and ads.</td>
</tr>
<tr>
<td><b>date_start</b></td>
<td>DATE-TIME</td>
<td>The start date.</td>
</tr>
<tr>
<td><b>publisher_platform</b></td>
<td>STRING</td>
<td>The publishing platform by which the data is segmented. Ex: facebook or instagram.</td>
</tr>
<tr>
<td><b>platform_position</b></td>
<td>STRING</td>
<td>The platform position by which the data is segmented.</td>
</tr>
<tr>
<td><b>impression_device</b></td>
<td>STRING</td>
<td>The type of device by which the data is segmented.</td>
</tr>
<tr>
<td>date_stop</td>
<td>DATE-TIME</td>
<td>The end date.</td>
</tr>
<tr>
<td>ad_name</td>
<td>STRING</td>
<td>The name of the ad.</td>
</tr>
<tr>
<td>adset_name</td>
<td>STRING</td>
<td>The name of the adset.</td>
</tr>
<tr>
<td>campaign_name</td>
<td>STRING</td>
<td>The name of the campaign.</td>
</tr>
<tr>
<td>clicks</td>
<td>INTEGER</td>
<td>The number of clicks on your ads.</td>
</tr>
<tr>
<td>website_ctr</td>
<td>ARRAY</td>
<td>The percentage of times people saw the ad and performed a link click.</td>
</tr>
<tr>
<td>unique_inline_link_click_ctr</td>
<td>NUMBER</td>
<td>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.</td>
</tr>
<tr>
<td>frequency</td>
<td>NUMBER</td>
<td>The average number of times each person saw your ad.</td>
</tr>
<tr>
<td>account_id</td>
<td>STRING</td>
<td>The ID number of your ad account..</td>
</tr>
<tr>
<td>account_name</td>
<td>STRING</td>
<td>The name of your ad account.</td>
</tr>
<tr>
<td>canvas_avg_view_time</td>
<td>NUMBER</td>
<td>The average total time (in seconds) that people spent viewing a Facebook Canvas.</td>
</tr>
<tr>
<td>unique_inline_link_clicks</td>
<td>INTEGER</td>
<td>The number of people who performed an inline link click.</td>
</tr>
<tr>
<td>cost_per_unique_action_type</td>
<td>ARRAY</td>
<td>Details about the average cost of unique actions.</td>
</tr>
<tr>
<td>inline_post_engagement</td>
<td>INTEGER</td>
<td>The total number of actions that people take involving the ad. Inline post engagements use a fixed 1-day-click attribution window.</td>
</tr>
<tr>
<td>relevance_score</td>
<td>OBJECT</td>
<td>Details about the relevance score of the ad.</td>
</tr>
<tr>
<td>inline_link_clicks</td>
<td>INTEGER</td>
<td>The number of clicks on links to select destinations or experiences.</td>
</tr>
<tr>
<td>cpc</td>
<td>NUMBER</td>
<td>The average cost for each click (all).</td>
</tr>
<tr>
<td>cost_per_unique_inline_link_click</td>
<td>NUMBER</td>
<td>The average cost of each unique inline link click.</td>
</tr>
<tr>
<td>cpm</td>
<td>NUMBER</td>
<td>The average cost for 1000 impressions.</td>
</tr>
<tr>
<td>cost_per_inline_post_engagement</td>
<td>NUMBER</td>
<td>The average cost of each inline post engagement.</td>
</tr>
<tr>
<td>inline_link_click_ctr</td>
<td>NUMBER</td>
<td>The percentage of time people saw your ads and performed an inline link click.</td>
</tr>
<tr>
<td>cpp</td>
<td>NUMBER</td>
<td>The average cost to reach 1000 people.</td>
</tr>
<tr>
<td>cost_per_action_type</td>
<td>ARRAY</td>
<td>Details about the average cost of a relevant action.</td>
</tr>
<tr>
<td>unique_link_clicks_ctr</td>
<td>NUMBER/td>
<td>The percentage of people who saw the ad and performed a link click.</td>
</tr>
<tr>
<td>spend</td>
<td>NUMBER</td>
<td>The estimated total amount of money spent on the campaign</td>
</tr>
<tr>
<td>cost_per_unique_click</td>
<td>NUMBER</td>
<td>The average cost of each unique click (all).</td>
</tr>
<tr>
<td>unique_clicks</td>
<td>INTEGER</td>
<td>The number of people who performed a click (all).</td>
</tr>
<tr>
<td>social_spend</td>
<td>NUMBER</td>
<td>The total amount spent so far for the ad showed with social information. </td>
</tr>
<tr>
<td>reach</td>
<td>INTEGER</td>
<td>The number of people who saw the ad at least once.</td>
</tr>
<tr>
<td>canvas_avg_view_percent</td>
<td>NUMBER</td>
<td>The average percentage of the Facebook Canvas that people saw.</td>
</tr>
<tr>
<td>objective</td>
<td>STRING</td>
<td>The objective selected for the campaign. This reflects the goal you want to achieve with your advertising.</td>
</tr>
<tr>
<td>impressions</td>
<td>INTEGER</td>
<td>The number of times the ad was on screen.</td>
</tr>
<tr>
<td>unique_ctr</td>
<td>NUMBER</td>
<td>The percentage of people who saw your ad and performed a unique click (all).</td>
</tr>
<tr>
<td>cost_per_inline_link_click</td>
<td>NUMBER</td>
<td>The average cost of each inline link click.</td>
</tr>
<tr>
<td>ctr</td>
<td>NUMBER</td>
<td>The percentage of times people saw your ad and performed a click (all).</td>
</tr>
</table>
</body>
</details>

The ads_insights_platform_and_device table contains entries for each campaign/set/ad combination for each day, along with detailed statistics, segmented by platform, platform position, and device. 

This table contains the same fields as the ads_insights table, with the exception of publisher_platform, platform_position and impression_device.

Note: Data for deleted ads, adsets, and campaigns will not appear in this table.

<details>
<summary><b><big><a href="https://developers.facebook.com/docs/marketing-api/insights/parameters/v5.0">Ads_insights_region</a></big></b></summary>
<body>
<table style="border-collapse:collapse;">
<tr>
<th style="width:200px;text-align:left">Column</th>
<th style="width:200px;text-align:left">Data-Type</th>
<th style="width:200px;text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><b>ad_id</b></td>
<td>STRING</td>
<td>The ID of the ad.</td>
</tr>
<tr>
<td><b>adset_id</b></td>
<td>NUMERIC STRING</td>
<td>The ID of the ad set.</td>
</tr>
<tr>
<td><b>campaign_id</b></td>
<td>NUMERIC STRING</td>
<td>The ID of the campaign. Campaigns contain ad sets and ads.</td>
</tr>
<tr>
<td><b>date_start</b></td>
<td>DATE-TIME</td>
<td>The start date.</td>
</tr>
<tr>
<td><b>region</b></td>
<td>STRING</td>
<td>The region by which the data is segmented.</td>
</tr>
<tr>
<td>date_stop</td>
<td>DATE-TIME</td>
<td>The end date.</td>
</tr>
<tr>
<td>ad_name</td>
<td>STRING</td>
<td>The name of the ad.</td>
</tr>
<tr>
<td>adset_name</td>
<td>STRING</td>
<td>The name of the adset.</td>
</tr>
<tr>
<td>campaign_name</td>
<td>STRING</td>
<td>The name of the campaign.</td>
</tr>
<tr>
<td>clicks</td>
<td>INTEGER</td>
<td>The number of clicks on your ads.</td>
</tr>
<tr>
<td>website_ctr</td>
<td>ARRAY</td>
<td>The percentage of times people saw the ad and performed a link click.</td>
</tr>
<tr>
<td>unique_inline_link_click_ctr</td>
<td>NUMBER</td>
<td>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.</td>
</tr>
<tr>
<td>frequency</td>
<td>NUMBER</td>
<td>The average number of times each person saw your ad.</td>
</tr>
<tr>
<td>account_id</td>
<td>STRING</td>
<td>The ID number of your ad account..</td>
</tr>
<tr>
<td>account_name</td>
<td>STRING</td>
<td>The name of your ad account.</td>
</tr>
<tr>
<td>canvas_avg_view_time</td>
<td>NUMBER</td>
<td>The average total time (in seconds) that people spent viewing a Facebook Canvas.</td>
</tr>
<tr>
<td>unique_inline_link_clicks</td>
<td>INTEGER</td>
<td>The number of people who performed an inline link click.</td>
</tr>
<tr>
<td>cost_per_unique_action_type</td>
<td>ARRAY</td>
<td>Details about the average cost of unique actions.</td>
</tr>
<tr>
<td>inline_post_engagement</td>
<td>INTEGER</td>
<td>The total number of actions that people take involving the ad. Inline post engagements use a fixed 1-day-click attribution window.</td>
</tr>
<tr>
<td>relevance_score</td>
<td>OBJECT</td>
<td>Details about the relevance score of the ad.</td>
</tr>
<tr>
<td>inline_link_clicks</td>
<td>INTEGER</td>
<td>The number of clicks on links to select destinations or experiences.</td>
</tr>
<tr>
<td>cpc</td>
<td>NUMBER</td>
<td>The average cost for each click (all).</td>
</tr>
<tr>
<td>cost_per_unique_inline_link_click</td>
<td>NUMBER</td>
<td>The average cost of each unique inline link click.</td>
</tr>
<tr>
<td>cpm</td>
<td>NUMBER</td>
<td>The average cost for 1000 impressions.</td>
</tr>
<tr>
<td>cost_per_inline_post_engagement</td>
<td>NUMBER</td>
<td>The average cost of each inline post engagement.</td>
</tr>
<tr>
<td>inline_link_click_ctr</td>
<td>NUMBER</td>
<td>The percentage of time people saw your ads and performed an inline link click.</td>
</tr>
<tr>
<td>cpp</td>
<td>NUMBER</td>
<td>The average cost to reach 1000 people.</td>
</tr>
<tr>
<td>cost_per_action_type</td>
<td>ARRAY</td>
<td>Details about the average cost of a relevant action.</td>
</tr>
<tr>
<td>unique_link_clicks_ctr</td>
<td>NUMBER/td>
<td>The percentage of people who saw the ad and performed a link click.</td>
</tr>
<tr>
<td>spend</td>
<td>NUMBER</td>
<td>The estimated total amount of money spent on the campaign</td>
</tr>
<tr>
<td>cost_per_unique_click</td>
<td>NUMBER</td>
<td>The average cost of each unique click (all).</td>
</tr>
<tr>
<td>unique_clicks</td>
<td>INTEGER</td>
<td>The number of people who performed a click (all).</td>
</tr>
<tr>
<td>social_spend</td>
<td>NUMBER</td>
<td>The total amount spent so far for the ad showed with social information. </td>
</tr>
<tr>
<td>reach</td>
<td>INTEGER</td>
<td>The number of people who saw the ad at least once.</td>
</tr>
<tr>
<td>canvas_avg_view_percent</td>
<td>NUMBER</td>
<td>The average percentage of the Facebook Canvas that people saw.</td>
</tr>
<tr>
<td>objective</td>
<td>STRING</td>
<td>The objective selected for the campaign. This reflects the goal you want to achieve with your advertising.</td>
</tr>
<tr>
<td>impressions</td>
<td>INTEGER</td>
<td>The number of times the ad was on screen.</td>
</tr>
<tr>
<td>unique_ctr</td>
<td>NUMBER</td>
<td>The percentage of people who saw your ad and performed a unique click (all).</td>
</tr>
<tr>
<td>cost_per_inline_link_click</td>
<td>NUMBER</td>
<td>The average cost of each inline link click.</td>
</tr>
<tr>
<td>ctr</td>
<td>NUMBER</td>
<td>The percentage of times people saw your ad and performed a click (all).</td>
</tr>
</table>
</body>
</details>

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.

<details>
<summary><b><big>Adsets (Core Object)</big></b></summary>
<body>
<table style="border-collapse:collapse;">
<tr>
<th style="width:200px;text-align:left">Column</th>
<th style="width:200px;text-align:left">Data-Type</th>
<th style="width:200px;text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><b>id</b></td>
<td>STRING</td>
<td>The ID of the ad set.</td>
</tr>
<tr>
<td><b>updated_time</b></td>
<td>DATE-TIME</td>
<td>The last time the ad set was updated.</td>
</tr>
<tr>
<td>name</td>
<td>STRING</td>
<td>The name of the ad set.</td>
</tr>
<tr>
<td>end_time</td>
<td>DATE-TIME</td>
<td>The end time of the ad set.</td>
</tr>
<tr>
<td>promoted_object</td>
<td>OBJECT</td>
<td>Details about the object an ad set promotes.</td>
</tr>
<tr>
<td>account_id</td>
<td>STRING</td>
<td>The ad account ID.</td>
</tr>
<tr>
<td>daily_budget</td>
<td>NUMBER</td>
<td>The daily budget of the ad set.</td>
</tr>
<tr>
<td>budget_remaining</td>
<td>NUMBER</td>
<td>The remaining budget of the ad set.</td>
</tr>
<tr>
<td>effective_status</td>
<td>STRING</td>
<td>The effective status of the ad set.</td>
</tr>
<tr>
<td>campaign_id</td>
<td>STRING</td>
<td>The ID of the campaign containing this ad set.</td>
</tr>
<tr>
<td>created_time</td>
<td>DATE-TIME</td>
<td>The time the ad set was created.</td>
</tr>
<tr>
<td>start_time</td>
<td>DATE-TIME</td>
<td>The start time of the ad set.</td>
</tr>
<tr>
<td>lifetime_budget</td>
<td>NUMBER</td>
<td>The lifetime budget of the ad set.</td>
</tr>
<tr>
<td>targeting</td>
<td>ARRAY</td>
<td>Targeting specs are ad set attributes that define who sees an ad.<br>Periscope may create subtables named adsets__targeting__[spec_name] for each targeting spec type that is applied to the ad set. For example: adsets__targeting__life_events<br>If you have many targeting specs applied to ads, a large number of subtables may be created in your destination.</td>
</tr>
<tr>
<td>bid_info</td>
<td>OBJECT</td>
<td>Details about the bid information for this ad set.</td>
</tr>
<tr>
<td>adLabels</td>
<td>ARRAY</td>
<td>Details about the ad labels applied to the ad set.</td>
</tr>
</table>
</body>
</details>

The adsets table contains info about the Ad Sets in your Facebook Ads account.

updated_time and querying

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 deleted data” option is set to “True”,  this table will include data for deleted ads.

<details>
<summary><b><big>Campaigns (Core Object)</big></b></summary>
<body>
<table style="border-collapse:collapse;">
<tr>
<th style="width:200px;text-align:left">Column</th>
<th style="width:200px;text-align:left">Data-Type</th>
<th style="width:200px;text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><b>id</b></td>
<td>STRING</td>
<td>The campaign ID.</td>
</tr>
<tr>
<td><b>updated_time</b></td>
<td>DATE-TIME</td>
<td>The last time the campaign was updated.</td>
</tr>
<tr>
<td>name</td>
<td>STRING</td>
<td>The name of the campaign.</td>
</tr>
<tr>
<tr>
<td>objective</td>
<td>STRING</td>
<td>The objective of the campaign.</td>
</tr>
<tr>
<td>account_id</td>
<td>STRING</td>
<td>The ID of the ad account that owns the campaign.</td>
</tr>
<tr>
<td>effective_status</td>
<td>STRING</td>
<td>The effective status of the campaign.</td>
</tr>
<tr>
<td>buying_type</td>
<td>STRING</td>
<td>The campaign buying type.</td>
</tr>
<tr>
<td>spend_cap</td>
<td>NUMBER</td>
<td>The spend cap for the campaign.</td>
</tr>
<tr>
<td>start_time</td>
<td>DATE-TIME</td>
<td>The campaign's start time..</td>
</tr>
<tr>
<td>end_time</td>
<td>DATE-TIME</td>
<td>The campaign's end time.</td>
</tr>
<tr>
<td>ads</td>
<td>ARRAY</td>
<td>The IDs of the ads associated with the campaign</td>
</tr>
</table>
</body>
</details>

The campaigns table contains info about the campaigns in your Facebook Ads account. 

updated_time and querying

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 deleted data” option is set to “True”,  this table will include data for deleted ads.

<a href="#top">Back to top</a>

Our support team is ready to help