Graph API Version

Ad

Contains information to display an ad and associate it an 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 an ad set helps optimize their delivery based on variations in images, links, video, text or placements.

Note that result returned by synchronous_ad_review does not represent the final decision made during full review of your ad.

Ads with Political Content

To increase transparency of ads on Facebook, we require advertisers running ads with political content to complete authorization. We will begin enforcing this in the next few weeks. You must also indicate that your ad has political content and provide the name of the funding source for the ad:

  • Your ad account must be authorized by a Page admin to run political ads for this Page. This is done by a Page admin on the Authorizations tab under Page Settings.

  • Ad account users must go through a verification process.

Ads with Page Mentions

With Facebook's ads tools such as Ads Manager or light-weight interfaces, you can create an ad with a Page Mention. This displays a link in your ad which opens an advertiser's Facebook page. We do not provide this functionality in Marketing API. If you try to create an ad with the API with a Page Mention it will succeed, however we will deliver the ad without the mention. Instead, use one of Facebook's ads tools.

Examples

Creating an 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,
})
curl \
  -F 'name=My Ad' \
  -F 'adset_id=<AD_SET_ID>' \
  -F 'creative={ 
    "title": "My Test Creative", 
    "body": "My Test Ad Creative Body", 
    "object_url": "https:\/\/www.facebook.com\/facebook", 
    "image_hash": "<IMAGE_HASH>" 
  }' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/ads

To create a political ad, provide authorization_category with the value POLITICAL in the creative field. For example:

curl \
-F 'status=ACTIVE' \
-F 'name=Test' \
-F 'adset_id=<id>' \
-F 'creative=
    "object_story_spec": {
        ...
    },
    "authorization_category": "POLITICAL"
}' \
-F 'access_token=<TOKEN>' \
https://graph.facebook.com/<VERSION>/<AD_ACCOUNT_ID>/ads 

See:

Reading

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

By ad ID

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

$ad = new Ad($ad_id);
$ad->read(array(
  AdFields::NAME,
));

// Output Ad name.
echo $ad->name;
from facebookads.objects import Ad

ad_id = <AD_ID>
ad = Ad(ad_id)
ad.remote_read(fields=[Ad.Field.name])
curl -G \
-d "fields=name" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_ID>"

By ad account

To read all ads from one ad account:

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\AdFields;

$account = new AdAccount($account_id);
$ads = $account->getAds(array(
  AdFields::NAME,
));

// Outputs names of Ads.
foreach ($ads as $ad) {
  echo $ad->name;
}
from facebookads.objects import AdAccount, Ad

account_id = 'act_<AD_ACCOUNT_ID>'
ad_account = AdAccount(account_id)
ad_iter = ad_account.get_ads(fields=[Ad.Field.name])
for ad in ad_iter:
    print ad[Ad.Field.name]
curl -G \
-d "fields=name" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ads"

By ad campaign

Read all ads from a campaign:

use FacebookAds\Object\Campaign;
use FacebookAds\Object\Fields\CampaignFields;

$campaign = new Campaign($campaign_id);
$ads = $campaign->getAds(array(
  AdFields::NAME,
));

// Outputs names of Ads.
foreach ($ads as $ad) {
  echo $ad->name;
}
from facebookads.objects import Campaign, Ad

campaign_id = <CAMPAIGN_ID>
campaign = Campaign(campaign_id)
ad_iter = campaign.get_ads(fields=[Ad.Field.name])
for ad in ad_iter:
    print ad[Ad.Field.name]
curl \
-F "fields=name" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<CAMPAIGN_ID>/ads"

By ad set

To read all ads from one ad set:

use FacebookAds\Object\AdSet;
use FacebookAds\Object\Fields\AdSetFields;

$adset = new AdSet($adset_id);
$ads = $adset->getAds(array(
  AdFields::NAME,
));

// Outputs names of Ads .
foreach ($ads as $ad) {
  echo $ad->name;
}
from facebookads.objects import AdSet, Ad

adset_id = <AD_SET_ID>
ad_set = AdSet(adset_id)
ad_iter = ad_set.get_ads(fields=[Ad.Field.name])
for ad in ad_iter:
    print ad[Ad.Field.name]
curl \
-F "fields=name" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_SET_ID>/ads"



Example

Graph API Explorer
GET v5.0/...?fields={fieldname_of_type_Ad} HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '...?fields={fieldname_of_type_Ad}',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "...?fields={fieldname_of_type_Ad}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "...?fields={fieldname_of_type_Ad}",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"...?fields={fieldname_of_type_Ad}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

ParameterDescription
date_preset
enum{today, yesterday, this_month, last_month, this_quarter, lifetime, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, last_week_mon_sun, last_week_sun_sat, last_quarter, last_year, this_week_mon_today, this_week_sun_today, this_year}

Date Preset

time_range
{'since':YYYY-MM-DD,'until':YYYY-MM-DD}

Time Range

since
datetime

A date in the format of "YYYY-MM-DD", which means from the beginning midnight of that day.

until
datetime

A date in the format of "YYYY-MM-DD", which means to the beginning midnight of the following day.

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.

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. Use status instead of this field.

created_time
datetime

Time when the ad was created.

creative

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

{"creative_id": <CREATIVE_ID>}
or creative spec as follow:

{"creative": {\"name\": \"<NAME>\", \"object_story_spec\": <SPEC>}}

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

The effective status of the ad. The status could be effective either because of its own status, or the status of its parent units. WITH_ISSUES is available for version 3.2 or higher. IN_PROCESS is available for version 4.0 or higher

issues_info

Issues for this ad that prevented it from delivering

last_updated_by_app_id
id

Indicates the app used for the most recent update of the ad.

name
string

Name of the ad.

preview_shareable_link
string

A link that enables users to preview ads in different placements

recommendations

If there are recommendations for this ad, this field includes them. Otherwise, it is not included in the response. Field not included in redownload mode.

source_ad

The source ad that this ad is copied from

source_ad_id
numeric string

The source ad id that this ad is copied from

status
enum {ACTIVE, PAUSED, DELETED, ARCHIVED}

The configured status of the ad. The field returns the same value as configured_status. Use this field, instead of configured_status.

tracking_specs

With tracking specs, you log actions taken by people on your ad. This field takes arguments identical to action spec. See Tracking and Conversion Specs.

updated_time
datetime

Time when this ad was updated.

Edges

EdgeDescription

Creative associated with this ad

Ad rules that govern this ad - by default, this only returns rules that either directly mention the ad by id or indirectly through the set entity_type

The copies of this ad

Leads submitted for this ad

Preview of the ad

The targeting description sentence for this ad

Validation Rules

ErrorDescription
100Invalid parameter
80004There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
80000There have been too many calls from this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
200Permissions error
278Reading advertisements requires an access token with the extended permission ads_read
1150An unknown error occurred.

Creating

Before you create an ad, you need an existing ad set and ad creative. You can create ads synchronously and asynchronously.

New ads are in pending state and do not run until Facebook approves or rejects them. After we approve an ad it runs. If you do not want an ad to automatically run after approval, create it and set it to paused, see ad set. Run the set when you are ready.

Synchronous Creation

Creates one ad at a time:

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();
ad_account = FacebookAds::AdAccount.get('act_<AD_ACCOUNT_ID>')
ad = ad_account.ads.create({
  name: 'My Ad',
  adset_id: <ADSET_ID>,
  creative: {
    creative_id: <CREATIVE_ID>,
  },
  status: 'PAUSED',
})
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.11/act_<AD_ACCOUNT_ID>/ads

Asynchronous Creation

Create multiple ads at a time asynchronously. Receive a notification when all the ads in the request exist. Make an HTTP POST to: https://graph.facebook.com/{API_VERSION}/act_{AD_ACCOUNT_ID}/asyncadrequestsets

Use these fields:

Field Description

name

type: string

Required.

Name of ad set for newly created ads.

ad_specs

type: array of ad specs

Required.

Ads can be created for different ad sets inside the current ad account. To use images in ad creative, provide image_hash in ad spec after you upload the image at https://graph.facebook.com/{API_VERSION}/act_{AD_ACCOUNT_ID}/adimages.
image_file inside ad_specs.

notification_uri

type: string

Optional.

Async job completed. This URI notifies the caller with a POST and ad set id.

notification_mode

type: string

Optional.

Notification mode:
OFF – No notification
ON_COMPLETE – Send notification when all ads for set created.



For information on asynchronous request sets, see Asynchronous Requests.

Limits

These are the maximum number of ads per object:

Limit Value

Ads in regular ad account

5000 non-deleted ads

Ads in bulk ad account

50000 non-deleted ads

Ads in an ad set

50 non-deleted ads

Archived ads in an ad account

100,000 archived ads

Examples

Download details for an ad:

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(
  'redownload' => 1,
));
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,
})
Ad ad = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAd()
  .setName("My Ad")
  .setAdsetId(<AD_SET_ID>)
  .setCreative(
    new AdCreative()
      .setFieldId(<CREATIVE_ID>)
  )
  .setRedownload(true)
  .execute();
String ad_id = ad.getId();
curl \
  -F 'name=My Ad' \
  -F 'adset_id=<AD_SET_ID>' \
  -F 'creative={"creative_id":"<CREATIVE_ID>"}' \
  -F 'redownload=1' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/ads



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

Parameters

ParameterDescription
adset_id
numeric string or integer

Single ID of an adset object to make the parent of the copy. Ignore if you want to keep the copy under the original adset parent.

rename_options
JSON or object-like arrays

Rename options

rename_strategy
enum {DEEP_RENAME, ONLY_TOP_LEVEL_RENAME, NO_RENAME}
Default value: ONLY_TOP_LEVEL_RENAME

DEEP_RENAME: will change this object's name and children's names in the copied object. ONLY_TOP_LEVEL_RENAME: will change the this object's name but won't change the children's name in the copied object. NO_RENAME: will change no name in the copied object

rename_prefix
string

A prefix to copy names. Defaults to null if not provided.

rename_suffix
string

A suffix to copy names. Defaults to null if not provided and appends a localized string of - Copy based on the ad account locale.

status_option
enum {ACTIVE, PAUSED, INHERITED_FROM_SOURCE}
Default value: PAUSED

ACTIVE: the copied ad will have active status. PAUSED: the copied ad will have paused status. INHERITED_FROM_SOURCE: the copied ad will have the parent status.

Return Type

This endpoint supports read-after-write and will read the node represented by copied_ad_id in the return type.
Struct {
copied_ad_id: numeric string,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
80004There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
9009Instagram user is unavailable
You can make a POST request to ads edge from the following paths:
When posting to this edge, an Ad will be created.

Example

Graph API Explorer
POST /v5.0/act_<AD_ACCOUNT_ID>/ads HTTP/1.1
Host: graph.facebook.com

name=My+Ad&adset_id=%3CAD_SET_ID%3E&creative=%7B%22creative_id%22%3A%22%3CCREATIVE_ID%3E%22%7D&status=PAUSED
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/act_<AD_ACCOUNT_ID>/ads',
    array (
      'name' => 'My Ad',
      'adset_id' => '<AD_SET_ID>',
      'creative' => '{"creative_id":"<CREATIVE_ID>"}',
      'status' => 'PAUSED',
    ),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/act_<AD_ACCOUNT_ID>/ads",
    "POST",
    {
        "name": "My Ad",
        "adset_id": "<AD_SET_ID>",
        "creative": "{\"creative_id\":\"<CREATIVE_ID>\"}",
        "status": "PAUSED"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("name", "My Ad");
params.putString("adset_id", "<AD_SET_ID>");
params.putString("creative", "{\"creative_id\":\"<CREATIVE_ID>\"}");
params.putString("status", "PAUSED");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/act_<AD_ACCOUNT_ID>/ads",
    params,
    HttpMethod.POST,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"name": @"My Ad",
  @"adset_id": @"<AD_SET_ID>",
  @"creative": @"{\"creative_id\":\"<CREATIVE_ID>\"}",
  @"status": @"PAUSED",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/act_<AD_ACCOUNT_ID>/ads"
                                      parameters:params
                                      HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
curl -X POST \
  -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/v5.0/act_<AD_ACCOUNT_ID>/ads
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

ParameterDescription
adlabels
list<Object>

Ad labels associated with this ad

adset_id
int64

The ID of the ad set, required on creation.

adset_spec
Ad set spec

The ad set spec for this ad. When the spec is provided, adset_id field is not required.

audience_id
string

The ID of the audience.

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 or creative spec of the ad creative to be used by this ad. You can read more about creatives here. You may supply the ID within an object as follows:

{"creative_id": <CREATIVE_ID>}
or creative spec as follow:

{"creative": {\"name\": \"<NAME>\", \"object_story_spec\": <SPEC>}}

RequiredSupports Emoji
date_format
string

The format of the date.

display_sequence
int64

The sequence of the ad within the same campaign

draft_adgroup_id
numeric string or integer

The ID of the draft ad.

engagement_audience
boolean

Flag to create a new audience based on users who engage with this ad

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.

include_demolink_hashes
boolean

Include the demolink hashes.

name
string

Name of the ad.

RequiredSupports Emoji
priority
int64

Priority

source_ad_id
numeric string or integer

ID of the source Ad, if applicable.

status
enum{ACTIVE, PAUSED, DELETED, ARCHIVED}

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

With Tracking Specs, you log actions taken by people on your ad. See Tracking and Conversion Specs.

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
80004There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
500Message contains banned content
2626The request for a reach frequency campaign has failed.
384The video you tried to upload is too long. Please try again with a shorter video.
331Your picture is too tall or too wide. Try to pick something closer to a square.
192Invalid phone number
9009Instagram user is unavailable
294Managing advertisements requires an access token with the extended permission for ads_management

Updating

Update certain fields:

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>"

Limitations

Use fields you used to Create Ads, including status and execution_options. You cannot use adset_id and social_prefs.

  • Ads with status = ARCHIVED have only two mutable fields: name and status. You can only change the latter to DELETED.

  • Ads with status = DELETED only can have name changed.

  • Ads in an ad set with creative_sequence set cannot be changed to PAUSED, ARCHIVED, or DELETED.

Examples

Update the name:

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=New Ad Name' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<AD_ID>

Update the name and download ad 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=New Ad Name' \
  -F 'redownload=1' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<AD_ID>

Update the status:

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=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<AD_ID>



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

Example

Graph API Explorer
POST /v5.0/<ADGROUP_ID>/ HTTP/1.1
Host: graph.facebook.com

name=My+New+Ad
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/<ADGROUP_ID>/',
    array (
      'name' => 'My New Ad',
    ),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/<ADGROUP_ID>/",
    "POST",
    {
        "name": "My New Ad"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("name", "My New Ad");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/<ADGROUP_ID>/",
    params,
    HttpMethod.POST,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"name": @"My New Ad",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/<ADGROUP_ID>/"
                                      parameters:params
                                      HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
curl -X POST \
  -F 'name="My New Ad"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v5.0/<ADGROUP_ID>/
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

ParameterDescription
adlabels
list<Object>

Ad labels associated with this ad

audience_id
string

The ID of the audience.

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 or creative spec of the ad creative to be used by this ad. You can read more about creatives here. You may supply the ID within an object as follows:

{"creative_id": <CREATIVE_ID>}
or creative spec as follow:

{"creative": {\"name\": \"<NAME>\", \"object_story_spec\": <SPEC>}}

Supports Emoji
display_sequence
int64

The sequence of the ad within the same campaign

draft_adgroup_id
numeric string or integer

The ID of the draft ad.

engagement_audience
boolean

Flag to create a new audience based on users who engage with this ad

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.

Supports Emoji
status
enum{ACTIVE, PAUSED, DELETED, ARCHIVED}

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

With tracking specs, you log actions taken by people on your ad. This field takes arguments identical to action spec. See Tracking and Conversion Specs.

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
80004There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
801Invalid operation
294Managing advertisements requires an access token with the extended permission for ads_management
2626The request for a reach frequency campaign has failed.
2615Invalid call to update this adaccount
9009Instagram user is unavailable
500Message contains banned content
331Your picture is too tall or too wide. Try to pick something closer to a square.

Deleting

Deleting an ad

You can remove values for any optional fields by updating the value to empty. You cannot delete ads in ad set with creative_sequence settings.

use FacebookAds\Object\Ad;

$ad = new Ad(<AD_ID>);
$ad->deleteSelf();
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 -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<AD_ID>/



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

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
80004There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.