Facebook
    Graph API Reference v21.0: Ad - Documentation - Meta for Developers
    Marketing API
    Graph API Version

    Ad

    Contains information to display an ad and associate it with 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 results 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 Issue, Electoral or Political Ads 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.

    Targeting DSA Regulated Locations (European Union)

    To create or copy an ad which is in an ad set targeted in the European Union's Digital Services Act (DSA) regulated locations, please set the payor/beneficiary information first. For your convenience, if the default_dsa_payor and default_dsa_beneficiary are set in an ad account, during the copying process, even if the original ad set does not set payor or beneficiary, it will be filled with saved default values. For more information on copying ads that target DSA regulated locations in the EU, see the Ad Copies reference documentation .

    Targeting Youth in European Union (EU), European Economic Area (EEA), and Switzerland

    Meta will stop showing ads to youth in the EU, EEA, and Switzerland as early as the week of November 6, 2023. When creating new ad sets or updating existing ones that target youth in the EU, EEA, and Switzerland, they will be prevented. Existing ad sets targeting youth in the EU, EEA and Switzerland, will pause delivery as early as the week of November 6, 2023. Existing ad sets targeting youth in the EU, EEA, and Switzerland and in other regions will see a warning that the ads in the ad sets will no longer be delivered to youth in the EU, EEA, and Switzerland.

    Examples

    Creating an ad:

     
       
 

     
 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/v21.0/act_<AD_ACCOUNT_ID>/ads
    Open In Graph API Explorer Open In Postman 
     
       
 

     
 'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const Ad = bizSdk.Ad;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'name' : 'My Ad',
  'adset_id' : '<adSetID>',
  'creative' : {'creative_id':'<adCreativeID>'},
  'status' : 'PAUSED',
};
const ads = (new AdAccount(id)).createAd(
  fields,
  params
);
logApiCallResult('ads api call complete.', ads);
    Open In Graph API Explorer Open In Postman 
     
       
 

     
 require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Ad;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_ACCOUNT_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'My Ad',
  'adset_id' => '<adSetID>',
  'creative' => array('creative_id' => '<adCreativeID>'),
  'status' => 'PAUSED',
);
echo json_encode((new AdAccount($id))->createAd(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);
    Open In Graph API Explorer Open In Postman 
     
       
 

     
 from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.ad import Ad
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'My Ad',
  'adset_id': '<adSetID>',
  'creative': {'creative_id':'<adCreativeID>'},
  'status': 'PAUSED',
}
print AdAccount(id).create_ad(
  fields=fields,
  params=params,
)
    Open In Graph API Explorer Open In Postman 
     
       
 

     
 import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_ACCOUNT_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new AdAccount(id, context).createAd()
      .setName(\"My Ad\")
      .setAdsetId(<adSetID>L)
      .setCreative(
          new AdCreative()
            .setFieldId(\"<adCreativeID>\")
        )
      .setStatus(Ad.EnumStatus.VALUE_PAUSED)
      .execute();

  }
}
    Open In Graph API Explorer Open In Postman 
     
       
 

     
 require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad_account = FacebookAds::AdAccount.get(id)
ads = ad_account.ads.create({
    name: 'My Ad',
    adset_id: '<adSetID>',
    creative: {'creative_id':'<adCreativeID>'},
    status: 'PAUSED',
})
    Open In Graph API Explorer Open In Postman

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

     
       
 

     
 curl -X POST \
  -F 'name="My AdGroup"' \
  -F 'adset_id="<AD_SET_ID>"' \
  -F 'creative={
       "creative_id": "<CREATIVE_ID>"
     }' \
  -F 'status="PAUSED"' \
  -F 'authorization_category="POLITICAL"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/ads
    Open In Graph API Explorer 
     
       
 

     
 'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const Ad = bizSdk.Ad;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'name' : 'My AdGroup',
  'adset_id' : '<adSetID>',
  'creative' : {'creative_id':'<adCreativeID>'},
  'status' : 'PAUSED',
  'authorization_category' : 'POLITICAL',
};
const ads = (new AdAccount(id)).createAd(
  fields,
  params
);
logApiCallResult('ads api call complete.', ads);
    Open In Graph API Explorer 
     
       
 

     
 require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Ad;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_ACCOUNT_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'My AdGroup',
  'adset_id' => '<adSetID>',
  'creative' => array('creative_id' => '<adCreativeID>'),
  'status' => 'PAUSED',
  'authorization_category' => 'POLITICAL',
);
echo json_encode((new AdAccount($id))->createAd(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);
    Open In Graph API Explorer 
     
       
 

     
 from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.ad import Ad
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'My AdGroup',
  'adset_id': '<adSetID>',
  'creative': {'creative_id':'<adCreativeID>'},
  'status': 'PAUSED',
  'authorization_category': 'POLITICAL',
}
print AdAccount(id).create_ad(
  fields=fields,
  params=params,
)
    Open In Graph API Explorer 
     
       
 

     
 import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_ACCOUNT_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new AdAccount(id, context).createAd()
      .setName(\"My AdGroup\")
      .setAdsetId(<adSetID>L)
      .setCreative(
          new AdCreative()
            .setFieldId(\"<adCreativeID>\")
        )
      .setStatus(Ad.EnumStatus.VALUE_PAUSED)
      .setParam(\"authorization_category\", \"POLITICAL\")
      .execute();

  }
}
    Open In Graph API Explorer 
     
       
 

     
 require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad_account = FacebookAds::AdAccount.get(id)
ads = ad_account.ads.create({
    name: 'My AdGroup',
    adset_id: '<adSetID>',
    creative: {'creative_id':'<adCreativeID>'},
    status: 'PAUSED',
    authorization_category: 'POLITICAL',
})
    Open In Graph API Explorer

    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

     
       
 

     
 curl -X GET \
  -d 'fields="id,name"' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<ADGROUP_ID>/
    Open In Graph API Explorer 
     
       
 

     
 'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Ad = bizSdk.Ad;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<ADGROUP_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
  'id',
  'name',
];
params = {
};
const sample_code = (new Ad(id)).get(
  fields,
  params
);
logApiCallResult('sample_code api call complete.', sample_code);
    Open In Graph API Explorer 
     
       
 

     
 require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\Ad;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<ADGROUP_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
  'id',
  'name',
);
$params = array(
);
echo json_encode((new Ad($id))->getSelf(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);
    Open In Graph API Explorer 
     
       
 

     
 from facebook_business.adobjects.ad import Ad
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<ADGROUP_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
  'id',
  'name',
]
params = {
}
print Ad(id).get(
  fields=fields,
  params=params,
)
    Open In Graph API Explorer 
     
       
 

     
 import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<ADGROUP_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Ad(id, context).get()
      .requestIdField()
      .requestNameField()
      .execute();

  }
}
    Open In Graph API Explorer 
     
       
 

     
 require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<ADGROUP_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad = FacebookAds::Ad.get(id ,'id,name')
    Open In Graph API Explorer

    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:

     
       
 

     
 curl -X GET \
  -d 'fields="name"' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<AD_CAMPAIGN_ID>/ads
    Open In Graph API Explorer 
     
       
 

     
 'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Campaign = bizSdk.Campaign;
const Ad = bizSdk.Ad;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_CAMPAIGN_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
  'name',
];
params = {
};
const adss = (new Campaign(id)).getAds(
  fields,
  params
);
logApiCallResult('adss api call complete.', adss);
    Open In Graph API Explorer 
     
       
 

     
 require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\Campaign;
use FacebookAds\Object\Ad;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_CAMPAIGN_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
  'name',
);
$params = array(
);
echo json_encode((new Campaign($id))->getAds(
  $fields,
  $params
)->getResponse()->getContent(), JSON_PRETTY_PRINT);
    Open In Graph API Explorer 
     
       
 

     
 from facebook_business.adobjects.campaign import Campaign
from facebook_business.adobjects.ad import Ad
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_CAMPAIGN_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
  'name',
]
params = {
}
print Campaign(id).get_ads(
  fields=fields,
  params=params,
)
    Open In Graph API Explorer 
     
       
 

     
 import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_CAMPAIGN_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Campaign(id, context).getAds()
      .requestNameField()
      .execute();

  }
}
    Open In Graph API Explorer 
     
       
 

     
 require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_CAMPAIGN_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

campaign = FacebookAds::Campaign.get(id)
adss = campaign.ads({
    fields: { 'name' },
})
    Open In Graph API Explorer

    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"



    Parameters

    Parameter Description
    date_preset
    enum{today, yesterday, this_month, last_month, this_quarter, maximum, data_maximum, 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. Note if time range is invalid, it will be ignored.
    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

    Field Description
    id
    numeric string

    The ID of this ad.

    Default
    account_id
    numeric string

    The ID of the ad account that this ad belongs to.
    ad_active_time
    numeric string

    The time from when the ad was recently active
    ad_review_feedback
    AdgroupReviewFeedback

    The review feedback for this ad after it is reviewed.
    ad_schedule_end_time
    datetime

    An optional parameter that defines the end time of an individual ad. If no end time is defined, the ad will run on the campaign’s schedule.

    This parameter is only available for sales and app promotion campaigns.
    ad_schedule_start_time
    datetime

    An optional parameter that defines the start time of an individual ad. If no start time is defined, the ad will run on the campaign’s schedule.

    This parameter is only available for sales and app promotion campaigns.
    adlabels
    list<AdLabel>

    Ad labels associated with this ad
    adset
    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. This value would be the same as the bid_amount field on the ad set.
    campaign
    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.
    conversion_domain
    string

    The domain where conversions happen. The field is no longer required for creation or update since June 2023. Note that this field should contain only the first and second level domains, and not the full URL. For example facebook.com .
    created_time
    datetime

    Time when the ad was created.
    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>}}

    creative_asset_groups_spec
    AdCreativeAssetGroupsSpec

    This field is used to create ads using the Flexible ad format. You can read more about that here

    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
    list<AdgroupIssuesInfo>

    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
    list<AdRecommendation>

    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
    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
    list<ConversionActionQuery>

    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

    Edge Description
    adcreatives
    Edge<AdCreative>

    Creative associated with this ad
    adrules_governed
    Edge<AdRule>

    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
    copies
    Edge<Adgroup>

    The copies of this ad
    leads
    Edge<UserLeadGenInfo>

    Leads submitted for this ad
    previews
    Edge<AdPreview>

    Preview of the ad
    targetingsentencelines
    Edge<TargetingSentenceLine>

    The targeting description sentence for this ad

    Error Codes

    Error Description
    100 Invalid parameter
    80004 There 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#ads-management.
    104 Incorrect signature
    200 Permissions error
    190 Invalid OAuth 2.0 Access Token
    80000 There 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#ads-insights.
    2635 You are calling a deprecated version of the Ads API. Please update to the latest version.
    2500 Error parsing graph query

    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 its ad set to paused (see ad set ). Run the ad set when you are ready.

    Due to iOS 14.5 changes, Deferred Deep Linking is no longer available for SKAdsNetwork Campaigns .

    Synchronous Creation

    Creates one ad at a time:

     
       
 

     
 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/v21.0/act_<AD_ACCOUNT_ID>/ads
    Open In Graph API Explorer Open In Postman 
     
       
 

     
 'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const Ad = bizSdk.Ad;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'name' : 'My Ad',
  'adset_id' : '<adSetID>',
  'creative' : {'creative_id':'<adCreativeID>'},
  'status' : 'PAUSED',
};
const ads = (new AdAccount(id)).createAd(
  fields,
  params
);
logApiCallResult('ads api call complete.', ads);
    Open In Graph API Explorer Open In Postman 
     
       
 

     
 require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Ad;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_ACCOUNT_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'My Ad',
  'adset_id' => '<adSetID>',
  'creative' => array('creative_id' => '<adCreativeID>'),
  'status' => 'PAUSED',
);
echo json_encode((new AdAccount($id))->createAd(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);
    Open In Graph API Explorer Open In Postman 
     
       
 

     
 from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.ad import Ad
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'My Ad',
  'adset_id': '<adSetID>',
  'creative': {'creative_id':'<adCreativeID>'},
  'status': 'PAUSED',
}
print AdAccount(id).create_ad(
  fields=fields,
  params=params,
)
    Open In Graph API Explorer Open In Postman 
     
       
 

     
 import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_ACCOUNT_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new AdAccount(id, context).createAd()
      .setName(\"My Ad\")
      .setAdsetId(<adSetID>L)
      .setCreative(
          new AdCreative()
            .setFieldId(\"<adCreativeID>\")
        )
      .setStatus(Ad.EnumStatus.VALUE_PAUSED)
      .execute();

  }
}
    Open In Graph API Explorer Open In Postman 
     
       
 

     
 require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad_account = FacebookAds::AdAccount.get(id)
ads = ad_account.ads.create({
    name: 'My Ad',
    adset_id: '<adSetID>',
    creative: {'creative_id':'<adCreativeID>'},
    status: 'PAUSED',
})
    Open In Graph API Explorer Open In Postman

    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:

     
       
 

     
 curl -X POST \
  -F 'name="My AdGroup with Redownload"' \
  -F 'adset_id="<AD_SET_ID>"' \
  -F 'creative={
       "creative_id": "<CREATIVE_ID>"
     }' \
  -F 'redownload=1' \
  -F 'status="PAUSED"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/ads
    Open In Graph API Explorer 
     
       
 

     
 'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const Ad = bizSdk.Ad;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'name' : 'My AdGroup with Redownload',
  'adset_id' : '<adSetID>',
  'creative' : {'creative_id':'<adCreativeID>'},
  'redownload' : '1',
  'status' : 'PAUSED',
};
const ads = (new AdAccount(id)).createAd(
  fields,
  params
);
logApiCallResult('ads api call complete.', ads);
    Open In Graph API Explorer 
     
       
 

     
 require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Ad;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_ACCOUNT_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'My AdGroup with Redownload',
  'adset_id' => '<adSetID>',
  'creative' => array('creative_id' => '<adCreativeID>'),
  'redownload' => '1',
  'status' => 'PAUSED',
);
echo json_encode((new AdAccount($id))->createAd(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);
    Open In Graph API Explorer 
     
       
 

     
 from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.ad import Ad
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'My AdGroup with Redownload',
  'adset_id': '<adSetID>',
  'creative': {'creative_id':'<adCreativeID>'},
  'redownload': '1',
  'status': 'PAUSED',
}
print AdAccount(id).create_ad(
  fields=fields,
  params=params,
)
    Open In Graph API Explorer 
     
       
 

     
 import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_ACCOUNT_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new AdAccount(id, context).createAd()
      .setName(\"My AdGroup with Redownload\")
      .setAdsetId(<adSetID>L)
      .setCreative(
          new AdCreative()
            .setFieldId(\"<adCreativeID>\")
        )
      .setParam(\"redownload\", \"1\")
      .setStatus(Ad.EnumStatus.VALUE_PAUSED)
      .execute();

  }
}
    Open In Graph API Explorer 
     
       
 

     
 require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad_account = FacebookAds::AdAccount.get(id)
ads = ad_account.ads.create({
    name: 'My AdGroup with Redownload',
    adset_id: '<adSetID>',
    creative: {'creative_id':'<adCreativeID>'},
    redownload: '1',
    status: 'PAUSED',
})
    Open In Graph API Explorer



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

    Parameters

    Parameter Description
    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,
    }

    Error Codes

    Error Description
    100 Invalid parameter
    368 The action attempted has been deemed abusive or is otherwise disallowed
    200 Permissions error
    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 /v21.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(); 

     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/v21.0/act_<AD_ACCOUNT_ID>/ads
    If you want to learn how to use the Graph API, read our Using Graph API guide .

    Parameters

    Parameter Description
    ad_schedule_end_time
    datetime

    An optional parameter that defines the end time of an individual ad. If no end time is defined, the ad will run on the campaign’s schedule.

    This parameter is only available for sales and app promotion campaigns.
    ad_schedule_start_time
    datetime

    An optional parameter that defines the start time of an individual ad. If no start time is defined, the ad will run on the campaign’s schedule.

    This parameter is only available for sales and app promotion campaigns.
    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

    Deprecated.We no longer allow setting the bid_amount value on an ad. Please set bid_amount for the ad set.
    conversion_domain
    string

    The domain where conversions happen. Required to create or update an ad in a campaign that shares data with a pixel. This field will be auto-populated for existing ads by inferring from destination URLs . Note that this field should contain only the first and second level domains, and not the full URL. For example facebook.com .
    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>}}

    Required Supports Emoji
    creative_asset_groups_spec
    string (CreativeAssetGroupsSpec)

    creative_asset_groups_spec

    Supports 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.

    Required Supports 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,
    }

    Error Codes

    Error Description
    100 Invalid parameter
    200 Permissions error
    2626 The request for a reach frequency campaign has failed.
    105 The number of parameters exceeded the maximum for this operation
    368 The action attempted has been deemed abusive or is otherwise disallowed
    194 Missing at least one required parameter
    80004 There 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#ads-management.
    190 Invalid OAuth 2.0 Access Token
    500 Message contains banned content
    1500 The url you supplied is invalid

    Updating

    Update certain fields:

     
       
 

     
 curl -X POST \
  -F 'name="My New Ad"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<ADGROUP_ID>/
    Open In Graph API Explorer 
     
       
 

     
 'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Ad = bizSdk.Ad;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<ADGROUP_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'name' : 'My New Ad',
};
const sample_code = (new Ad(id)).update(
  fields,
  params
);
logApiCallResult('sample_code api call complete.', sample_code);
    Open In Graph API Explorer 
     
       
 

     
 require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\Ad;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<ADGROUP_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'My New Ad',
);
echo json_encode((new Ad($id))->updateSelf(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);
    Open In Graph API Explorer 
     
       
 

     
 from facebook_business.adobjects.ad import Ad
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<ADGROUP_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'My New Ad',
}
print Ad(id).update(
  fields=fields,
  params=params,
)
    Open In Graph API Explorer 
     
       
 

     
 import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<ADGROUP_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Ad(id, context).update()
      .setName(\"My New Ad\")
      .execute();

  }
}
    Open In Graph API Explorer 
     
       
 

     
 require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<ADGROUP_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad = FacebookAds::Ad.get(id)
ad.name = 'My New Ad'
ad.save
    Open In Graph API Explorer

    Limitations

    • Only update fields that were used during ad creation can be updated.
    • adset_id and social_prefs can not be updated.

    • 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 .

    • Trying to duplicate existing objective campaigns to use the new objective values ( OUTCOME_APP_PROMOTION , OUTCOME_AWARENESS , OUTCOME_ENGAGEMENT , OUTCOME_LEADS , OUTCOME_SALES , OUTCOME_TRAFFIC ) may throw an error.

    Examples

    Update the name:

     
       
 

     
 curl -X POST \
  -F 'name="My New Ad"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<ADGROUP_ID>/
    Open In Graph API Explorer 
     
       
 

     
 'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Ad = bizSdk.Ad;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<ADGROUP_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'name' : 'My New Ad',
};
const sample_code = (new Ad(id)).update(
  fields,
  params
);
logApiCallResult('sample_code api call complete.', sample_code);
    Open In Graph API Explorer 
     
       
 

     
 require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\Ad;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<ADGROUP_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'My New Ad',
);
echo json_encode((new Ad($id))->updateSelf(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);
    Open In Graph API Explorer 
     
       
 

     
 from facebook_business.adobjects.ad import Ad
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<ADGROUP_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'My New Ad',
}
print Ad(id).update(
  fields=fields,
  params=params,
)
    Open In Graph API Explorer 
     
       
 

     
 import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<ADGROUP_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Ad(id, context).update()
      .setName(\"My New Ad\")
      .execute();

  }
}
    Open In Graph API Explorer 
     
       
 

     
 require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<ADGROUP_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad = FacebookAds::Ad.get(id)
ad.name = 'My New Ad'
ad.save
    Open In Graph API Explorer

    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:

     
       
 

     
 curl -X POST \
  -F 'adgroup_status="PAUSED"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<ADGROUP_ID>/
    Open In Graph API Explorer 
     
       
 

     
 'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Ad = bizSdk.Ad;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<ADGROUP_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'adgroup_status' : 'PAUSED',
};
const sample_code = (new Ad(id)).update(
  fields,
  params
);
logApiCallResult('sample_code api call complete.', sample_code);
    Open In Graph API Explorer 
     
       
 

     
 require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\Ad;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<ADGROUP_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'adgroup_status' => 'PAUSED',
);
echo json_encode((new Ad($id))->updateSelf(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);
    Open In Graph API Explorer 
     
       
 

     
 from facebook_business.adobjects.ad import Ad
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<ADGROUP_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'adgroup_status': 'PAUSED',
}
print Ad(id).update(
  fields=fields,
  params=params,
)
    Open In Graph API Explorer 
     
       
 

     
 import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<ADGROUP_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Ad(id, context).update()
      .setParam(\"adgroup_status\", \"PAUSED\")
      .execute();

  }
}
    Open In Graph API Explorer 
     
       
 

     
 require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<ADGROUP_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad = FacebookAds::Ad.get(id)
ad.adgroup_status = 'PAUSED'
ad.save
    Open In Graph API Explorer



    You can't perform this operation on this endpoint.

    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.

     
       
 

     
 curl -X DELETE \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<ADGROUP_ID>/
    Open In Graph API Explorer 
     
       
 

     
 'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Ad = bizSdk.Ad;
const AbstractObject = bizSdk.AbstractObject;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<ADGROUP_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
};
const sample_code = (new Ad(id)).delete(
  fields,
  params
);
logApiCallResult('sample_code api call complete.', sample_code);
    Open In Graph API Explorer 
     
       
 

     
 require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\Ad;
use FacebookAds\Object\AbstractObject;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<ADGROUP_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
);
echo json_encode((new Ad($id))->deleteSelf(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);
    Open In Graph API Explorer 
     
       
 

     
 from facebook_business.adobjects.ad import Ad
from facebook_business.adobjects.abstractobject import AbstractObject
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<ADGROUP_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
}
print Ad(id).delete(
  fields=fields,
  params=params,
)
    Open In Graph API Explorer 
     
       
 

     
 import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<ADGROUP_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Ad(id, context).delete()
      .execute();

  }
}
    Open In Graph API Explorer 
     
       
 

     
 require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<ADGROUP_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad = FacebookAds::Ad.get(id)
ad.destroy({

})
    Open In Graph API Explorer



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

    Example

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

     /* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->delete(
    '/<ADGROUP_ID>/',
    array (),
    '{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>/",
    "DELETE",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
); 

     /* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/<ADGROUP_ID>/",
    null,
    HttpMethod.DELETE,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync(); 

     /* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/<ADGROUP_ID>/"
                                      parameters:params
                                      HTTPMethod:@"DELETE"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}]; 

     curl -X DELETE -G \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<ADGROUP_ID>/
    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.

    Return Type

    Struct {
    success : bool,
    }

    Error Codes

    Error Description
    200 Permissions error
    100 Invalid parameter
    80004 There 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#ads-management.
    190 Invalid OAuth 2.0 Access Token
    Design a Mobile Website
    View Site in Mobile | Classic
    Share by: