Facebook Ads Updates

Updates on the Facebook Ads data source, including new metrics, dimensions, and other features.

October 2024

2024-10-15

The following metric has been added:

• Omni content view conversion value (shared item)

April 2024

2024-04-04

The following dimension has been added:

• Audience type

March 2024

2024-03-26

The following fields have been deprecated:

• Estimated ad recall lift (upper bound)
• Estimated ad recall lift (lower bound)

January 2024

2024-01-04

New dimension added:

• Ad set optimization goal

December 2023

2023-12-12

Updated data source to Graph API v17.

The following field has been deprecated:

• Ad preview URL

October 2022

2022-10-28

Updated data source to Marketing Graph API v15.

July 2022

2022-07-13

New field added:

• Unique CTR

June 2022

2022-06-29

Updated data source to Facebook Graph API v14.0.

March 2022

2022-03-22

Added "Mixed" option to Report time of action stats setting. This can fix discrepancies with mixed onsite and offsite conversions.

January 2022

2022-01-25

The timezone optional setting was deprecated and the user interface element "Select timezone:" has been removed.

2022-01-11

Updated data source to Marketing Graph API v12.

New dynamic video ad dimensions added:

• Video asset name

• Video asset video ID

• Video asset ID

• Video asset URL

• Video asset thumbnail URL

December 2021

2021-12-21

New dynamic video ads dimensions added:

• Video asset name
• Video asset video ID
• Video asset ID
• Video asset URL
• Video asset thumbnail URL

2021-12-07

New conversion metrics added:

• On-Facebook view content
• Phone number clicks
• Get directions clicks
• Cost per on-Facebook view content
• Cost per on-Facebook phone number click
• Cost per on-Facebook get directions click

August 2021

2021-08-24

Updated data source to Marketing Graph API v11.

June 2021

2021-06-02

Field description fixed for "Description asset text" dimension.

Country names should now be normalized to match other data sources.

New fields added to support tags:

• Campaign tags
• Ad set tags
• Ad tags

2021-06-09:

Updated data source to Marketing Graph API v10.

Removed "Use account attribution window setting" UI element and support for the setting. It has been deprecated by Facebook as part of the April 26th changes for iOS 14, so it has been removed from our data source.

May 2021

2021-05-06 -

The following setting defaults have been changed to align with Facebook's updates around iOS 14/ATT changes:

• Conversion window: was '7 d click + 1 d view', is now '7 d view'
• Report time of action stats: was 'On impression date', is not 'On conversion date'

The following fields have been added:

• Cost per unique video view
• Cost per unique link click
• Term (utm)
• Source (utm)
• Medium (utm)
• Content (utm)
• Campaign (utm)

April 2021

2021-04-13:

We have updated the connectors to use Marketing Graph API 9.0.

2021-04-15 -

The following fields have been marked as deprecated and will stop returning data as of May 1st:

• Store visits point estimate
• Cost per store visit

2021-04-27 -
The following field has been renamed slightly to fix a typo:

Video play curve actions second: 15_20  => Video play curve actions second: 15-20

2021-04-29 -

The following field has been marked deprecated as was removed by Facebook some time ago and already returns no value. Please remove it from your reporting:

• Unique leads (form)

March 2021

2021-03-09:

The "Country" field now produces the country name. 

The original "Country" field has been renamed to "Country code".

2021-03-17 -

New fields added:

• Ad creative image
• Promoted post thumbnail
• Carousel card image

Feb. 2021

2021-02-02 -

New setting "Use account attribution setting" has been added to switch the attribution behavior to the account setting, rather than the default unified attribution settings.

New fields added:

• Attribution setting
• Is Campaign using SKAdNetwork

2021-02-09:

Default attribution setting has been updated in drop-down to "7 d click + 1 d view" to reflect the new window. "28 d click + 1 d view" has been added as a normal option, as it is no longer the default.

New fields added to breakdown the "Ad set targeting" data into easier to use chunks:

• Targeting maximum age
• Targeting minimum age
• Targeting country location
• Targeting country groups
• Targeting location type

2021-02-25 -

Support added for Collaborative Ads. The following fields have been added to work with those:

• Omni adds to cart (shared item)
• Mobile app adds to cart (shared item)
• Website adds to cart (shared item)
• Omni content view (shared item)
• Mobile apps content view (shared item)
• Website content view (shared item)
• Omni purchase (shared item)
• Mobile apps purchase (shared item)
• Website purchase (shared item)
• On-Facebook purchase (shared item)
• Omni adds to cart conversion value (shared item)
• Mobile apps adds to cart conversion value (shared item)
• Website adds to cart conversion value (shared item)
• Omni purchase conversion value (shared item)
• Mobile apps purchase conversion value (shared item)
• Website purchase conversion value (shared item)
• Omni purchase ROAS (shared item)
• Website purchase ROAS (shared item)
• Mobile app purchase ROAS (shared item)

Jan. 2021

2021-01-12 -

New dimensions added to support "Carousel Ads" type creatives.

• Carousel card ID
• Action carousel card name
• Carousel card description
• Carousel card call to action type
• Carousel card target URL
• Carousel card image URL

2021-01-19:

We have updated the connectors to use Marketing Graph API v8.0.

Dec. 2020

2020-12-04 -

Added new metrics for missing conversions:

• Ad click (mobile app)
• Ad impression (mobile app)
• Contact (total)
• Contact (website)
• Contact (mobile app)
• Contact (offline)
• Customize product (total)
• Customize product (website)
• Customize product (mobile app)
• Customize product (offline)
• Donate (total)
• Donate (website)
• Donate (on facebook)
• Donate (mobile app)
• Donate (offline)
• Find location (total)
• Find location (website)
• Find location (mobile app)
• Find location (offline)
• Schedule (total)
• Schedule (website)
• Schedule (mobile app)
• Schedule (offline)
• Start trial (total)
• Start trial (website)
• Start trial (mobile app)
• Start trial (offline)
• Submit application (total)
• Submit application (website)
• Submit application (mobile app)
• Submit application (offline)
• Subscribe (total)
• Subscribe (website)
• Subscribe (mobile app)
• Subscribe (offline)
• Contact value (total)
• Contact value (website)
• Contact value (mobile app)
• Contact value (offline)
• Customize product value (total)
• Customize product value (website)
• Customize product value (mobile app)
• Customize product value (offline)
• Donate value (total)
• Donate value value (website)
• Donate value (on facebook)
• Donate value (mobile app)
• Donate value (offline)
• Find location value (total)
• Find location value (website)
• Find location (mobile app)
• Find location value (offline)
• Schedule value (total)
• Schedule value (website)
• Schedule value (mobile app)
• Schedule value (offline)
• Start trial value (total)
• Start trial value (website)
• Start trial value (mobile app)
• Start trial value (offline)
• Submit application value (total)
• Submit application value (website)
• Submit application value (mobile app)
• Submit application value (offline)
• Subscribe value (total)
• Subscribe value (website)
• Subscribe value (mobile app)
• Subscribe value (offline)
• Cost per Ad click (mobile app)
• Cost per Ad impression (mobile app)
• Cost per Submit application
• Cost per Contact
• Cost per Donate
• Cost per Find location
• Cost per Customize product
• Cost per Schedule
• Cost per Start trial
• Cost per Subscribe
• Omni app installs
• Omni purchases
• Omni adds to cart
• Omni completed registrations
• Omni content views
• Omni searches
• Omni initiated checkouts
• Omni achievement unlocks
• Omni app activations
• Omni level completed
• Omni rates
• Omni credit spends
• Omni completed tutorials
• Omni custom actions

Sept. 2020

2019-09-22:

We have updated the connectors to use Marketing Graph API v7.0.

July 2020

2020-07-07:

"Messaging conversations started" properly moved to deprecated field section.

May 2020

2020-05-26:

We have updated the connectors to use Marketing Graph API v6.0.

April 2020

2020-04-07 -

The following fields have been added:

• Video play actions
• Video play curve actions second : 0
• Video play curve actions second : 1
• Video play curve actions second : 2
• Video play curve actions second : 3
• Video play curve actions second : 4
• Video play curve actions second : 5
• Video play curve actions second : 6
• Video play curve actions second : 7
• Video play curve actions second : 8
• Video play curve actions second : 9
• Video play curve actions second : 10
• Video play curve actions second : 11
• Video play curve actions second : 12
• Video play curve actions second : 13
• Video play curve actions second : 14
• Video play curve actions second : 15_20
• Video play curve actions second : 20_25
• Video play curve actions second : 25_30
• Video play curve actions second : 30_40
• Video play curve actions second : 40_50
• Video play curve actions second : 50_60
• Video play curve actions second 60 and more

March 2020

2020-03-25 -

We have updated the connectors to use Marketing Graph API v5.0.

The following metrics have been marked as deprecated:

• Relevance score
• Relevance score status
• Leads (form)
• Cost per lead (form)

The following metrics have been added:

• On-Facebook leads
• Cost per on-Facebook lead

Nov. 2019

2019-11-06:

The following field has been added -

• Amount spent (SEK)

The following field has been marked as deprecated and will no longer return data as of 2019-11-21:

• Video average percentage watched

2019-11-28 - The following fields have been added:

• Lead form name
• Lead form status

Oct. 2019

2019-10-14 - New field added:

• Existing post destination URL

Aug. 2019

2019-08-08:

We have updated the connectors to use Marketing Graph API v3.3.

2019-08-14:

The following fields have been added:

• Unique web adds to cart
• Unique web content views
• Unique web purchases
• Unique desktop adds to cart
• Unique desktop content views
• Unique desktop purchases
• Unique web app events
• Unique web app adds to cart
• Unique web app content views
• Unique web app purchases
• Unique mobile app retentions
• Unique mobile app ROAS
• Unique website conversions
• Unique website engagements
• Unique page stories engagements
• Unique instagram profile engagements
• Unique post stories engagements
• Unique conversions
• Unique adds to cart
• Unique store visits with dwell
• Unique completed registrations
• Unique purchases
• Unique searches
• Unique content views
• Unique initiated checkouts
• Unique payment info adds
• Unique adds to wishlist
• Unique leads
• Unique subscribes
• Unique Omni app installs
• Unique Omni purchases
• Unique Omni adds to cart
• Unique Omni completed registrations
• Unique Omni content views
• Unique Omni searches
• Unique Omni initiated checkout
• Unique Omni achievement unlocked
• Unique Omni app activations
• Unique Omni level achieves
• Unique Omni rates
• Unique Omni credit spends
• Unique Omni completed tutorials
• Unique Omni custom actions
• Page subscribes
• Credits spent conversion value
• New messaging conversations within 7 days
• Mobile app checkouts conversion value

July 2019

2019-07-10 - New metric added:

• Mobile app adds to cart conversion value

2019-07-16:

New dimensions added to support Dynamic Creative Ads:

• Body asset ID
• Body asset text
• Description asset ID
• Description asset text
• Image asset ID
• Image asset name
• Image asset hash
• Image asset URL
• Title asset ID
• Title asset text
• Call to action asset ID
• Call to action asset name
• Link asset ID
• Link asset website URL
• Link URL asset display URL

2019-07-23 - New metrics added:

• Website purchase ROAS %
• Return on ad spend (ROAS)

2019-07-31:

The following metric has been marked as "deprecated" and will return no data after 2019-08-08. Please remove it from your reporting to prevent disruptions:

• Messaging replies

The following metrics have been added:

• Messaging conversations started
• Messaging reply rate

"Messaging reply rate" is the intended replacement for "Messaging replies" but please note that it is a percent and does not work exact the same.

June 2019

2019-06-03:

New dimensions have been added which allows users to click through to view more details about the campaign/account or edit the details. The user clicking the link must have access to the ad account as normal to view the information.

• Account edit link
• Campaign edit link
• Ad set edit link

2019-06-25:

Added new metrics to show Ranking scores as text values (does not replace the fields with the raw numbers, but helps make it easier if you want to see the text values as shown in Ad Manager):

• Quality Ranking (text)
• Engagement Rate Ranking (text)
• Conversion Rate Ranking (text)

2019-06-27 - New metrics have been added:

• ThruPlay actions
• Cost per ThruPlay

May 2019

2019-05-07:

Due to the demand, we have found a way to re-create these fields in the backend even though Facebook had deprecated them. So these specifically are now un-deprecated and available to use:

• Website conversions
• Website conversion rate
• Cost per website conversion
• Website conversion rate

This field has been deprecated in the Facebook API and UI:

• Relevance score

But has been replaced by three new, better fields to track that information. See here for more information on what the fields do specifically.

• Quality ranking
• Engagement rate ranking
• Conversion rate ranking

2019-05-13:

The connectors have been updated to Marketing API version 3.2.

2019-05-24:

New metrics added that separately pull different conversion windows so that you request different windows in the same request.

• Conversions within 1 day of view
• Conversions within 7 days of view
• Conversions within 28 days of view
• Conversions within 1 day of click
• Conversions within 7 days of click
• Conversions within 28 days of click
• Unique conversions within 1 day of view
• Unique conversions within 7 days of view
• Unique conversions within 28 days of view
• Unique conversions within 1 day of click
• Unique conversions within 7 days of click
• Unique conversions within 28 days of click

2019-05-28 - New fields have been added:

• Cost per website checkout initiated
• Lifetime spend cap
• Lifetime minimum spend target

April 2019

2019-04-01 - a new metric has been added:

• Unique landing page views

2019-04-30:

New metrics have been added:

OFFLINE (Actions)

• Offline adds of payment info
• Offline adds to cart
• Offline adds to wishlist
• Offline registrations completed
• Offline checkouts initiated
• Offline searches
• Offline content views

OFFLINE CONVERSION VALUE (action_values)

• Offline adds of payment info conversion value
• Offline adds to cart conversion value
• Offline adds to wishlist conversion value
• Offline registrations completed conversion value
• Offline checkouts initiated conversion value
• Offline leads conversion value
• Offline other conversion value
• Offline purchases conversion value
• Offline searches conversion value
• Offline content views conversion value

The following fields have been marked as Deprecated with the text "(deprecated)" appended to a field's name. The fields will work as before until the 13th of May, 2019. After that the fields will return empty (NULL) values for all queries. Please check and update your queries if you are using any of these (most have current versions that replaced these).

• Mobile app actions (deprecated)
• Website conversions (deprecated)
• Website adds to cart (conversion tracking pixel) (deprecated)
• Website checkouts initiated (conversion tracking pixel) (deprecated)
• Website key page views (conversion tracking pixel) (deprecated)
• Website leads (conversion tracking pixel) (deprecated)
• Other website conversions (deprecated)
• Website registrations (conversion tracking pixel) (deprecated)
• Website conversion rate (deprecated)
• Cost per website add to cart (conversion tracking pixel) (deprecated)
• Cost per website conversion (deprecated)
• Cost per mobile app action (deprecated)
• Cost per website checkout initiated (conversion tracking pixel) (deprecated)
• Cost per website key page view (conversion tracking pixel) (deprecated)
• Cost per website lead (conversion tracking pixel) (deprecated)
• Cost per other website conversion (deprecated)
• Cost per website registration (conversion tracking pixel) (deprecated)

Sept. 2018

Support has been added for canvas fields - 2018-09-04:

• Avg. canvas view time
• Avg. canvas view percentage
• Canvas component name

Aug. 2018

2018-08-02:

Facebook Ads connectors have been updated to now use the Facebook Graph API version v3.1.

In addition, some metrics have been deprecated due to this update. They will be marked as (Deprecated) in the field name and return no results:

• Reach estimate: min bid amount
• Reach estimate: max bid amount
• Reach estimate: median bid amount
• Store visits high estimate
• Store visits low estimate

July 2018

The following metrics for Offline conversions have been added - 2018-07-25:

• Offline leads
• Offline purchase
• Offline other conversions

The following metrics and dimensions are deprecated on 2018-07-26:

• Social reach (social_reach)
• Social impressions (social_impressions)
• Cost per any action (total_actions)
• Relevance score negative feedback
• Relevance score positive feedback
• Social clicks (all) (social_clicks)
• Call-to-action clicks (call_to_action_clicks)

For more information on the deprecations, see https://business.facebook.com/business/help/1695754927158071

June 2018

New dimension added for Designated Market Area - 2018-06-13:

• DMA

May 2018

2018-05-04:

Connectors have been updated to now use the Facebook Graph API version v2.12

"15-second video views" metric is a deprecated field and will return empty results. It should now be marked as (Deprecated) in the field name

April 2018

New dimensions added - 2018-04-01:

• Campaign start date
• Campaign end date
• Campaign start date & time
• Campaign end date & time
• Ad creative image URL

March 2018

New dimensions added - 2018-03-28:

• Campaign start date
• Campaign end date
• Campaign start date & time
• Campaign end date & time
• Ad creative image URL

Feb. 2018

2018-02-01 - new fields added:

Outbound clicks:
Outbound clicks
Unique outbound clicks
Outbound CTR (%)
Unique outbound CTR (%)

Messaging conversations:
New messaging conversations
Messaging replies
Blocked message conversations
Cost per new messaging conversation
Cost per messaging reply

On-Facebook purchases and workflow completion:
On-Facebook purchases
On-Facebook workflow completion
Cost per on-Facebook purchase
Cost per workflow completion on Facebook
Conversion value of purchase on Facebook
Conversion value of workflow completion on Facebook

Custom conversion labels

Dimension "Custom conv. labels" will use custom conversion labels instead of ID numbers

Old dimension renamed "Action type (with custom conv. IDs)"