Skip to main content
Skip table of contents

Facebook Ads

Overview

The Facebook Ads datasource allows you to query data from your Facebook Business Manager profiles.

Vendor/Partner

Facebook

Version

v17.0

API Documentation

https://developers.facebook.com/docs/graph-api/

https://developers.facebook.com/docs/graph-api/changelog/versions/

Sunset Date

Marketing API: May 14, 2024

Channel(s)

Refresh Time (CST)

6am / Real Time

Default backfill

Most metrics will update once every 24 hours.

Alli Data Library

(tick)

Getting Started

Required Authorization

Facebook Ads requires a Facebook account with access to Facebook Business Manager. You can check which profiles you have access to by visiting business.facebook.com.

  1. Once you have an account with Business Manager access, click the Request Facebook Ads Access button.

  2. Next, select ad accounts from the Additional Configuration Needed section. You can select multiple ad accounts by holding down the CTRL ( on macOS X) key.

  3. Make sure to click the Next button to save your selection.

Define your Data

Dimensions

Name

Type

Description

Field Name

Start Date

date

Start date of the report.

date_start

End Date

date

End date of the report.

date_stop

Account Id

string

ID number that is unique to your ad account.

account_id

Account Name

string

The grouping of all your specific ads activity. Your ad account includes different campaigns, ads and billing information.

account_name

Ad Audience Id

string

A comma-separated list of audience ids attached to an ad.

ad_audience_id

Ad Audience Name

string

A comma-separated list of audiences attached to an ad.

ad_audience_name

Ad Creative Id

string

The Ad Creative Id - to generate a facebook insights report, add this metric.

ad_creative_id

Ad Id

string

ID number that is unique to each ad.

ad_id

Ad Name

string

An individual ad includes its creative (ex: the image and text it uses) and the specific audience it targets.

ad_name

Ad Optimization Goal

string

The optimization goal for the ad.

ad_optimization_goal

Ad Targeting

JSON

The targeting options for the ad.

ad_targeting

Adset Id

string

ID number that is unique to each ad set.

adset_id

Adset Name

string

A group of ads that share the same budget and are usually about a single topic.

adset_name

Age

string

The age range of the people you have reached.

age

Attribution Setting

string

The attribution setting of the campaign.

attribution_setting

Buying Type

string

The method by which you pay for and target ads in your campaigns: through dynamic auction bidding, fixed-price bidding or reach and frequency buying.

buying_type

Campaign Id

string

ID number that is unique to each campaign.

campaign_id

Campaign Name

string

A group of ad sets that share the same objective.

campaign_name

Card Views

string

The number of times your product was viewed.

card_views

Country

string

The countries where the people you have reached are located. This is based on information such as a person's hometown, their current city and the geographical location where they tend to be when they visit Facebook.

country

Device Platform

string

The Device OS where your last ad was served to someone on Facebook. For example "iOS 10" if someone viewed your ad on an iPhone with iOS 10.

device_platform

DMA

string

The DMA where the people you have reached are located. This is based on information such as a person's hometown, their current city and the geographical location where they tend to be when they visit Facebook.

dma

Frequency Value

string

The number of times an ad in your Reach and Frequency campaign was served to each person.

frequency_value

Gender

string

Gender of people you have reached. People who do not list their gender are shown as 'not specified'.

gender

Hourly Stats Aggregated By Advertiser Time Zone

string

Hourly breakdown aggregated by the time ads were delivered in the advertiser's time zone. For example, if your ads are scheduled to run from 9 AM to 11 AM, but they reach audiences in multiple time zones, they may deliver from 9 AM to 1 PM in the advertiser's time zone. Stats will be aggregated into four groups 9 AM - 10 AM, 10 AM - 11 AM, 11 AM - 12 PM, and 12 PM - 1 PM.

hourly_stats_aggregated_by_advertiser_time_zone

Hourly Stats Aggregated By Audience Time Zone

string

Hourly breakdown aggregated by the time ads were delivered in the audiences' time zone. For example, if your ads are scheduled to run from 9 AM to 11 AM but they reach audiences in multiple time zones, they may deliver from 9 AM to 1 PM in the advertiser's time zone. Stats will be aggregated into two groups 9 AM - 10 AM and 10 AM - 11 AM.

hourly_stats_aggregated_by_audience_time_zone

Impression Device

string

The device where your last ad was served to someone on Facebook. For example "iPhone" if someone viewed your ad on an iPhone.

impression_device

Instagram URL

string

Instagram permalink.

instagram_permalink_url

Object Story Id

string

The organic insights api id. Note: this field also requires the ad id to be added.

effective_object_story_id

Objective

string

The objective you selected for your ad, ad set or campaign. Your objective reflects what you want to achieve with ads.

objective

Place Page Id

string

The id of the place page involved in impression, click or action.

place_page_id

Place Page Name

string

The name of the place page involved in impression, click or action. Has to be used together with Business Locations breakdown.

place_page_name

Platform Position

string

The position on the page where your ad shows up.

platform_position

Product Id

string

The id of the product involved in impression, click or action.

product_id

Publisher Platform

string

Publisher Platform, (e.g. Instagram vs Facebook)

publisher_platform

Region

string

The regions where the people you have reached are located. This is based on information such as a person's hometown, their current city and the geographical location where they tend to be when they visit Facebook.

region

Metrics

Name

Type

Description

Field Name

Actions

number

actions

Action Values

number

The total revenue returned from conversions or Facebook credit spends that occurred on your website or app.

action_values

App Custom Event Conversion - FB Mobile App Purchase (Catalog Segment Action)

number

The number of purchases made through the Mobile App to ads promoting a catalog segment.

catalog_segment_actions_app_custom_event_fb_mobile_purchase

App Custom Event Conversion - FB Mobile App Purchase (Catalog Segment Value)

number

The value of purchases made through the Mobile App to ads promoting a catalog segment.

catalog_segment_value_app_custom_event_fb_mobile_purchase

Canvas Average View Percentage

Number

The average percentage of the Canvas seen.

canvas_avg_view_percent

Canvas Average View Time

Number

The average time spent in seconds, within a Canvas unit.

canvas_avg_view_time

Comment (unique action)

number

Action count for Comment event.

uaction_comment

Comments (action)

number

action_comment

Conversion Rate Ranking

string

A ranking of your ad's expected conversion rate. Your ad is ranked against ads with your optimization goal that competed for the same audience.

conversion_rate_ranking

Cost Per Inline Link Click

number

The average you paid for each inline link click.

cost_per_inline_link_click

Cost Per Inline Post Engagement

number

The average you paid for each inline post engagement.

cost_per_inline_post_engagement

Cost Per Link Click Action

Number

cost_per_action_link_click

Cost Per Link Click Unique Action

Number

cost_per_uaction_link_click

Cost Per Offsite Conversion

Number

cost_per_action_offsite_conversion

Cost Per Page Engagement Action

Number

cost_per_action_page_engagement

Cost Per Page Engagement Unique Action

Number

cost_per_uaction_page_engagement

Cost Per Post Engagement Unique Action

Number

cost_per_uaction_post_engagement

Cost Per Post Engagement

Number

cost_per_action_post_engagement

Cost Per Store Visit

number

Cost Per Store Visit.

cost_per_store_visit_actions

Cost Per Unique Click

number

The average cost per unique click for these ads, calculated as the amount spent divided by the number of unique clicks received.

cost_per_unique_click

Cost Per Unique Offsite Conversion

Number

cost_per_uaction_offsite_conversion

CPM

number

The average cost you have paid to have 1,000 impressions of your ad.

cpm

CPP

number

The average cost you have paid to have your ad served to 1,000 unique people.

cpp

CTR

number

The number of clicks you received divided by the number of impressions.

ctr

Custom Event - Other (action)

number

action_app_custom_event_other

Custom Event - Other (unique action)

number

uaction_app_custom_event_other

Engagement Rate Ranking

string

A ranking of your ad's expected engagement rate. Engagement includes all clicks, likes, comments and shares. Your ad is ranked against ads that competed for the same audience.

engagement_rate_ranking

Estimated Ad Recall Rate

number

The rate at which an estimated number of additional people, when asked, would remember seeing your ads within 2 days. This metric is only available for assets in the Brand awareness, Post engagement and Video views Objectives

estimated_ad_recall_rate

Estimated Ad Recallers

number

An estimate of the number of additional people who may remember seeing your ads, if asked, within 2 days.

estimated_ad_recallers

Facebook Mobile Activations (action)

number

The number of mobile app starts.

action_app_custom_event_fb_mobile_activate_app

Facebook Mobile Activations (unique action)

number

The number of mobile app starts.

uaction_app_custom_event_fb_mobile_activate_app

Facebook Mobile Content View (action)

number

The number of mobile content views.

action_app_custom_event_fb_mobile_content_view

Facebook Mobile Content View (unique action)

number

The number of mobile content views.

uaction_app_custom_event_fb_mobile_content_view

Facebook Mobile Initiated Checkout (action)

number

The number of mobile initiated checkouts.

action_app_custom_event_fb_mobile_initiated_checkout

Facebook Mobile Initiated Checkout (unique action)

number

The number of mobile initiated checkouts.

uaction_app_custom_event_fb_mobile_initiated_checkout

Facebook Mobile Purchase (action)

number

The number of mobile purchases.

action_app_custom_event_fb_mobile_purchase

Facebook Mobile Purchase (unique action)

number

The number of mobile purchases.

uaction_app_custom_event_fb_mobile_purchase

Frequency

number

The average number of times your ad was served to each person.

frequency

Impressions

number

The number of times your ad was served. On our mobile apps, an ad is counted as served the first time it is viewed. On all other Facebook interfaces, an ad is served the first time it is placed in a person's News Feed or each time it is placed in the right column.

impressions

Inline Link Clicks

number

The number of inline link clicks that your ad received.

inline_link_clicks

Inline Post Engagement

number

The number of inline post engagement that your ad received.

inline_post_engagement

Landing Page View (action)

number

action_landing_page_view

Landing Page View (unique action)

number

uaction_landing_page_view

Lead (Action)

number

Action count for Lead.

action_lead

Leadgen Other (Action)

number

Action count for Leadgen Other.

action_leadgen_other

Link Click (action)

number

action_link_click

Link Click (unique action)

number

uaction_link_click

Link URL Asset

string

The ID of the URL asset involved in impression, click or action.

link_url_asset

Mentions (action)

number

action_mention

Mentions (unique action)

number

uaction_mention

Mobile App Installs (action)

number

The number of mobile app installs.

action_mobile_app_install

Mobile App Installs (unique action)

number

uaction_mobile_app_install

Offline Conversion - Purchase (action value)

number

Revenue of conversions uploaded from in-store visits.

action_values_offline_conversion_purchase

Offline Conversion - Purchase (action)

number

Number of conversions uploaded from in-store visits.

action_offline_conversion_purchase

Offline Conversion - Purchase (Catalog Segment Action)

number

The value of purchases made through the Mobile App to ads promoting a catalog segment.

catalog_segment_actions_offline_conversion_purchase

Offline Conversion - Purchase (Catalog Segment Value)

number

The value of purchases made through the Mobile App to ads promoting a catalog segment.

catalog_segment_value_offline_conversion_purchase

Offsite Conversion - Add To Cart (action)

number

action_offsite_conversion_fb_pixel_add_to_cart

Offsite Conversion - Add To Cart (unique action)

number

uaction_offsite_conversion_fb_pixel_add_to_cart

Offsite Conversion - Checkouts (action)

number

Conversions from an Offsite Conversion - Checkouts.

action_offsite_conversion_checkout

Offsite Conversion - Checkouts (unique action)

number

Conversions from an Offsite Conversion - Checkouts.

uaction_offsite_conversion_checkout

Offsite Conversion - Complete Registration (action)

number

action_offsite_conversion_fb_pixel_complete_registration

Offsite Conversion - Complete Registration (unique action)

number

uaction_offsite_conversion_fb_pixel_complete_registration

Offsite Conversion - Custom (action)

number

action_offsite_conversion_fb_pixel_custom

Offsite Conversion - Custom (unique action)

number

uaction_offsite_conversion_fb_pixel_custom

Offsite Conversion - Initiate Checkout (action)

number

action_offsite_conversion_fb_pixel_initiate_checkout

Offsite Conversion - Initiate Checkout (unique action)

number

uaction_offsite_conversion_fb_pixel_initiate_checkout

Offsite Conversion - Leads (action)

number

Conversions from an Offsite Conversion - Leads within the default attribution window.

action_offsite_conversion_fb_pixel_lead

Offsite Conversion - Leads (unique action)

number

Conversions from an Offsite Conversion - Leads

uaction_offsite_conversion_lead

Offsite Conversion - Purchase (action value)

number

The value of purchases made as reported by the FB pixel.

action_values_offsite_conversion_fb_pixel_purchase

Offsite Conversion - Purchase (action)

number

action_offsite_conversion_fb_pixel_purchase

Offsite Conversion - Purchase (Catalog Segment Action)

number

The number of purchases made as reported by the FB pixel to ads promoting a catalog segment.

catalog_segment_actions_offsite_conversion_fb_pixel_purchase

Offsite Conversion - Purchase (Catalog Segment Value)

number

The value of purchases made as reported by the FB pixel to ads promoting a catalog segment.

catalog_segment_value_offsite_conversion_fb_pixel_purchase

Offsite Conversion - Purchase (unique action)

number

uaction_offsite_conversion_fb_pixel_purchase

Offsite Conversion - Revenue (action value)

Number

The total revenue returned from conversions or Facebook credit spends that occurred on your website or app.

offsite_conversion_revenue

Offsite Conversion - View Content (action)

number

The number of content views as counted by the FB pixel on your website.

action_offsite_conversion_fb_pixel_view_content

Offsite Conversion - View Content (unique action)

number

uaction_offsite_conversion_fb_pixel_view_content

Offsite Conversion (Action Value)

number

Action Value value for Offsite Conversion.

action_values_offsite_conversion

Offsite Conversion (action)

number

Conversions from an offsite conversion.

action_offsite_conversion

Offsite Conversion (unique action)

number

Conversions from an offsite conversion.

uaction_offsite_conversion

Offsite Conversion Checkout (Action Value)

number

Action Value value for Offsite Conversion Checkout.

action_values_offsite_conversion_checkout

Offsite Conversion Fb Pixel Add to Cart (Action Value)

number

Action Value value for Offsite Conversion Fb Pixel Add to Cart.

action_values_offsite_conversion_fb_pixel_add_to_cart

Offsite Conversion Fb Pixel Add to Wishlist (Action Value)

number

Action Value value for Offsite Conversion Fb Pixel Add to Wishlist.

action_values_offsite_conversion_fb_pixel_add_to_wishlist

Offsite Conversion Fb Pixel Add to Wishlist (Action)

number

Action count for Offsite Conversion Fb Pixel Add to Wishlist.

action_offsite_conversion_fb_pixel_add_to_wishlist

Offsite Conversion Fb Pixel Complete Registration (Action Value)

number

Action Value value for Offsite Conversion Fb Pixel Complete Registration

action_values_offsite_conversion_fb_pixel_complete_registration

Offsite Conversion Fb Pixel Custom (Action Value)

number

Action Value value for Offsite Conversion Fb Pixel Custom.

action_values_offsite_conversion_fb_pixel_custom

Offsite Conversion Fb Pixel Initiate Checkout (Action Value)

number

Action Value value for Offsite Conversion Fb Pixel Initiate Checkout.

action_values_offsite_conversion_fb_pixel_initiate_checkout

Offsite Conversion Fb Pixel Lead (Action Value)

number

Action Value value for Offsite Conversion Fb Pixel Lead

action_values_offsite_conversion_fb_pixel_lead

Offsite Conversion Fb Pixel Search (Action Value)

number

Action Value value for Offsite Conversion Fb Pixel Search.

action_values_offsite_conversion_fb_pixel_search

Offsite Conversion Fb Pixel Search (Action)

number

Action count for Offsite Conversion Fb Pixel Search.

action_offsite_conversion_fb_pixel_search

Offsite Conversion Fb Pixel View Content (Action Value)

number

Action Value value for Offsite Conversion Fb Pixel View Content.

action_values_offsite_conversion_fb_pixel_view_content

Offsite Conversion Lead (Action Value)

number

Action Value value for Offsite Conversion Lead.

action_values_offsite_conversion_lead

Offsite Conversion Lead (Action)

number

Action count for Offsite Conversion Lead.

action_offsite_conversion_lead

Omni Achievement Unlocked (Action)

number

Action count for Omni Achievement Unlocked.

action_omni_achievement_unlocked

Omni Activate App (Action)

number

Action count for Omni Activate App.

action_omni_activate_app

Omni Add to Cart (Action Value)

number

Action Value value for Omni Add to Cart.

action_values_omni_add_to_cart

Omni Add to Cart (Action)

number

Action count for Omni Add to Cart.

action_omni_add_to_cart

Omni Add To Cart (Catalog Segment Action)

number

Add To Carts attributed to ads promoting a catalog segment.

catalog_segment_actions_omni_add_to_cart

Omni Add To Cart (Catalog Segment Value)

number

Add To Carts attributed to ads promoting a catalog segment.

catalog_segment_value_omni_add_to_cart

Omni App Install (Action)

number

Action count for Omni App Install.

action_omni_app_install

Omni Complete Registration (Action)

number

Action count for Omni Complete Registration.

action_omni_complete_registration

Omni Custom (Action)

number

Action count for Omni Custom.

action_omni_custom

Omni Initiated Checkout (Action)

number

Action count for Omni Initiated Checkout.

action_omni_initiated_checkout

Omni Level Achieved (Action)

number

Action count for Omni Level Achieved.

action_omni_level_achieved

Omni Purchase (Action Value)

number

Action Value value for Omni Purchase

action_values_omni_purchase

Omni Purchase (Action)

number

Action count for Omni Purchase.

action_omni_purchase

Omni Purchases (Catalog Segment Action)

number

Purchases attributed to ads promoting a catalog segment.

catalog_segment_actions_omni_purchase

Omni Purchases (Catalog Segment Value)

number

Purchases Value attributed to ads promoting a catalog segment.

catalog_segment_value_omni_purchase

Omni Rate (Action)

number

Action count for Omni Rate.

action_omni_rate

Omni Search (Action)

number

Action count for Omni Search.

action_omni_search

Omni Spend Credits (Action)

number

Action count for Omni Spend Credits.

action_omni_spend_credits

Omni Tutorial Completion (Action)

number

Action count for Omni Tutorial Completion.

action_omni_tutorial_completion

Omni View Content (Action Value)

number

Action Value value for Omni View Content.

action_values_omni_view_content

Omni View Content (Action)

number

Action count for Omni View Content.

action_omni_view_content

Omni View Content (Catalog Segment Action)

number

View Content attributed to ads promoting a catalog segment.

catalog_segment_actions_omni_view_content

Onsite Conversion Leads (Forms)

number

The number of form responses submitted after people clicked on an ad that includes an instant form.

action_onsite_conversion_lead_grouped

Onsite Conversion Post Save (Action)

number

Action count for Onsite Conversion Post Save.

action_onsite_conversion_post_save

Onsite Conversion Purchase (Action)

number

Action count for Onsite Conversion Purchase.

action_onsite_conversion_purchase

Outbound Click (Action)

number

Action count for Outbound Click.

action_outbound_click

Page Engagement (action)

number

action_page_engagement

Page Engagement (unique action)

number

uaction_page_engagement

Photo View (unique action)

number

uaction_photo_view

Photo Views (action)

number

The number of views on a photo.

action_photo_view

Post Dwell (action)

number

action_dwell

Post Dwell (unique action)

number

uaction_dwell

Post Engagement (action)

number

action_post_engagement

Post Engagement (unique action)

number

uaction_post_engagement

Post Full Views (action)

number

action_full_view

Post Full Views (unique action)

number

uaction_full_view

Post Reaction (unique action)

number

uaction_post_reaction

Post Reactions (action)

number

The number of reactions a post received.

action_post_reaction

Post Share (unique action)

number

uaction_post

Post Shares (action)

number

The number of shares a post received.

action_post

Quality Ranking

string

A ranking of your ad's perceived quality. Quality is measured using feedback on your ads and the post-click experience. Your ad is ranked against ads that competed for the same audience.

quality_ranking

Reach

number

The number of people your ad was served to.

reach

RSVPs (action)

number

The number of RSVPs to an event.

action_rsvp

Social Clicks

number

The number of clicks your ad receives when it's shown with social information (ex: Jane Doe likes this).

social_clicks

Social Impressions

number

The number of times your ad was served, with social information. For example, if 3 people are served an ad 2 times each and it includes information about a friend liking your Page, it counts as 6 social impressions.

social_impressions

Social Reach

number

The number of people your ad was served to with social information. For example, if 3 people see an ad 2 times each that says a friend likes your Page, it counts as 3 social reaches.

social_reach

Social Spend

number

The total amount you've spent so far for your ads showed with social information. (ex: Jane Doe likes this).

social_spend

Spend

number

The total amount you've spent so far.

spend

Start Trial Total (Action)

number

Action count for Start Trial Total.

conversion_action_start_trial_total

Start Trial Website (Action)

number

Action count for Start Trial Website.

conversion_action_start_trial_website

Store Visits (action)

number

The number of store visits within the default attribution window.

store_visit_actions

Submit Application Mobile App (Action)

number

Action count for Submit Application Mobile App.

conversion_action_submit_application_mobile_app

Submit Application Offline (Action)

number

Action count for Submit Application Offline.

action_submit_application_offline

Submit Application on Facebook (Action)

number

Action count for Submit Application on Facebook.

action_submit_application_on_facebook

Submit Application Website (Action)

number

Action count for Submit Application Website.

conversion_action_submit_application_website

Subscribe (Action)

number

Action count for Subscribe.

action_subscribe

Unique Actions

number

The number of actions taken on your ad, Page, app or event after your ad was served to someone, even if they did not click on it. Actions include Page likes, app installs, conversions, event responses and more. For example, 2 Page likes and 2 comments would be counted as 4 actions.

unique_actions

Unique Clicks

number

The total number of unique people who have clicked on your ad. For example, if 3 people click on the same ad 5 times, it will count as 3 unique clicks.

unique_clicks

Unique CTR

number

The number of people who clicked on your ad divided by the number of people you reached. For example, if you received 20 unique clicks and your ad was served to 1,000 unique people, your unique click-through rate would be 2%.

unique_ctr

Unique Impressions

number

The number of individuals the ad was served to on the site.

unique_impressions

Unique Lead (Forms)

number

The unique number of form responses submitted after people clicked on an ad that includes an instant form.

uaction_leadgen_other

Unique Link Clicks CTR

number

Unique click-through rate for clicks to link. The number of people who clicked on the link in your ad that directs people off Facebook divided by the number of people you reached. Example: if you received 20 unique clicks to link and your ad was shown to 1,000 unique people, your unique click-through rate would be 2%.

unique_link_clicks_ctr

Unique Social Clicks

number

The number of individuals who clicked this ad while it had social context.

unique_social_clicks

Unique Social Impressions

number

The number of people the ad was served to with social context.

unique_social_impressions

Video 30 Sec Watched Actions

number

This shows the number of total views of at least 30 seconds or to the end of your video, whichever occurs first.

video_30_sec_watched_actions

Video Complete Watched Actions

number

This shows the number of total views of at least 30 seconds or to the end of your video, whichever occurs first.

video_complete_watched_actions

Video P100 Watched Actions

number

The number of times your video was viewed to 100% of its length, including views that skipped to this point.

video_p100_watched_actions

Video P25 Watched Actions

number

The number of times your video was viewed to 25% of its length, including views that skipped to this point.

video_p25_watched_actions

Video P50 Watched Actions

number

The number of times your video was viewed to 50% of its length, including views that skipped to this point.

video_p50_watched_actions

Video P75 Watched Actions

number

The number of times your video was viewed to 75% of its length, including views that skipped to this point.

video_p75_watched_actions

Video P95 Watched Actions

number

The number of times your video was viewed to 95% of its length, including views that skipped to this point.

video_p95_watched_actions

Video Play (action)

number

action_video_play

Video Plays (unique action)

number

uaction_video_play

Video Thurplay Watched Actions

number

This shows the number of total views of at least 10 seconds or to the end of your video, whichever occurs first.

video_thruplay_watched_actions

Video View (action)

number

action_video_view

Video Views (unique action)

number

uaction_video_view

Website Purchase ROAS

number

The total return on ad spend (ROAS) value from website purchases. This is based on the value of all conversions recorded by the Facebook pixel on your website and attributed to your ads

website_purchase_roas_offsite_conversion_fb_pixel_purchase

Frequently Asked Questions

Why does my data not match with the Facebook Ads platform UI?

Archived campaigns

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.