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.
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.
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.
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.
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.
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
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
See:
An ad object contains the data necessary to visually display an ad and associate it with a corresponding ad set.
curl -X GET \
-d 'fields="id,name"' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/<ADGROUP_ID>/
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;
}
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
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;
}
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. |
Field | Description |
---|---|
id numeric string | The ID of this ad. |
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 | 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 | 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. This value would be the same as the |
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 |
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 |
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_asset_groups_spec | 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. |
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 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 | 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
|
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. |
Edge | Description |
---|---|
Edge<AdCreative> | Creative associated with this ad |
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 |
Edge<Adgroup> | The copies of this ad |
Edge<UserLeadGenInfo> | Leads submitted for this ad |
Edge<AdPreview> | Preview of the ad |
Edge<TargetingSentenceLine> | The targeting description sentence for this ad |
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 |
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.
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
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 |
notification_uri type: string | Optional. Async job completed. This URI notifies the caller with a |
notification_mode type: string | Optional. Notification mode: |
For information on asynchronous request sets, see Asynchronous Requests.
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 |
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
copies
edge from the following paths: 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 |
status_option enum {ACTIVE, PAUSED, INHERITED_FROM_SOURCE} | Default value: PAUSED
|
copied_ad_id
in the return type.copied_ad_id
: numeric string, Error | Description |
---|---|
100 | Invalid parameter |
200 | Permissions error |
ads
edge from the following paths: 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
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 |
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 |
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: RequiredSupports 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 |
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 |
tracking_specs Object | With Tracking Specs, you log actions taken by people on your ad. See Tracking and Conversion Specs. |
id
in the return type.id
: numeric string, success
: bool, 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 |
194 | Missing at least one required parameter |
368 | The action attempted has been deemed abusive or is otherwise disallowed |
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 |
2625 | The request for a reach frequency campaign is invalid. |
Update certain fields:
curl -X POST \
-F 'name="My New Ad"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/<ADGROUP_ID>/
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.
Update the name:
curl -X POST \
-F 'name="My New Ad"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/<ADGROUP_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:
curl -X POST \
-F 'adgroup_status="PAUSED"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/<ADGROUP_ID>/
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>/
/{ad_id}
.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>/
success
: bool, 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. |