Facebook Ads - Structure

Facebook

v19.0

https://developers.facebook.com/docs/marketing-apis/

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

Marketing API: February 4th, 2025

12am, 12pm / Real Time

N/A

Account Id

String

account_id

Account Name

String

name

Account Status

String

account_status

Age

Number

age

Spend Cap

Number

spend_cap

Created Time

Date

created_time

Amount Spent

Number

amount_spent

Balance

Number

balance

Currency

String

currency

Account Id

String

account_id

Campaign Id

String

id

Campaign Name

String

name

Created Time

String

created_time

Updated Time

String

updated_time

Start Time

String

start_time

Stop Time

String

stop_time

Objective

String

objective

Can Create Brand Lift Study

String

can_create_brand_lift_study

Can Use Spend Cap

String

can_use_spend_cap

Configured Status

String

configured_status

Effective Status

String

effective_status

Status

String

status

Budget Rebalance Flag

String

budget_rebalance_flag

Daily Budget

Number

daily_budget

Budget Remaining

Number

budget_remaining

Lifetime Budget

Number

lifetime_budget

Buying Type

String

buying_type

Spend Cap

Number

spend_cap

Account Id

Number

account_id

Custom Audience ID

Number

id

Custom Audience Name

String

name

Approximate Count

Number

The Approximate Count of the CustomAudience (The average from the upper and lower Bounds).

approximate_count

Approximate Count (Lower Bound)

Number

The Lower Bound of the Approximate Count of the CustomAudience.

approximate_count_lower_bound

Approximate Count (Upper Bound)

Number

The Upper Bound of the Approximate Count of the CustomAudience.

approximate_count_upper_bound

Customer File Source

String

customer_file_source

Delivery Status

JSON

delivery_status

Description

String

description

External Event Source

JSON

external_event_source

Is Value Based

String

is_value_based

Lookalike Audience Ids

JSON

lookalike_audience_ids

Lookalike Spec

JSON

lookalike_spec

Operation Status

JSON

operation_status

Opt Out Link

String

opt_out_link

Pixel Id

String

pixel_id

Retention Days

Number

retention_days

Time Created

Number

time_created

Time Updated

Number

time_updated

Data Source

JSON

data_source

Permission for Actions

JSON

permission_for_actions

Sharing Status

JSON

sharing_status

SubType

String

subtype

Account ID

String

account_id

Campaign ID

String

campaign_id

Adset ID

String

adset_id

Ad ID

String

id

Ad Name

String

name

Configured Status

String

configured_status

Effective Status

String

effective_status

Status

String

status

Created Time

Date

created_time

Updated Time

Date

updated_time

Last Updated by App Id

String

last_updated_by_app_id

Creative

JSON

creative

Source Ad ID

String

source_ad_id

Preview Shareable Link

String

preview_shareable_link

Pixel ID

String

id

Pixel Name

String

name

Is Created By Business

String

is_created_by_business

Is Unavailable

String

is_unavailable

Last Fired Time

String

last_fired_time

Owner Ad Account

String

owner_ad_account

Owner Business

String

owner_business

First Party Cookie Status

String

first_party_cookie_status

Enable Automatic Matching

String

enable_automatic_matching

Data Use Setting

String

data_use_setting

Creator

String

creator

Creation Time

String

creation_time

Can Proxy

String

can_proxy

Automatic Matching Fields

JSON

automatic_matching_fields

Stats Aggregation

String

stats_aggregation

Stats Start Time

String

stats_start_time

Stats Value

String

stats_event_value

Stats Count

Number

stats_event_count

Account Id

String

The Facebook Account Id

account_id

Campaign Id

String

The Facebook Campaign Id

campaign_id

Id

String

The Facebook Adset Id

id

Name

String

The Facebook Adset Name

name

Created Time

String

The Adset Created Time

created_time

Updated Time

String

The Adset Updated Time

updated_time

Daily Budget

Number

The Daily Budget for the Adset

daily_budget

Lifetime Budget

Number

The Lifetime Budget for the Adset

lifetime_budget

Budget Remaining

Number

The Budget Remaining for the Adset

budget_remaining

Start Time

String

The Start Time for the Adset

start_time

End Time

String

The End Time for the Adset

end_time

Adset Schedule

JSON

The Schedule for the Adset

adset_schedule

Bid Adjustments

JSON

Map of bid adjustment types to values

bid_adjustments

Bid Amount

Number

The Bid Amount for the Adset

bid_amount

Bid Constraints

JSON

Choose bid constraints for ad set to suit your specific business goals. It usually works together with bid_strategy field

bid_constraints

Bid Info

JSON

Map of bid objective to bid value.

bid_info

Bid Strategy

String

Bid strategy for this ad set when you use AUCTION as your buying type

bid_strategy

Billing Event

String

The Billing Event for the Adset

billing_event

configured_status

String

The Configured Status for the Adset

configured_status

Creative Sequence

JSON

Order of the adgroup sequence to be shown to users

creative_sequence

Daily Min Spend Target

Number

The Daily Min Spend Target for the Adset

daily_min_spend_target

Daily Spend Cap

Number

The Daily Spend Cap for the Adset

daily_spend_cap

destination_type

String

Destination Type for the Adset

destination_type

Effective Status

String

Effective Status for the Adset

effective_status

Frequency Control Specs

JSON

Frequency Control Specs

frequency_control_specs

Instagram Actor Id

String

Instagram Actor Id

instagram_actor_id

Is Dynamic Creative

String

Is the Creative Dynamic (returns True/False)

is_dynamic_creative

Issues Info

JSON

Issues Info

issues_info

Learning Stage Info

JSON

The Learning Stage Information for an Adset

learning_stage_info

Lifetime Impressions

Number

Lifetime impressions. Available only for campaigns with buying_type=FIXED_CPM

lifetime_imps

Lifetime Min Spend Target

Number

Lifetime minimum spend target of the ad set defined in your account currency. To use this field, lifetime budget must be specified in the Campaign. This target is not a guarantee but our best effort.

lifetime_min_spend_target

Lifetime Spend Cap

Number

Lifetime spend cap of the ad set defined in your account currency. To use this field, lifetime budget must be specified in the Campaign.

lifetime_spend_cap

Multi Optimization Goal Weight

type

multi_optimization_goal_weight

multi_optimization_goal_weight

Optimization Goal

String

Which optimization goal this ad set is using

optimization_goal

Pacing Type

JSON

Defines the pacing type, standard or using ad scheduling

pacing_type

Promoted Object

JSON

The object this ad set is promoting across all its ads.

promoted_object

Recommendations

JSON

If there are recommendations for this ad set, this field includes them. Otherwise, will not be included in the response. This field is not included in redownload mode.

recommendations

Recurring Budget Semantics

String

If this field is true, your daily spend may be more than your daily budget while your weekly spend will not exceed 7 times your daily budget. More details explained in the Ad Set Budget document. If this is false, your amount spent daily will not exceed the daily budget. This field is not applicable for lifetime budgets.

recurring_budget_semantics

Review Feedback

String

Reviews for dynamic creative ad.

review_feedback

Reach/Frequency Prediciton Id

String

Reach and frequency prediction ID

rf_prediction_id

Source Adset Id

String

The source ad set that this ad set was copied from.

source_adset_id

Status

String

The status set at the ad set level. It can be different from the effective status due to its parent campaign. The field returns the same value as configured_status, and is the suggested one to use.

status

Targeting - Age Max

Number

Targeting Age Max

targeting_age_max

Targeting - Age Min

Number

Targeting Age Min

targeting_age_min

Targeting - App Install State

String

Targeting - App Install State

targeting_app_install_state

Targeting - Custom Audiences

JSON

Targeting - Custom Audiences

targeting_custom_audiences

Targeting - Geo Countries

JSON

Targeting - Geo Countries

targeting_geo_locations_countries

Targeting - Geo Markets

JSON

Targeting - Geo Markets

targeting_geo_locations_markets

Targeting - Geo Regions

JSON

Targeting - Geo Regions

targeting_geo_locations_regions

Targeting - Geo Cities

JSON

Targeting - Geo Cities

targeting_geo_locations_cities

Targeting - Geo Location Types

JSON

Targeting - Geo Cities

targeting_geo_locations_location_types

Targeting - Excluded Custom Audiences

JSON

Targeting - Excluded Custom Audiences

targeting_excluded_custom_audiences

Targeting - Platform Positions

JSON

Targeting - Platform Positions

targeting_platform_positions

Targeting - Device Platforms

JSON

Targeting - Device Platforms

targeting_device_platforms

Use New App Click

String

If set, allows Mobile App Engagement ads to optimize for LINK_CLICKS

use_new_app_click

Account Id

String

The Account Id Associated with the Ad Creative

account_id

Id

String

The Ad Creative Id

id

Name

String

The Ad Creative Name

name

Actor Id

String

The actor ID (Page ID) of this creative

actor_id

Ad Labels

JSON

Ad Labels associated with this creative. Used to group it with related ad objects.

adlabels

Applink Treatment

String

Used for Dynamic Ads. Specify what action should occur if a person clicks a link in the ad, but the business' app is not installed on their device. For example, open a webpage displaying the product, or open the app in an app store on the person's mobile device.

applink_treatment

Asset Feed Spec

JSON

Used for Dynamic Creative to automatically experiment and deliver different variations of an ad's creative. Specifies an asset feed with multiple images, text and other assets used to generate variations of an ad. Formatted as a JSON string.

asset_feed_spec

Authorization Category

String

Specifies whether ad was configured to be labeled as a political ad or not. See Facebook Advertising Policies. This field cannot be used for Dynamic Ads.

authorization_category

Body

JSON

The body of the ad. Not supported for video post creatives

body

Branded Content Sponser Page Id

String

ID for page representing business which runs Branded Content ads.

branded_content_sponsor_page_id

Bundle Folder Id

String

The Dynamic Ad's bundle folder ID

bundle_folder_id

Call to Action Type

String

Type of call to action button in your ad. This determines the button text and header text for your ad

call_to_action_type

Categorization Criteria

String

The Dynamic Category Ad's categorization field, e.g. brand

categorization_criteria

Category Media Source

String

The Dynamic Ad's rendering mode for category ads

category_media_source

Destination Set Id

String

The ID of the Product Set for a Destination Catalog that will be used to link with Travel Catalogs

destination_set_id

Dynamic Ad Voice

String

Used for Store Traffic Objective inside Dynamic Ads. Allows you to control the voice of your ad. If set to DYNAMIC, page name and profile picture in your ad post come from the nearest page location. If set to STORY_OWNER, page name and profile picture in your ad post come from the main page location.

dynamic_ad_voice

Effectie Authorization Category

String

Specifies whether ad is a political ad or not.

effective_authorization_category

Effective Instagram Media Id

String

The ID of an Instagram post to use in an ad

effective_instagram_media_id

Effective Instagram Story Id

String

Used for Instagram Ads. The ID of an Instagram post to display as an Instagram ad.

effective_instagram_story_id

Effective Object Story Id

String

The ID of a page post to use in an ad, regardless of whether it's an organic or unpublished page post

effective_object_story_id

Enable Direct Install

String

Whether Direct Install should be enabled on supported devices

enable_direct_install

Enable Launch Instant App

String

Whether Instant App should be enabled on supported devices

enable_launch_instant_app

Image Url

String

A URL for the image for this creative. We save the image at this URL to the ad account's image library.

image_url

Instagram Actor Id

String

Used for Instagram Ads. Provide Instagram account ID used for running these ads.

instagram_actor_id

Instagram Permalink URL

String

URL for a post on Instagram you want to run as an ad. Also known as Instagram media.

instagram_permalink_url

Interactive Components Spec

JSON

Specification for all the interactive components that would show up on the ad

interactive_components_spec

Link Destination Display Url

String

Overwrites the display URL for link ads when object_url is set to a click tag

link_destination_display_url

Link OG Id

String

The Open Graph (OG) ID for the link in this creative if the landing page has OG tags

link_og_id

Link Url

String

Identify a specific landing tab on your Facebook page by the Page tab's URL.

link_url

Messenger Sponsered Message

JSON

Used for Messenger sponsored message. JSON string with message for this ad creative

messenger_sponsored_message

Object Id

String

ID for Facebook object being promoted with ads or relevant to the ad or ad type. For example a page ID if you are running ads to generate Page Likes.

object_id

Object Store Url

String

iTunes or Google Play of the destination of an app ad

object_store_url

Object Story Id

String

ID of a Facebook Page post to use in an ad. You can get this ID by querying the posts of the page.

object_story_id

Object Story Spec - Page Id

String

description

object_story_spec_page_id

Object Story Spec - Instagram Actor Id

String

The Instagram user account that the story will be posted to

object_story_spec_instagram_actor_id

Object Story Spec - Link Data

JSON

The Spec for a link page post of carousel ad.

object_story_spec_link_data

Object Story Spec - Photo Data

JSON

The spec for a photo page post.

object_story_spec_photo_data

Object Story Spec - Tempalte Data

JSON

The spec for a template link page post as used in Dynamic Product Ads.

object_story_spec_template_data

Object Story Spec - Text Data

JSON

The spec for a text page post.

object_story_spec_text_data

Object Story Spec - Video Data

JSON

The spec for a video page post.

object_story_spec_video_data

Object Type

String

The type of Facebook object you want to advertise.

object_type

Place Page Set Id

String

The ID of the page set for this creative.

place_page_set_id

Platform Customizations

JSON

Use this field to specify the exact media to use on different Facebook placements. You can currently use this setting for images and videos. Facebook replaces the media originally defined in ad creative with this media when the ad displays in a specific placements. For example, if you define a media here for instagram, Facebook uses that media instead of the media defined in the ad creative when the ad appears on Instagram.

platform_customizations

Playable Asset Id

String

The ID of the playable asset in this creative.

playable_asset_id

Portrait Customizations

JSON

This field describes the rendering customizations selected for portrait mode ads like IG Stories, FB Stories, IGTV, etc.

portrait_customizations

Product Set Id

String

Used for Dynamic Ad. An ID for a product set, which groups related products or other items being advertised.

product_set_id

Recommender Settings

JSON

Used for Dynamic Ads. Settings to display Dynamic ads based on product recommendations.

recommender_settings

Referral Id

String

The ID of Referral Ad Configuration in this creative.

referral_id

Source Instagram Media Id

String

The ID of an Instagram post for creating ads.

source_instagram_media_id

Status

String

The status of the creative.

status

Template Url

String

Used for Dynamic Ads when you want to use third-party click tracking.

template_url

Template Url Spec

JSON

Used for Dynamic Ads when you want to use third-party click tracking.

template_url_spec

Thumbnail Url

String

URL for a thumbnail image for this ad creative.

thumbnail_url

Title

String

Title for link ad, which does not belong to a page.

title

Url Tags

String

A set of query string parameters which will replace or be appended to urls clicked from page post ads, message of the post, and canvas app install creatives only

url_tags

Use Page Actor Override

String

Used for App Ads. If true, we display the Facebook page associated with the app ads.

use_page_actor_override

Video Id

String

Facebook object ID for video in this ad creative.

video_id

Account Id

string

The ad account that owns the image.

account_id

Created Time

type

Time the image was created.

created_time

Updated Time

type

Time the image was updated.

updated_time

Creatives

JSON

A list of ad creative IDs that this ad image is being used in. Not applicable for creatives using object_story_spec and a URL in the picture field.

creatives

Hash

String

The hash which uniquely identifies the image.

hash

Height

string

The height of the image.

height

Width

string

The width of the image.

width

Is Associated Creatives in Adgroups

string

Is Associated Creatives in Adgroups

is_associated_creatives_in_adgroups

Name

string

The filename of the image. The maximum length of this string is 100 characters.

name

Original Height

string

The height of the image that was originally uploaded.

original_height

Original Width

string

The width of the image that was originally uploaded.

original_width

Permalink URL

string

A permanent URL of the image to use in story creatives.

permalink_url

Status

string

Status of the image.

status

URL

string

A temporary URL which the image can be retrieved at. Do not use this URL in ad creative creation.

url

URL 128

string

A temporary URL pointing to a version of the image resized to fit within a 128x128 pixel box

url_128

Account Id

string

The ad account that owns the video.

account_id

Ad Breaks

JSON

Time offsets of ad breaks in milliseconds. Ad breaks are short ads that play within a video.

ad_breaks

Backdated Time

string

A user-specified time for when this object was created

backdated_time

Backdated Time Granularity

string

How accurate the backdated time is

backdated_time_granularity

Content Category

string

The content category of this video.

content_category

Content Tags

JSON

Tags that describe the contents of the video.

content_tags

Created Time

string

The time the video was initially published.

created_time

Custom Labels

JSON

Labels used to describe the video. Unlike content tags, custom labels are not published and only appear in insights data.

custom_labels

Description

string

The description of the Video.

description

Embed HTML

JSON

The HTML element that may be embedded in a Web page to play the video.

embed_html

Embeddable

string

Whether the video is embeddable

embeddable

Format

JSON

The different formats of the video.

format

From

string

The profile that created the video.

from

Icon

string

The icon that Facebook displays when videos are published to the feed.

icon

Length

number

Duration of this video in seconds.

length

Permalink URL

string

URL to the permalink page of the video.

permalink_url

Place

JSON

Place Info

place

Published

string

Whether a post about this video is published. The post is not scheduled, draft, or ads_post.

published

Scheduled Publish Time

string

The time that the video is scheduled to publish.

scheduled_publish_time

Source

string

A URL to the raw, playable video file.

source

Status

JSON

Object describing the status attributes of a video.

status

Title

string

The video title or caption.

title

Thumbnail Id (Preferred)

JSON

The Preferred Thumbnail Id for the video.

thumbnails_preferred_id

Thumbnail Height (Preferred)

JSON

The Preferred Thumbnail Height for the video.

thumbnails_preferred_height

Thumbnail Scale (Preferred)

JSON

The Preferred Thumbnail Scale for the video.

thumbnails_preferred_scale

Thumbnail URI (Preferred)

JSON

The Preferred Thumbnail URI for the video.

thumbnails_preferred_uri

Thumbnail Width (Preferred)

JSON

The Preferred Thumbnail Width for the video.

thumbnails_preferred_width

Universal Video Id

string

The publishers asset management code for this video.

universal_video_id

Updated Time

string

The last time the video or its caption was updated.

updated_time

Lifetime Min Spend Target

Number

Lifetime minimum spend target of the ad set defined in your account currency. To use this field, lifetime budget must be specified in the Campaign. This target is not a guarantee but our best effort.

lifetime_min_spend_target

Lifetime Spend Cap

Number

Lifetime spend cap of the ad set defined in your account currency. To use this field, lifetime budget must be specified in the Campaign.

lifetime_spend_cap

Multi Optimization Goal Weight

type

multi_optimization_goal_weight

multi_optimization_goal_weight

Optimization Goal

String

Which optimization goal this ad set is using

optimization_goal

Pacing Type

JSON

Defines the pacing type, standard or using ad scheduling

pacing_type

Promoted Object

JSON

The object this ad set is promoting across all its ads.

promoted_object

Recommendations

JSON

If there are recommendations for this ad set, this field includes them. Otherwise, will not be included in the response. This field is not included in redownload mode.

recommendations

Recurring Budget Semantics

String

If this field is true, your daily spend may be more than your daily budget while your weekly spend will not exceed 7 times your daily budget. More details explained in the Ad Set Budget document. If this is false, your amount spent daily will not exceed the daily budget. This field is not applicable for lifetime budgets.

recurring_budget_semantics

Review Feedback

String

Reviews for dynamic creative ad.

review_feedback

Reach/Frequency Prediciton Id

String

Reach and frequency prediction ID

rf_prediction_id

Source Adset Id

String

The source ad set that this ad set was copied from.

source_adset_id

Status

String

The status set at the ad set level. It can be different from the effective status due to its parent campaign. The field returns the same value as configured_status, and is the suggested one to use.

status

Targeting - Age Max

Number

Targeting Age Max

targeting_age_max

Targeting - Age Min

Number

Targeting Age Min

targeting_age_min

Targeting - App Install State

String

Targeting - App Install State

targeting_app_install_state

Targeting - Custom Audiences

JSON

Targeting - Custom Audiences

targeting_custom_audiences

Targeting - Geo Countries

JSON

Targeting - Geo Countries

targeting_geo_locations_countries

Targeting - Geo Markets

JSON

Targeting - Geo Markets

targeting_geo_locations_markets

Targeting - Geo Regions

JSON

Targeting - Geo Regions

targeting_geo_locations_regions

Targeting - Geo Cities

JSON

Targeting - Geo Cities

targeting_geo_locations_cities

Targeting - Geo Location Types

JSON

Targeting - Geo Cities

targeting_geo_locations_location_types

Targeting - Excluded Custom Audiences

JSON

Targeting - Excluded Custom Audiences

targeting_excluded_custom_audiences

Targeting - Platform Positions

JSON

Targeting - Platform Positions

targeting_platform_positions

Targeting - Device Platforms

JSON

Targeting - Device Platforms

targeting_device_platforms

Use New App Click

String

If set, allows Mobile App Engagement ads to optimize for LINK_CLICKS

use_new_app_click