Due to the iOS 14.5 launch, changes have been made to this endpoint.
POST /{ad-account-id}/adsets
endpoint for iOS 14.5 SKAdNetwork campaigns.The adsets of this ad account
GET /v21.0/act_<AD_ACCOUNT_ID>/adsets?fields=name%2Cid%2Cstatus 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(
'/act_<AD_ACCOUNT_ID>/adsets?fields=name%2Cid%2Cstatus',
'{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>/adsets",
{
"fields": "name,id,status"
},
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
Bundle params = new Bundle();
params.putString("fields", "name,id,status");
/* make the API call */
new GraphRequest(
AccessToken.getCurrentAccessToken(),
"/act_<AD_ACCOUNT_ID>/adsets",
params,
HttpMethod.GET,
new GraphRequest.Callback() {
public void onCompleted(GraphResponse response) {
/* handle the result */
}
}
).executeAsync();
NSDictionary *params = @{
@"fields": @"name,id,status",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
initWithGraphPath:@"/act_<AD_ACCOUNT_ID>/adsets"
parameters:params
HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
id result,
NSError *error) {
// Handle the result
}];
curl -X GET -G \
-d 'fields="name,id,status"' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/adsets
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} | Predefine date range used to aggregate insights metrics |
effective_status list<enum{ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ARCHIVED, ADSET_PAUSED, IN_PROCESS, WITH_ISSUES}> | Effective status of adset |
is_completed boolean | Filter adset by completed status |
time_range {'since':YYYY-MM-DD,'until':YYYY-MM-DD} | Date range used to aggregate insights metrics |
updated_since integer | Time since the Adset has been updated. |
Reading from this edge will return a JSON formatted result:
{ "
data
": [], "paging
": {}, "summary
": {} }
data
paging
summary
Aggregated information about the edge, such as counts. Specify the fields to fetch in the summary param (like summary=insights
).
Field | Description |
---|---|
insights Edge<AdsInsights> | Analytics summary for all objects. Use nested parameters with this field.
|
total_count unsigned int32 | Total number of objects |
Error | Description |
---|---|
100 | Invalid parameter |
190 | Invalid OAuth 2.0 Access Token |
200 | Permissions error |
613 | Calls to this api have exceeded the rate limit. |
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. |
3018 | The start date of the time range cannot be beyond 37 months from the current date |
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. |
2500 | Error parsing graph query |
Mobile App Install CPA Billing will no longer be supported. The billing event cannot be App Install if the Optimization goal is App Install.
adsets
edge from the following paths: POST /v21.0/act_<AD_ACCOUNT_ID>/adsets HTTP/1.1
Host: graph.facebook.com
name=My+First+AdSet&daily_budget=10000&bid_amount=300&billing_event=IMPRESSIONS&optimization_goal=REACH&campaign_id=%3CAD_CAMPAIGN_ID%3E&promoted_object=%7B%22page_id%22%3A%22%3CPAGE_ID%3E%22%7D&targeting=%7B%22facebook_positions%22%3A%5B%22feed%22%5D%2C%22geo_locations%22%3A%7B%22countries%22%3A%5B%22US%22%5D%2C%22regions%22%3A%5B%7B%22key%22%3A%224081%22%7D%5D%2C%22cities%22%3A%5B%7B%22key%22%3A777934%2C%22radius%22%3A10%2C%22distance_unit%22%3A%22mile%22%7D%5D%7D%2C%22genders%22%3A%5B1%5D%2C%22age_max%22%3A24%2C%22age_min%22%3A20%2C%22publisher_platforms%22%3A%5B%22facebook%22%2C%22audience_network%22%5D%2C%22device_platforms%22%3A%5B%22mobile%22%5D%2C%22flexible_spec%22%3A%5B%7B%22interests%22%3A%5B%7B%22id%22%3A%22%3CINTEREST_ID%3E%22%2C%22name%22%3A%22%3CINTEREST_NAME%3E%22%7D%5D%7D%5D%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>/adsets',
array (
'name' => 'My First AdSet',
'daily_budget' => '10000',
'bid_amount' => '300',
'billing_event' => 'IMPRESSIONS',
'optimization_goal' => 'REACH',
'campaign_id' => '<AD_CAMPAIGN_ID>',
'promoted_object' => '{"page_id":"<PAGE_ID>"}',
'targeting' => '{"facebook_positions":["feed"],"geo_locations":{"countries":["US"],"regions":[{"key":"4081"}],"cities":[{"key":777934,"radius":10,"distance_unit":"mile"}]},"genders":[1],"age_max":24,"age_min":20,"publisher_platforms":["facebook","audience_network"],"device_platforms":["mobile"],"flexible_spec":[{"interests":[{"id":"<INTEREST_ID>","name":"<INTEREST_NAME>"}]}]}',
'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>/adsets",
"POST",
{
"name": "My First AdSet",
"daily_budget": "10000",
"bid_amount": "300",
"billing_event": "IMPRESSIONS",
"optimization_goal": "REACH",
"campaign_id": "<AD_CAMPAIGN_ID>",
"promoted_object": "{\"page_id\":\"<PAGE_ID>\"}",
"targeting": "{\"facebook_positions\":[\"feed\"],\"geo_locations\":{\"countries\":[\"US\"],\"regions\":[{\"key\":\"4081\"}],\"cities\":[{\"key\":777934,\"radius\":10,\"distance_unit\":\"mile\"}]},\"genders\":[1],\"age_max\":24,\"age_min\":20,\"publisher_platforms\":[\"facebook\",\"audience_network\"],\"device_platforms\":[\"mobile\"],\"flexible_spec\":[{\"interests\":[{\"id\":\"<INTEREST_ID>\",\"name\":\"<INTEREST_NAME>\"}]}]}",
"status": "PAUSED"
},
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
Bundle params = new Bundle();
params.putString("name", "My First AdSet");
params.putString("daily_budget", "10000");
params.putString("bid_amount", "300");
params.putString("billing_event", "IMPRESSIONS");
params.putString("optimization_goal", "REACH");
params.putString("campaign_id", "<AD_CAMPAIGN_ID>");
params.putString("promoted_object", "{\"page_id\":\"<PAGE_ID>\"}");
params.putString("targeting", "{\"facebook_positions\":[\"feed\"],\"geo_locations\":{\"countries\":[\"US\"],\"regions\":[{\"key\":\"4081\"}],\"cities\":[{\"key\":777934,\"radius\":10,\"distance_unit\":\"mile\"}]},\"genders\":[1],\"age_max\":24,\"age_min\":20,\"publisher_platforms\":[\"facebook\",\"audience_network\"],\"device_platforms\":[\"mobile\"],\"flexible_spec\":[{\"interests\":[{\"id\":\"<INTEREST_ID>\",\"name\":\"<INTEREST_NAME>\"}]}]}");
params.putString("status", "PAUSED");
/* make the API call */
new GraphRequest(
AccessToken.getCurrentAccessToken(),
"/act_<AD_ACCOUNT_ID>/adsets",
params,
HttpMethod.POST,
new GraphRequest.Callback() {
public void onCompleted(GraphResponse response) {
/* handle the result */
}
}
).executeAsync();
NSDictionary *params = @{
@"name": @"My First AdSet",
@"daily_budget": @"10000",
@"bid_amount": @"300",
@"billing_event": @"IMPRESSIONS",
@"optimization_goal": @"REACH",
@"campaign_id": @"<AD_CAMPAIGN_ID>",
@"promoted_object": @"{\"page_id\":\"<PAGE_ID>\"}",
@"targeting": @"{\"facebook_positions\":[\"feed\"],\"geo_locations\":{\"countries\":[\"US\"],\"regions\":[{\"key\":\"4081\"}],\"cities\":[{\"key\":777934,\"radius\":10,\"distance_unit\":\"mile\"}]},\"genders\":[1],\"age_max\":24,\"age_min\":20,\"publisher_platforms\":[\"facebook\",\"audience_network\"],\"device_platforms\":[\"mobile\"],\"flexible_spec\":[{\"interests\":[{\"id\":\"<INTEREST_ID>\",\"name\":\"<INTEREST_NAME>\"}]}]}",
@"status": @"PAUSED",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
initWithGraphPath:@"/act_<AD_ACCOUNT_ID>/adsets"
parameters:params
HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
id result,
NSError *error) {
// Handle the result
}];
curl -X POST \
-F 'name="My First AdSet"' \
-F 'daily_budget=10000' \
-F 'bid_amount=300' \
-F 'billing_event="IMPRESSIONS"' \
-F 'optimization_goal="REACH"' \
-F 'campaign_id="<AD_CAMPAIGN_ID>"' \
-F 'promoted_object={
"page_id": "<PAGE_ID>"
}' \
-F 'targeting={
"facebook_positions": [
"feed"
],
"geo_locations": {
"countries": [
"US"
],
"regions": [
{
"key": "4081"
}
],
"cities": [
{
"key": 777934,
"radius": 10,
"distance_unit": "mile"
}
]
},
"genders": [
1
],
"age_max": 24,
"age_min": 20,
"publisher_platforms": [
"facebook",
"audience_network"
],
"device_platforms": [
"mobile"
],
"flexible_spec": [
{
"interests": [
{
"id": "<INTEREST_ID>",
"name": "<INTEREST_NAME>"
}
]
}
]
}' \
-F 'status="PAUSED"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/adsets
Parameter | Description |
---|---|
adlabels list<Object> | Specifies list of labels to be associated with this object. This field is optional |
adset_schedule list<Object> | Ad set schedule, representing a delivery schedule for a single day |
attribution_spec list<JSON object> | Conversion attribution spec used for attributing conversions for optimization. Supported window lengths differ by optimization goal and campaign objective. |
bid_amount integer | Bid cap or target cost for this ad set. The bid cap used in a lowest cost bid strategy is defined as the maximum bid you want to pay for a result based on your |
enum{LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS} | Choose bid strategy for this ad set to suit your specific business goals.
Each strategy has tradeoffs and may be available for certain Notes:
|
billing_event enum{APP_INSTALLS, CLICKS, IMPRESSIONS, LINK_CLICKS, NONE, OFFER_CLAIMS, PAGE_LIKES, POST_ENGAGEMENT, THRUPLAY, PURCHASE, LISTING_INTERACTION} | The billing event that this ad set is using: |
budget_schedule_specs list<JSON or object-like arrays> | Initial high demand periods to be created with the ad set. |
campaign_attribution enum{} | campaign_attribution |
campaign_id numeric string or integer | The ad campaign you wish to add this ad set to. |
campaign_spec Campaign spec | Provide |
contextual_bundling_spec Object | settings of Contextual Bundle to support ads serving in Facebook contextual surfaces |
creative_sequence list<numeric string or integer> | Order of the adgroup sequence to be shown to users |
daily_budget int64 | The daily budget defined in your account currency, allowed only for ad sets with a duration (difference between |
daily_imps int64 | Daily impressions. Available only for campaigns with |
daily_min_spend_target int64 | Daily minimum spend target of the ad set defined in your account currency. To use this field, daily budget must be specified in the Campaign. This target is not a guarantee but our best effort. |
daily_spend_cap int64 | Daily spend cap of the ad set defined in your account currency. To use this field, daily budget must be specified in the Campaign. Set the value to 922337203685478 to remove the spend cap. |
destination_type enum{WEBSITE, APP, MESSENGER, APPLINKS_AUTOMATIC, WHATSAPP, INSTAGRAM_DIRECT, FACEBOOK, MESSAGING_MESSENGER_WHATSAPP, MESSAGING_INSTAGRAM_DIRECT_MESSENGER, MESSAGING_INSTAGRAM_DIRECT_MESSENGER_WHATSAPP, MESSAGING_INSTAGRAM_DIRECT_WHATSAPP, SHOP_AUTOMATIC, ON_AD, ON_POST, ON_EVENT, ON_VIDEO, ON_PAGE, INSTAGRAM_PROFILE, FACEBOOK_PAGE, INSTAGRAM_PROFILE_AND_FACEBOOK_PAGE} | Destination of ads in this Ad Set. Options include: Website, App, Messenger, |
dsa_beneficiary string | dsa_beneficiary |
dsa_payor string | dsa_payor |
end_time datetime | End time, required when |
execution_options list<enum{validate_only, include_recommendations}> | Default value: Set An execution setting |
existing_customer_budget_percentage int64 | existing_customer_budget_percentage |
frequency_control_specs list<Object> | An array of frequency control specs for this ad set. As there is only one event type currently supported, this array has no more than one element. Writes to this field are only available in ad sets where |
boolean | Indicates the ad set must only be used for dynamic creatives. Dynamic creative ads can be created in this ad set. Defaults to |
lifetime_budget int64 | Lifetime budget, defined in your account currency. If specified, you must also specify an |
lifetime_imps int64 | Lifetime impressions. Available only for campaigns with |
lifetime_min_spend_target int64 | Lifetime minimum spend target of the ad set defined in your account currency. To use this field, lifetime budget must be specified in the Campaign. This target is not a guarantee but our best effort. |
lifetime_spend_cap int64 | Lifetime spend cap of the ad set defined in your account currency. To use this field, lifetime budget must be specified in the Campaign. Set the value to 922337203685478 to remove the spend cap. |
max_budget_spend_percentage int64 | max_budget_spend_percentage |
min_budget_spend_percentage int64 | min_budget_spend_percentage |
multi_optimization_goal_weight enum{UNDEFINED, BALANCED, PREFER_INSTALL, PREFER_EVENT} | multi_optimization_goal_weight |
name string | Ad set name, max length of 400 characters. RequiredSupports Emoji |
optimization_goal enum{NONE, APP_INSTALLS, AD_RECALL_LIFT, ENGAGED_USERS, EVENT_RESPONSES, IMPRESSIONS, LEAD_GENERATION, QUALITY_LEAD, LINK_CLICKS, OFFSITE_CONVERSIONS, PAGE_LIKES, POST_ENGAGEMENT, QUALITY_CALL, REACH, LANDING_PAGE_VIEWS, VISIT_INSTAGRAM_PROFILE, VALUE, THRUPLAY, DERIVED_EVENTS, APP_INSTALLS_AND_OFFSITE_CONVERSIONS, CONVERSATIONS, IN_APP_VALUE, MESSAGING_PURCHASE_CONVERSION, SUBSCRIBERS, REMINDERS_SET, MEANINGFUL_CALL_ATTEMPT, PROFILE_VISIT, MESSAGING_APPOINTMENT_CONVERSION} | What the ad set is optimizing for. |
optimization_sub_event enum{NONE, VIDEO_SOUND_ON, TRIP_CONSIDERATION, TRAVEL_INTENT, TRAVEL_INTENT_NO_DESTINATION_INTENT, TRAVEL_INTENT_BUCKET_01, TRAVEL_INTENT_BUCKET_02, TRAVEL_INTENT_BUCKET_03, TRAVEL_INTENT_BUCKET_04, TRAVEL_INTENT_BUCKET_05} | Optimization sub event for a specific optimization goal (ex: Sound-On event for Video-View-2s optimization goal) |
pacing_type list<string> | Defines the pacing type, standard by default or using ad scheduling |
promoted_object Object | The object this ad set is promoting across all its ads.
Required with certain campaign objectives.
optimization_goal is OFFSITE_CONVERSIONS
optimization_goal is LEAD_GENERATION , page_id needs to be passed as promoted_object.
Please refer to the Outcome-Driven Ads Experiences mapping table to find new objectives and their corresponding destination types, optimization goals and promoted objects. |
rf_prediction_id numeric string or integer | Reach and frequency prediction ID |
source_adset_id numeric string or integer | The source adset id that this ad is copied from (if applicable). |
start_time datetime | The start time of the set, e.g. |
status enum{ACTIVE, PAUSED, DELETED, ARCHIVED} | Only |
targeting Targeting object | An ad set's targeting structure. "countries" is required. See targeting. |
time_based_ad_rotation_id_blocks list<list<int64>> | Specify ad creative that displays at custom date ranges in a campaign
as an array. A list of Adgroup IDs. The list of ads to display for each
time range in a given schedule. For example display first ad in Adgroup
for first date range, second ad for second date range, and so on. You
can display more than one ad per date range by providing more than
one ad ID per array. For example set
|
time_based_ad_rotation_intervals list<int64> | Date range when specific ad creative displays during a campaign.
Provide date ranges in an array of UNIX timestamps where each
timestamp represents the start time for each date range. For example a
3-day campaign from May 9 12am to May 11 11:59PM PST can have three
date ranges, the first date range starts from May 9 12:00AM to
May 9 11:59PM, second date range starts from May 10 12:00AM to
May 10 11:59PM and last starts from May 11 12:00AM to May 11 11:59PM.
The first timestamp should match the campaign start time. The last
timestamp should be at least 1 hour before the campaign end time. You
must provide at least two date ranges. All date ranges must cover the
whole campaign length, so any date range cannot exceed campaign length.
Use with |
time_start datetime | Time start |
time_stop datetime | Time stop |
tune_for_category enum{NONE, EMPLOYMENT, HOUSING, CREDIT, ISSUES_ELECTIONS_POLITICS, ONLINE_GAMBLING_AND_GAMING, FINANCIAL_PRODUCTS_SERVICES} | tune_for_category |
id
in the return type.id
: numeric string, success
: bool, Error | Description |
---|---|
100 | Invalid parameter |
200 | Permissions error |
2695 | The ad set creation reached its campaign group(ios14) limit. |
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. |
900 | No such application exists. |
2641 | Your ad includes or excludes locations that are currently restricted |
2635 | You are calling a deprecated version of the Ads API. Please update to the latest version. |
This operation has been deprecated with Marketing API V8.