Marketing API Version

Ad

Overview

An ad object contains the data necessary to visually display an ad and associate it with a corresponding ad set. Each ad is associated with an ad set and all ads in a set have the same daily or lifetime budget, schedule, and targeting. Creating multiple ads in each ad set will let us optimize their delivery based on variations in images, links, video, text or placements.

Reading

An ad object contains the data necessary to visually display an ad and associate it with a corresponding ad set.

Permissions

Developers usually request these permissions for this endpoint:
  • ads_management
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

This endpoint doesn't have any parameters.

Fields

FieldDescription

id

numeric string

The ID of this ad.

account_id

numeric string

The ID of the ad account that this ad belongs to.

ad_review_feedback

The review feedback for this ad after it is reviewed.

adlabels

Ad labels associated with this ad

adset

Ad set that contains this ad

adset_id

numeric string

ID of the ad set that contains the ad

bid_amount

int32

Bid amount for this ad which will be used in auction instead of the ad set bid_amount, if specified. Any updates to the ad set bid_amount will overwrite this value with the new ad set value.

bid_info

map<string, unsigned int32>

A dictionary of {objective}:{value} that you place on your bid, based on the bid_type of ad set.
Values are defined in your currency's minimum denomination:
For bid_type=CPM, bid_info={'IMPRESSIONS':<value>}
For bid_type=CPC, bid_info={'CLICKS':<value>}
For bid_type=ABSOLUTE_OCPM, bid_info={'ACTIONS':<value>, 'REACH':<value>, 'CLICKS':<value>, 'SOCIAL':<value>}
For bid_type=CPA, bid_info={'ACTIONS':<value>}

bid_type

enum {CPC, CPM, MULTI_PREMIUM, ABSOLUTE_OCPM, CPA}

Bid type

campaign

Ad campaign that contains this ad

campaign_id

numeric string

ID of the ad campaign that contains this ad

configured_status

enum {ACTIVE, PAUSED, DELETED, ARCHIVED}

The configured status of the ad. Prefer using 'status' instead of this.

conversion_specs

Conversion specs

created_time

datetime

Created time

creative

This field is required for create. The ID of the ad creative to be used by this ad. You can read more about creatives here. You should supply the ID within an object as follows:

{"creative_id": <CREATIVE_ID>}

effective_status

enum {ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ARCHIVED, ADSET_PAUSED}

The effective status of the ad. The status could be effective either because of its own status, or the status of its parent units.

last_updated_by_app_id

id

Last Updated By App ID

name

string

Name of the ad.

recommendations

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

status

enum {ACTIVE, PAUSED, DELETED, ARCHIVED}

The configured status of the ad. The field returns the same value as 'configured_status', and is the suggested one to use.

tracking_specs

Tracking specs

updated_time

datetime

Updated time

Edges

EdgeDescription

adcreatives

Creative associated with this ad

insights

Insights on advertising performance of this ad

keywordstats

Stats of keywords of this ad

previews

Preview of the ad

reachestimate

The reach estimate for this ad

targetingsentencelines

The targeting description sentence for this ad

Validation Rules

ErrorDescription
100Invalid parameter
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.
274The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API
272This Ads API call requires the user to be admin of the application
273This Ads API call requires the user to be admin of the ad account
278Reading advertisements requires an access token with the extended permission ads_read

Creating

Creating an ad requires both an ad set and an ad creative to have been created first. After those objects are created, you may create ads both synchronously and asynchronously, both ways are described below.

Ads are in pending state after creation until they are approved (or rejected). Once an ad is approved, it will be in a running state. If you would like an ad to not run after approval, you can create the ad in a paused set, and then resume the set when you are ready to run the ad.

Synchronous Ad Creation

The synchronous method of ad creation creates one ad at a time. To create an ad object:

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdFields;

$data = array(
  AdFields::NAME => 'My Ad',
  AdFields::ADSET_ID => <AD_SET_ID>,
  AdFields::CREATIVE => array(
    'creative_id' => <CREATIVE_ID>,
  ),
);

$ad = new Ad(null, 'act_<AD_ACCOUNT_ID>');
$ad->setData($data);
$ad->create(array(
  Ad::STATUS_PARAM_NAME => Ad::STATUS_PAUSED,
));
from facebookads.adobjects.ad import Ad

ad = Ad(parent_id='act_<AD_ACCOUNT_ID>')
ad[Ad.Field.name] = 'My Ad'
ad[Ad.Field.adset_id] = <AD_SET_ID>
ad[Ad.Field.creative] = {
    'creative_id': <CREATIVE_ID>,
}
ad.remote_create(params={
    'status': Ad.Status.paused,
})
Ad ad = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAd()
  .setName("My Ad")
  .setAdsetId(<AD_SET_ID>)
  .setCreative(
    new AdCreative()
      .setFieldId(<CREATIVE_ID>)
  )
  .setStatus(Ad.EnumStatus.VALUE_PAUSED)
  .execute();
curl \
  -F 'name=My Ad' \
  -F 'adset_id=<AD_SET_ID>' \
  -F 'creative={"creative_id":"<CREATIVE_ID>"}' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/act_<AD_ACCOUNT_ID>/ads

Asynchronous ad creation

Asynchronous ad creation allows you to create multiple ads at a time asynchronously. You create a request and receive a notification when all the ads in the request have been created. To create an ad object asynchronously, make an HTTP POST call to

 https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/asyncadrequestsets

with the following fields:

NameTypeDescriptionRequired

name

string

Name of the set that contains these async requests for creating ads.

yes

ad_specs

array of ad specs

Ads can be created for different ad sets inside the current ad account. For images in the ad's creative, the best practice is to upload the image using the API https://graph.facebook.com/<API_VERSION>/ act_<AD_ACCOUNT_ID>/adimages, and then provide the image_hash in the ad spec. Creative names are unique per adaccount, therefore in case you are using the same image across all ads, make sure to update the names for each of the images when uplaoding them.
We don’t support image_file inside ad_specs.

yes

notification_uri

string

When async jobs of creating ads are all done, this URI will be used to notify the caller with POST action and the id of this set.

no

notification_mode

string

Different ways to receive notification. Following are valid values:
OFF – No need to send notification
ON_COMPLETE – Send notification when the whole set is done.

no



For more information on checking status, updating, deleting asynchronous request sets, please see managing asynchronous requests.

Limits

The following are the maximum number of ads per object.

LimitValue

Maximum number of ads in a regular ad account

5000 non-deleted ads

Maximum number of ads in a bulk ad account

50000 non-deleted ads

Maximum number of ads in an ad set

50 non-deleted ads

Maximum number of archived ads in an ad account

50k archived ads

Examples

Creating an offsite ad

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdCreativeFields;
use FacebookAds\Object\Fields\AdFields;

// First, upload the ad image that you will use in your ad creative
// Please refer to Ad Image Create for details.

// Then, use the image hash returned from above
$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');
$creative->setData(array(
  AdCreativeFields::TITLE => 'My Test Creative',
  AdCreativeFields::BODY => 'My Test Ad Creative Body',
  AdCreativeFields::OBJECT_URL => 'https://www.facebook.com/facebook',
  AdCreativeFields::IMAGE_HASH => '<IMAGE_HASH>',
));

// Finally, create your ad along with ad creative.
// Please note that the ad creative is not created independently, rather its
// data structure is appended to the ad group
$ad = new Ad(null, 'act_<AD_ACCOUNT_ID>');
$ad->setData(array(
  AdFields::NAME => 'My Ad',
  AdFields::ADSET_ID => <AD_SET_ID>,
  AdFields::CREATIVE => $creative,
));
$ad->create(array(
  Ad::STATUS_PARAM_NAME => Ad::STATUS_PAUSED,
));
from facebookads.adobjects.ad import Ad
from facebookads.adobjects.adcreative import AdCreative

# First, upload the ad image that you will use in your ad creative
# Please refer to Ad Image Create for details.

# Then, use the image hash returned from above
creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.title] = 'My Test Creative'
creative[AdCreative.Field.body] = 'My Test Ad Creative Body'
creative[AdCreative.Field.object_url] = 'https://www.facebook.com/facebook'
creative[AdCreative.Field.image_hash] = '<IMAGE_HASH>'

# Finally, create your ad along with ad creative.
# Please note that the ad creative is not created independently, rather its
# data structure is appended to the ad group
ad = Ad(parent_id='act_<AD_ACCOUNT_ID>')
ad[Ad.Field.name] = 'My Ad'
ad[Ad.Field.adset_id] = <AD_SET_ID>
ad[Ad.Field.creative] = creative
ad.remote_create(params={
    'status': Ad.Status.paused,
})
// First, upload the ad image that you will use in your ad creative
curl \
-F "image.jpg=@myimage.jpg" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adimages"

// Then, create an ad creative by referencing the image hash returned in the previous call
curl \
-F "name=sample creative" \ 
-F "title=hello world" \
-F "body=hi i'm an ad" \
-F "object_url=www.facebook.com" \ 
-F "image_hash=<IMAGE_HASH>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adcreatives"

  // Finally, create your ad by referencing the ad creative. 
curl \
-F "name=my ad" \
-F "adset_id=<AD_SET_ID>" \
-F "creative={'creative_id':<AD_CREATIVE_ID>}" \
-F "status=PAUSED" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ads"

// Asynchronous creation.
curl \
-F "name=testasyncset" \
-F "ad_specs=
[{'name':'name 1', 
  'adset_id':'<AD_SET_ID>', 
  'creative':{'creative_id':<AD_CREATIVE_ID>}},
{'name':'name 2', 
  'adset_id':'<AD_SET_ID>',  
  'creative':{'creative_id':<AD_CREATIVE_ID>}}]" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/asyncadrequestsets"

Specifying you want to redownload the details of an ad upon creation

from facebookads.adobjects.ad import Ad

ad = Ad(parent_id='act_<AD_ACCOUNT_ID>')
ad[Ad.Field.name] = 'My Ad'
ad[Ad.Field.adset_id] = <AD_SET_ID>
ad[Ad.Field.creative] = {'creative_id': <CREATIVE_ID>}
ad[Ad.Field.redownload] = True
ad.remote_create(params={
    'status': Ad.Status.paused,
})
curl \
-F "name=my ad" \
-F "adset_id=<AD_SET_ID>" \
-F "creative={'creative_id':<AD_CREATIVE_ID>}" \
-F "redownload=true" \
-F "status=PAUSED" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ads"



You can make a POST request to ads edge from the following paths:
When posting to this edge, an Ad will be created.

Permissions

Developers usually request these permissions for this endpoint:
  • ads_management

Parameters

NameDescription
adlabels
list<Object>

Ad labels associated with this ad

adset_id
unsigned int32

The ID of the ad set, required on creation.

bid_amount
integer

Bid amount for this ad which will be used in auction instead of the ad set bid_amount, if specified. Any updates to the ad set bid_amount will overwrite this value with the new ad set value.

creative
AdCreative

This field is required for create. The ID of the ad creative to be used by this ad. You can read more about creatives here. You should supply the ID within an object as follows:

{"creative_id": <CREATIVE_ID>}

RequiredSupports Emoji
date_format
string

The format of the date.

display_sequence
unsigned int32

The sequence of the ad within the same campaign

execution_options
list<enum{validate_only, synchronous_ad_review, include_recommendations}>
Default value: Set

An execution setting
validate_only: when this option is specified, the API call will not perform the mutation but will run through the validation rules against values of each field.
include_recommendations: this option cannot be used by itself. When this option is used, recommendations for ad object's configuration will be included. A separate section recommendations will be included in the response, but only if recommendations for this specification exist.
synchronous_ad_review: this option should not be used by itself. It should always be specified with validate_only. When these options are specified, the API call will perform Ads Integrity validations, which include message language checking, image 20% text rule, and so on, as well as the validation logics.
If the call passes validation or review, response will be {"success": true}. If the call does not pass, an error will be returned with more details. These options can be used to improve any UI to display errors to the user much sooner, e.g. as soon as a new value is typed into any field corresponding to this ad object, rather than at the upload/save stage, or after review.

name
string

Name of the ad.

Required
redownload
boolean

Set this value to true and the API will respond with all fields instead of just id.

status
enum{ACTIVE, PAUSED, ARCHIVED, DELETED}

Only ACTIVE and PAUSED are valid during creation. Other statuses can be used for update. When an ad is created, it will first go through ad review, and will have the ad status PENDING_REVIEW before it finishes review and reverts back to your selected status of ACTIVE or PAUSED. During testing, it is recommended to set ads to a PAUSED status so as to not incur accidental spend.

tracking_specs
Object

Tracking specs

Return Type

Struct {
id: numeric string,
success: bool,
}
You can make a POST request to leads edge from the following paths:
When posting to this edge, an Ad will be created.

Parameters

NameDescription
end_time
datetime

Leads created before end_time will be exported

start_time
datetime

Leads created after start_time will be exported

Return Type

Struct {
report_run_id: numeric string,
}
You may perform a POST request to the following edge from this node:

Validation Rules

ErrorDescription
100Invalid parameter
2615Invalid call to update this adaccount
300Edit failure
272This Ads API call requires the user to be admin of the application
2626The request for a reach frequency campaign has failed.
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.
294Managing advertisements requires an access token with the extended permission for ads_management
500Message contains banned content
380There was a problem uploading your thumbnail file. Please try again.
2625The request for a reach frequency campaign is invalid.

Updating

You can update certain fields of an ad:

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdFields;

$ad = new Ad($ad_id);
$ad->update(array(
  AdFields::NAME => 'New Ad Name',
));
from facebookads.objects import Ad

ad_id = <AD_ID>
ad = Ad(ad_id)
ad[Ad.Field.name] = 'New Ad Name'
ad.remote_update()
curl \
-F "name=New Ad Name" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_ID>"

You can use any of the fields you used in ad creation, including status and execution_options, except adset_id and social_prefs.

An ad with ARCHIVED as status has only two fields alterable: name and status, and the latter can only be changed to DELETED.

An ad with DELETED as status can only have its name changed.

Ads of an ad set which has non-empty creative_sequence cannot be changed to PAUSED, ARCHIVED, or DELETED status.

Examples

Updating the name of an ad

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdFields;

$ad = new Ad(<AD_ID>);
$ad->{AdFields::NAME} = 'New Ad Name';
$ad->update();
from facebookads.adobjects.ad import Ad

ad = Ad(<AD_ID>)
ad[Ad.Field.name] = 'New Ad Name'
ad.remote_update()
new Ad(<AD_ID>, context).update()
  .setName("New Ad Name")
  .execute();
curl \
-F "name=newname" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_ID>"

Updating the name of an ad and redownloading the ad's information

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdFields;

$ad = new Ad(<AD_ID>);
$ad->setData(array(
  AdFields::NAME => 'New Ad Name',
));
$ad->update(array(
  'redownload' => true,
));
from facebookads.adobjects.ad import Ad

ad = Ad(<AD_ID>)
ad[Ad.Field.name] = 'New Ad Name'
ad['redownload'] = True
ad.remote_update()
new Ad(<AD_ID>, context).update()
  .setName("New Ad Name")
  .setRedownload(true)
  .execute();
curl \
-F "name=newname" \
-F "redownload=true" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_ID>"

Updating the status of an existing ad

use FacebookAds\Object\Ad;

$ad = new Ad(<AD_ID>);
$ad->update(array(
  Ad::STATUS_PARAM_NAME => Ad::STATUS_PAUSED,
));
from facebookads.adobjects.ad import Ad

ad = Ad(<AD_ID>)
ad.remote_update(params={
    'status': Ad.Status.paused,
})
new Ad(<AD_ID>, context).update()
  .setStatus(Ad.EnumStatus.VALUE_PAUSED)
  .execute();
curl \
-F "status=ADGROUP_PAUSED" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_ID>"



You can update an Ad by making a POST request to /{ad_id}.

Permissions

Developers usually request these permissions for this endpoint:
  • ads_management
  • manage_pages
  • business_management

Parameters

NameDescription
adlabels
list<Object>

Ad labels associated with this ad

adset_id
unsigned int32

The ID of the ad set, required on creation.

bid_amount
integer

Bid amount for this ad which will be used in auction instead of the ad set bid_amount, if specified. Any updates to the ad set bid_amount will overwrite this value with the new ad set value.

creative
AdCreative

This field is required for create. The ID of the ad creative to be used by this ad. You can read more about creatives here. You should supply the ID within an object as follows:

{"creative_id": <CREATIVE_ID>}

Supports Emoji
display_sequence
unsigned int32

The sequence of the ad within the same campaign

execution_options
list<enum{validate_only, synchronous_ad_review, include_recommendations}>
Default value: Set

An execution setting
validate_only: when this option is specified, the API call will not perform the mutation but will run through the validation rules against values of each field.
include_recommendations: this option cannot be used by itself. When this option is used, recommendations for ad object's configuration will be included. A separate section recommendations will be included in the response, but only if recommendations for this specification exist.
synchronous_ad_review: this option should not be used by itself. It should always be specified with validate_only. When these options are specified, the API call will perform Ads Integrity validations, which include message language checking, image 20% text rule, and so on, as well as the validation logics.
If the call passes validation or review, response will be {"success": true}. If the call does not pass, an error will be returned with more details. These options can be used to improve any UI to display errors to the user much sooner, e.g. as soon as a new value is typed into any field corresponding to this ad object, rather than at the upload/save stage, or after review.

name
string

Name of the ad.

redownload
boolean

Set this value to true and the API will respond with all fields instead of just id.

status
enum{ACTIVE, PAUSED, ARCHIVED, DELETED}

Only ACTIVE and PAUSED are valid during creation. Other statuses can be used for update. When an ad is created, it will first go through ad review, and will have the ad status PENDING_REVIEW before it finishes review and reverts back to your selected status of ACTIVE or PAUSED. During testing, it is recommended to set ads to a PAUSED status so as to not incur accidental spend.

tracking_specs
Object

Tracking specs

Return Type

Struct {
success: bool,
}
You may perform a POST request to the following edge from this node:

Validation Rules

ErrorDescription
100Invalid parameter
2615Invalid call to update this adaccount
300Edit failure
272This Ads API call requires the user to be admin of the application
2626The request for a reach frequency campaign has failed.
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.
294Managing advertisements requires an access token with the extended permission for ads_management
500Message contains banned content
380There was a problem uploading your thumbnail file. Please try again.
2625The request for a reach frequency campaign is invalid.

Deleting

Deleting an ad

use FacebookAds\Object\Ad;

$ad = new Ad(<AD_ID>);
$ad->delete();
from facebookads.adobjects.ad import Ad

ad = Ad(<AD_ID>)
ad.remote_delete()
new Ad(<AD_ID>, context).update()
  .setStatus(Ad.EnumStatus.VALUE_DELETED)
  .execute();
curl \
-F "status=DELETED" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_ID>"

Ads of an ad set which has non-empty creative_sequence cannot be deleted.

You can also delete the value of any of the optional fields of an ad by updating the value to an empty value.

You can delete an Ad by making a DELETE request to /{ad_id}.

Permissions

Developers usually request these permissions for this endpoint:
  • ads_management
  • manage_pages
  • publish_pages
  • business_management

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {
success: bool,
}
You may perform a DELETE request to the following edge from this node:

Validation Rules

ErrorDescription
2615Invalid call to update this adaccount
100Invalid parameter
2626The request for a reach frequency campaign has failed.