Graph API Version

Campaign

A campaign is the highest level organizational structure within an ad account and should represent a single objective for an advertiser, for example, to drive page post engagement. Setting objective of the campaign will enforce validation on any ads added to the campaign to ensure they also have the correct objective.

Facebook will no longer be able to aggregate non-inline conversion metric values across iOS 14.5 and non-iOS 14.5 campaigns due to differences in attribution logic. Querying across iOS 14.5 and non-iOS 14.5 campaigns will result in no data getting returned for non-inline conversion metrics such as app installs and purchases. Inline event metrics like impressions, link clicks, and video views, however, can still be aggregated. Please visit our changelog for more information.

Ad campaigns that target iOS 14.5 must set the new is_skadnetwork_attribution field to true.

The date_preset = lifetime parameter is disabled in Graph API v10.0 and replaced with date_preset = maximum, which returns a maximum of 37 months of data. For v9.0 and below, date_preset = maximum will be enabled on May 25, 2021, and any lifetime calls will default to maximum and return only 37 months of data.

Limits

You can only create 200 ad sets per ad campaign. Learn more about the ad campaign structure.
If your campaign has more than 70 ad sets and uses Campaign Budget Optimization, you are not able to edit your current bid strategy or turn off CBO. Learn more in the Business Help Center.

New Required Field for All Campaigns

All businesses using the Marketing API must identify whether or not new and edited campaigns belong to a Special Ad Category. Current available categories are: housing, employment, credit, or issues, elections, and politics. Businesses whose ads do not belong to a Special Ad Category must indicate NONE or send an empty array in the special_ad_categories field.

Businesses running housing, employment, or credit ads must comply with targeting and audience restrictions. Targeting for ads about social issues, elections or politics are not affected by the special_ad_categories label.

As of Marketing API 7.0, the special_ad_category parameter on the POST /act_<ad_account_id>/campaigns endpoint has been deprecated and replaced with a new special_ad_categories parameter. The new special_ad_categories parameter is required and accepts an array.

If you use the special_ad_category parameter, it will still return a string, but you should use GET /{campaign-id}?fields=special_ad_categories to get an array back. Refer to Special Ad Category for additional information.

Reading

A campaign is a grouping of ad sets which are organized by the same business objective. Each campaign has an objective that must be valid across the ad sets within that campaign.

After your ads begin delivering, you can query stats for ad campaigns. The statistics returned will be unique stats, deduped across the ad sets. You can also get reports and statistics for all ad sets and ads in an campaign simultaneously.

Example

Graph API Explorer

GET v21.0/...?fields={fieldname_of_type_Campaign} HTTP/1.1
Host: graph.facebook.com

/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '...?fields={fieldname_of_type_Campaign}',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */

/* make the API call */
FB.api(
    "...?fields={fieldname_of_type_Campaign}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "...?fields={fieldname_of_type_Campaign}",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();

/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"...?fields={fieldname_of_type_Campaign}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

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	Campaign's ID Default
`account_id` numeric string	ID of the ad account that owns this campaign
`adlabels` list<AdLabel>	Ad Labels associated with this campaign
`bid_strategy` enum {LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS}	Bid strategy for this campaign when you enable campaign budget optimization and when you use `AUCTION` as your buying type: `LOWEST_COST_WITHOUT_CAP`: Designed to get the most results for your budget based on your ad set `optimization_goal` without limiting your bid amount. This is the best strategy to select if you care most about cost efficiency. However, note that it may be harder to get stable average costs as you spend. Note: this strategy is also known as automatic bidding. Learn more in Ads Help Center, About bid strategies: Lowest cost. `LOWEST_COST_WITH_BID_CAP`: Designed to get the most results for your budget based on your ad set `optimization_goal` while limiting actual bid to a specified amount. Get specified bid cap in the `bid_amount` field for each ad set in this ad campaign. This strategy is known as manual maximum-cost bidding. Learn more in Ads Help Center, About bid strategies: Lowest cost. `COST_CAP`: Designed to get the most results for your budget based on your ad set `optimization_goal` while limiting actual average cost per optimization event to a specified amount. Get specified cost cap in the `bid_amount` field for each ad set in this ad campaign. Learn more in Ads Help Center, About bid strategies: Cost Cap. Notes: If you do not enable campaign budget optimization, you should get `bid_strategy` at the ad set level. `TARGET_COST` bidding strategy has been deprecated with Marketing API v9.
`boosted_object_id` numeric string	The Boosted Object this campaign has associated, if any
`brand_lift_studies` list<AdStudy>	Automated Brand Lift V2 studies for this ad set.
`budget_rebalance_flag` bool	Whether to automatically rebalance budgets daily for all the adsets under this campaign. This has been deprecated on Marketing API V7.0.
`budget_remaining` numeric string	Remaining budget
`buying_type` string	Buying type, possible values are: `AUCTION`: default `RESERVED`: for reach and frequency ads. Reach and Frequency is disabled for housing, employment and credit ads.
`campaign_group_active_time` numeric string	campaign_group_active_time this is only for Internal, This will have the active running length of Campaign Groups
`can_create_brand_lift_study` bool	If we can create a new automated brand lift study for the ad set.
`can_use_spend_cap` bool	Whether the campaign can set the spend cap
`configured_status` enum {ACTIVE, PAUSED, DELETED, ARCHIVED}	If this status is `PAUSED`, all its active ad sets and ads will be paused and have an effective status `CAMPAIGN_PAUSED`. Prefer using 'status' instead of this.
`created_time` datetime	Created Time
`daily_budget` numeric string	The daily budget of the campaign
`effective_status` enum {ACTIVE, PAUSED, DELETED, ARCHIVED, IN_PROCESS, WITH_ISSUES}	IN_PROCESS is available for version 4.0 or higher
`has_secondary_skadnetwork_reporting` bool	has_secondary_skadnetwork_reporting
`is_budget_schedule_enabled` bool	Whether budget scheduling is enabled for the campaign group
`is_skadnetwork_attribution` bool	When set to `true` Indicates that the campaign will include SKAdNetwork, iOS 14+.
`issues_info` list<AdCampaignIssuesInfo>	Issues for this campaign that prevented it from deliverying
`last_budget_toggling_time` datetime	Last budget toggling time
`lifetime_budget` numeric string	The lifetime budget of the campaign
`name` string	Campaign's name
`objective` string	Campaign's objective See the Outcome Ad-Driven Experience Objective Validation section below for more information.
`pacing_type` list<string>	Defines pacing type of the campaign. The value is an array of options: "standard".
`primary_attribution` enum	primary_attribution
`promoted_object` AdPromotedObject	The object this campaign is promoting across all its ads
`smart_promotion_type` enum	Smart Promotion Type. guided_creation or smart_app_promotion(the choice under APP_INSTALLS objective).
`source_campaign` Campaign	The source campaign that this campaign is copied from
`source_campaign_id` numeric string	The source campaign id that this campaign is copied from
`special_ad_categories` list<enum>	special ad categories
`special_ad_category` enum	The campaign's Special Ad Category. One of `HOUSING`, `EMPLOYMENT`, `CREDIT`, or `NONE`.
`special_ad_category_country` list<enum>	Country field for Special Ad Category.
`spend_cap` numeric string	A spend cap for the campaign, such that it will not spend more than this cap. Expressed as integer value of the subunit in your currency.
`start_time` datetime	Merging of `start_time`s for the ad sets belonging to this campaign. At the campaign level, `start_time` is a read only field. You can setup `start_time` at the ad set level.
`status` enum {ACTIVE, PAUSED, DELETED, ARCHIVED}	If this status is `PAUSED`, all its active ad sets and ads will be paused and have an effective status `CAMPAIGN_PAUSED`. The field returns the same value as 'configured_status', and is the suggested one to use.
`stop_time` datetime	Merging of `stop_time`s for the ad sets belonging to this campaign, if available. At the campaign level, `stop_time` is a read only field. You can setup `stop_time` at the ad set level.
`topline_id` numeric string	Topline ID
`updated_time` datetime	Updated Time. If you update `spend_cap` or daily budget or lifetime budget, this will not automatically update this field.

Edges

Edge	Description
`ad_studies` Edge<AdStudy>	The ad studies containing this campaign
`adrules_governed` Edge<AdRule>	Ad rules that govern this campaign - by default, this only returns rules that either directly mention the campaign by id or indirectly through the set entity_type
`ads` Edge<Adgroup>	Ads under this campaign
`adsets` Edge<AdCampaign>	The ad sets under this campaign
`copies` Edge<AdCampaignGroup>	The copies of this campaign

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.
2635	You are calling a deprecated version of the Ads API. Please update to the latest version.
190	Invalid OAuth 2.0 Access Token
104	Incorrect signature
200	Permissions error
3018	The start date of the time range cannot be beyond 37 months from the current date
2500	Error parsing graph query

Creating

You can make a POST request to async_batch_requests edge from the following paths:

/act_{ad_account_id}/async_batch_requests

When posting to this edge, a Campaign will be created.

Parameters

Parameter	Description
`adbatch` list<Object>	JSON encoded batch reqeust Required
`name` string	Required
`relative_url` string	Required
`body` UTF-8 encoded string	Required
`name` UTF-8 encoded string	Name of the batch request for tracking purposes. Required

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.

Struct {

id: numeric string,

}

Error Codes

Error	Description
100	Invalid parameter
2500	Error parsing graph query
194	Missing at least one required parameter

You can make a POST request to copies edge from the following paths:

/{campaign_id}/copies

When posting to this edge, a Campaign will be created.

Parameters

Parameter	Description
`deep_copy` boolean	Default value: `false` Whether to copy all the child ads. Limits: the total number of children ads to copy should not exceed 3 for a synchronous call and 51 for an asynchronous call.
`end_time` datetime	For deep copy, the end time of the sets under the copied campaign, e.g. `2015-03-12 23:59:59-07:00` or `2015-03-12 23:59:59 PDT`. UTC UNIX timestamp. When creating a set with a daily budget, specify `end_time=0` to set the set to be ongoing without end date. If not set, the copied sets will inherit the end time from the original set
`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.
`start_time` datetime	For deep copy, the start time of the sets under the copied campaign, e.g. `2015-03-12 23:59:59-07:00` or `2015-03-12 23:59:59 PDT`. UTC UNIX timestamp. If not set, the copied sets will inherit the start time from the original set
`status_option` enum {ACTIVE, PAUSED, INHERITED_FROM_SOURCE}	Default value: `PAUSED` `ACTIVE`: the copied campaign will have active status. `PAUSED`: the copied campaign will have paused status. `INHERITED_FROM_SOURCE`: the copied campaign will have the parent status.

Return Type

This endpoint supports read-after-write and will read the node represented by copied_campaign_id in the return type.

Struct {

copied_campaign_id: numeric string,

ad_object_ids: List [

Struct {

ad_object_type: enum {unique_adcreative, ad, ad_set, campaign, opportunities, privacy_info_center, topline, ad_account},

source_id: numeric string,

copied_id: numeric string,

}

Error Codes

Error	Description
100	Invalid parameter
200	Permissions error

You can make a POST request to campaigns edge from the following paths:

/act_{ad_account_id}/campaigns

When posting to this edge, a Campaign will be created.

Example

Graph API Explorer

POST /v21.0/act_<AD_ACCOUNT_ID>/campaigns HTTP/1.1
Host: graph.facebook.com

name=My+campaign&objective=OUTCOME_TRAFFIC&status=PAUSED&special_ad_categories=%5B%5D

/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/act_<AD_ACCOUNT_ID>/campaigns',
    array (
      'name' => 'My campaign',
      'objective' => 'OUTCOME_TRAFFIC',
      'status' => 'PAUSED',
      'special_ad_categories' => '[]',
    ),
    '{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>/campaigns",
    "POST",
    {
        "name": "My campaign",
        "objective": "OUTCOME_TRAFFIC",
        "status": "PAUSED",
        "special_ad_categories": "[]"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Bundle params = new Bundle();
params.putString("name", "My campaign");
params.putString("objective", "OUTCOME_TRAFFIC");
params.putString("status", "PAUSED");
params.putString("special_ad_categories", "[]");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/act_<AD_ACCOUNT_ID>/campaigns",
    params,
    HttpMethod.POST,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();

NSDictionary *params = @{
  @"name": @"My campaign",
  @"objective": @"OUTCOME_TRAFFIC",
  @"status": @"PAUSED",
  @"special_ad_categories": @"[]",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/act_<AD_ACCOUNT_ID>/campaigns"
                                      parameters:params
                                      HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

curl -X POST \
  -F 'name="My campaign"' \
  -F 'objective="OUTCOME_TRAFFIC"' \
  -F 'status="PAUSED"' \
  -F 'special_ad_categories=[]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/campaigns

If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

Parameter	Description
`adlabels` list<Object>	Ad Labels associated with this campaign
`bid_strategy` enum{LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS}	Choose bid strategy for this campaign to suit your specific business goals. Each strategy has tradeoffs and may be available for certain `optimization_goal`s: `LOWEST_COST_WITHOUT_CAP`: Designed to get the most results for your budget based on your ad set `optimization_goal` without limiting your bid amount. This is the best strategy if you care most about cost efficiency. However with this strategy it may be harder to get stable average costs as you spend. This strategy is also known as automatic bidding. Learn more in Ads Help Center, About bid strategies: Lowest cost. `LOWEST_COST_WITH_BID_CAP`: Designed to get the most results for your budget based on your ad set `optimization_goal` while limiting actual bid to your specified amount. With a bid cap you have more control over your cost per actual optimization event. However if you set a limit which is too low you may get less ads delivery. If you select this, you must provide a bid cap in the `bid_amount` field for each ad set in this ad campaign. Note: during creation this is the default bid strategy if you don't specify. This strategy is also known as manual maximum-cost bidding. Learn more in Ads Help Center, About bid strategies: Lowest cost. Notes: If you do not enable campaign budget optimization, you should set `bid_strategy` at ad set level. `TARGET_COST` bidding strategy has been deprecated with Marketing API v9.
`budget_schedule_specs` list<JSON or object-like arrays>	Initial high demand periods to be created with the campaign. Provide list of `time_start`, `time_end`,`budget_value`, and `budget_value_type`. For example, -F 'budget_schedule_specs=[{ "time_start":1699081200, "time_end":1699167600, "budget_value":100, "budget_value_type":"ABSOLUTE" }]' See High Demand Period for more details on each field.
`id` int64
`time_start` datetime
`time_end` datetime
`budget_value` int64
`budget_value_type` enum{ABSOLUTE, MULTIPLIER}
`recurrence_type` enum{ONE_TIME, WEEKLY}
`weekly_schedule` list<JSON or object-like arrays>
`days` list<int64>
`minute_start` int64
`minute_end` int64
`timezone_type` string
`buying_type` string	Default value: `AUCTION` This field will help Facebook make optimizations to delivery, pricing, and limits. All ad sets in this campaign must match the buying type. Possible values are: `AUCTION` (default) `RESERVED` (for reach and frequency ads).
`campaign_optimization_type` enum{NONE, ICO_ONLY}	campaign_optimization_type
`daily_budget` int64	Daily budget of this campaign. All adsets under this campaign will share this budget. You can either set budget at the campaign level or at the adset level, not both.
`execution_options` list<enum{validate_only, 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. 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.
`is_skadnetwork_attribution` boolean	To create an iOS 14 campaign, enable SKAdNetwork attribution for this campaign.
`is_using_l3_schedule` boolean	is_using_l3_schedule
`iterative_split_test_configs` list<Object>	Array of Iterative Split Test Configs created under this campaign .
`lifetime_budget` int64	Lifetime budget of this campaign. All adsets under this campaign will share this budget. You can either set budget at the campaign level or at the adset level, not both.
`name` string	Name for this campaign Supports Emoji
`objective` enum{APP_INSTALLS, BRAND_AWARENESS, CONVERSIONS, EVENT_RESPONSES, LEAD_GENERATION, LINK_CLICKS, LOCAL_AWARENESS, MESSAGES, OFFER_CLAIMS, OUTCOME_APP_PROMOTION, OUTCOME_AWARENESS, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_TRAFFIC, PAGE_LIKES, POST_ENGAGEMENT, PRODUCT_CATALOG_SALES, REACH, STORE_VISITS, VIDEO_VIEWS}	Campaign's objective. If it is specified the API will validate that any ads created under the campaign match that objective. Currently, with `BRAND_AWARENESS` objective, all creatives should be either only images or only videos, not mixed. See Outcome Ad-Driven Experience Objective Validation for more information.
`promoted_object` Object	The object this campaign is promoting across all its ads. It’s required for Meta iOS 14+ app promotion (SKAdNetwork or Aggregated Event Measurement) campaign creation. Only `product_catalog_id` is used at the ad set level.
`application_id` int	The ID of a Facebook Application. Usually related to mobile or canvas games being promoted on Facebook for installs or engagement
`pixel_id` numeric string or integer	The ID of a Facebook conversion pixel. Used with offsite conversion campaigns.
`custom_event_type` enum{AD_IMPRESSION, RATE, TUTORIAL_COMPLETION, CONTACT, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, SCHEDULE, START_TRIAL, SUBMIT_APPLICATION, SUBSCRIBE, ADD_TO_CART, ADD_TO_WISHLIST, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, PURCHASE, LEAD, COMPLETE_REGISTRATION, CONTENT_VIEW, SEARCH, SERVICE_BOOKING_REQUEST, MESSAGING_CONVERSATION_STARTED_7D, LEVEL_ACHIEVED, ACHIEVEMENT_UNLOCKED, SPENT_CREDITS, LISTING_INTERACTION, D2_RETENTION, D7_RETENTION, OTHER}	The event from an App Event of a mobile app, not in the standard event list.
`object_store_url` URL	The uri of the mobile / digital store where an application can be bought / downloaded. This is platform specific. When combined with the "application_id" this uniquely specifies an object which can be the subject of a Facebook advertising campaign.
`offer_id` numeric string or integer	The ID of an Offer from a Facebook Page.
`page_id` Page ID	The ID of a Facebook Page
`product_catalog_id` numeric string or integer	The ID of a Product Catalog. Used with Dynamic Product Ads.
`product_item_id` numeric string or integer	The ID of the product item.
`instagram_profile_id` numeric string or integer	The ID of the instagram profile id.
`product_set_id` numeric string or integer	The ID of a Product Set within an Ad Set level Product Catalog. Used with Dynamic Product Ads.
`event_id` numeric string or integer	The ID of a Facebook Event
`offline_conversion_data_set_id` numeric string or integer	The ID of the offline dataset.
`fundraiser_campaign_id` numeric string or integer	The ID of the fundraiser campaign.
`custom_event_str` string	The event from an App Event of a mobile app, not in the standard event list.
`mcme_conversion_id` numeric string or integer	The ID of a MCME conversion.
`conversion_goal_id` numeric string or integer	The ID of a Conversion Goal.
`offsite_conversion_event_id` numeric string or integer	The ID of a Offsite Conversion Event
`boosted_product_set_id` numeric string or integer	The ID of the Boosted Product Set within an Ad Set level Product Catalog. Should only be present when the advertiser has opted into Product Set Boosting.
`lead_ads_form_event_source_type` enum{inferred, offsite_crm, offsite_web, onsite_crm, onsite_web}	The event source of lead ads form.
`value_semantic_type` enum {VALUE, MARGIN, LIFETIME_VALUE}	The semantic of the event value to be using for optimization
`variation` enum {OMNI_CHANNEL_SHOP_AUTOMATIC_DATA_COLLECTION, PRODUCT_SET_AND_APP, PRODUCT_SET_AND_IN_STORE, PRODUCT_SET_AND_OMNICHANNEL, PRODUCT_SET_AND_WEBSITE}	Variation of the promoted object for a PCA ad
`omnichannel_object` Object
`app` array<JSON object>
`pixel` array<JSON object>	Required
`onsite` array<JSON object>
`whatsapp_phone_number` string
`source_campaign_id` numeric string or integer	Used if a campaign has been copied. The ID from the original campaign that was copied.
`special_ad_categories` array<enum {NONE, EMPLOYMENT, HOUSING, CREDIT, ISSUES_ELECTIONS_POLITICS, ONLINE_GAMBLING_AND_GAMING, FINANCIAL_PRODUCTS_SERVICES}>	special_ad_categories Required
`special_ad_category_country` array<enum {AD, AE, AF, AG, AI, AL, AM, AN, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, XK, YE, YT, ZA, ZM, ZW}>	special_ad_category_country
`spend_cap` int64	A spend cap for the campaign, such that it will not spend more than this cap. Defined as integer value of subunit in your currency with a minimum value of $100 USD (or approximate local equivalent). Set the value to 922337203685478 to remove the spend cap. Not available for Reach and Frequency or Premium Self Serve campaigns
`start_time` datetime	start_time
`status` enum{ACTIVE, PAUSED, DELETED, ARCHIVED}	Only `ACTIVE` and `PAUSED` are valid during creation. Other statuses can be used for update. If it is set to `PAUSED`, its active child objects will be paused and have an effective status `CAMPAIGN_PAUSED`.
`stop_time` datetime	stop_time
`topline_id` numeric string or integer	Topline ID

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
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.
200	Permissions error
190	Invalid OAuth 2.0 Access Token
2635	You are calling a deprecated version of the Ads API. Please update to the latest version.
368	The action attempted has been deemed abusive or is otherwise disallowed
2615	Invalid call to update this adaccount
300	Edit failure

Updating

You can update a Campaign by making a POST request to /{campaign_id}.

Parameters

Parameter	Description
`adlabels` list<Object>	Ad Labels associated with this campaign
`adset_bid_amounts` JSON object {numeric string : int64}	A map of child adset IDs to their respective bid amounts required in the process of toggling campaign from autobid to manual bid
`adset_budgets` array<JSON object>	An array of maps containing all the non-deleted child adset IDs and either daily_budget or lifetime_budget, required in the process of toggling between campaign budget and adset budget
`adset_id` numeric string	adset_id Required
`daily_budget` int64	daily_budget
`lifetime_budget` int64	lifetime_budget
`bid_strategy` enum{LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS}	Choose bid strategy for this campaign to suit your specific business goals. Each strategy has tradeoffs and may be available for certain `optimization_goal`s: `LOWEST_COST_WITHOUT_CAP`: Designed to get the most results for your budget based on your ad set `optimization_goal` without limiting your bid amount. This is the best strategy if you care most about cost efficiency. However with this strategy it may be harder to get stable average costs as you spend. This strategy is also known as automatic bidding. Learn more in Ads Help Center, About bid strategies: Lowest cost. `LOWEST_COST_WITH_BID_CAP`: Designed to get the most results for your budget based on your ad set `optimization_goal` while limiting actual bid to your specified amount. With a bid cap you have more control over your cost per actual optimization event. However if you set a limit which is too low you may get less ads delivery. If you select this, you must provide a bid cap in the `bid_amount` field for each ad set in this ad campaign. Note: during creation this is the default bid strategy if you don't specify. This strategy is also known as manual maximum-cost bidding. Learn more in Ads Help Center, About bid strategies: Lowest cost. `COST_CAP`: Designed to get the most results for your budget based on your ad set `optimization_goal` while limiting actual average cost per optimization event to a specified amount. Get specified cost cap in the `bid_amount` field for each ad set in this ad campaign. Learn more in Ads Help Center, About bid strategies: Cost Cap. Notes: If you do not enable campaign budget optimization, you should set `bid_strategy` at ad set level. `TARGET_COST` bidding strategy has been deprecated with Marketing API v9.
`budget_rebalance_flag` boolean	Whether to automatically rebalance budgets daily for all the adsets under this campaign.
`campaign_optimization_type` enum{NONE, ICO_ONLY}	campaign_optimization_type
`daily_budget` int64	Daily budget of this campaign. All adsets under this campaign will share this budget. You can either set budget at the campaign level or at the adset level, not both.
`execution_options` list<enum{validate_only, 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. 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.
`is_skadnetwork_attribution` boolean	Flag to indicate that the campaign will be using SKAdNetwork, which also means that it will only be targeting iOS 14.x and above
`is_using_l3_schedule` boolean	is_using_l3_schedule
`iterative_split_test_configs` list<Object>	Array of Iterative Split Test Configs created under this campaign .
`lifetime_budget` int64	Lifetime budget of this campaign. All adsets under this campaign will share this budget. You can either set budget at the campaign level or at the adset level, not both.
`name` string	Name for this campaign Supports Emoji
`objective` enum{APP_INSTALLS, BRAND_AWARENESS, CONVERSIONS, EVENT_RESPONSES, LEAD_GENERATION, LINK_CLICKS, LOCAL_AWARENESS, MESSAGES, OFFER_CLAIMS, OUTCOME_APP_PROMOTION, OUTCOME_AWARENESS, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_TRAFFIC, PAGE_LIKES, POST_ENGAGEMENT, PRODUCT_CATALOG_SALES, REACH, STORE_VISITS, VIDEO_VIEWS}	Campaign's objective. If it is specified the API will validate that any ads created under the campaign match that objective. Currently, with `BRAND_AWARENESS` objective, all creatives should be either only images or only videos, not mixed. See the Outcome Ad-Driven Experience Objective Validation section below for more information.
`promoted_object` Object	The object this campaign is promoting across all its ads. Only `product_catalog_id` is used at the ad set level.
`application_id` int	The ID of a Facebook Application. Usually related to mobile or canvas games being promoted on Facebook for installs or engagement
`pixel_id` numeric string or integer	The ID of a Facebook conversion pixel. Used with offsite conversion campaigns.
`custom_event_type` enum{AD_IMPRESSION, RATE, TUTORIAL_COMPLETION, CONTACT, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, SCHEDULE, START_TRIAL, SUBMIT_APPLICATION, SUBSCRIBE, ADD_TO_CART, ADD_TO_WISHLIST, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, PURCHASE, LEAD, COMPLETE_REGISTRATION, CONTENT_VIEW, SEARCH, SERVICE_BOOKING_REQUEST, MESSAGING_CONVERSATION_STARTED_7D, LEVEL_ACHIEVED, ACHIEVEMENT_UNLOCKED, SPENT_CREDITS, LISTING_INTERACTION, D2_RETENTION, D7_RETENTION, OTHER}	The event from an App Event of a mobile app, not in the standard event list.
`object_store_url` URL	The uri of the mobile / digital store where an application can be bought / downloaded. This is platform specific. When combined with the "application_id" this uniquely specifies an object which can be the subject of a Facebook advertising campaign.
`offer_id` numeric string or integer	The ID of an Offer from a Facebook Page.
`page_id` Page ID	The ID of a Facebook Page
`product_catalog_id` numeric string or integer	The ID of a Product Catalog. Used with Dynamic Product Ads.
`product_item_id` numeric string or integer	The ID of the product item.
`instagram_profile_id` numeric string or integer	The ID of the instagram profile id.
`product_set_id` numeric string or integer	The ID of a Product Set within an Ad Set level Product Catalog. Used with Dynamic Product Ads.
`event_id` numeric string or integer	The ID of a Facebook Event
`offline_conversion_data_set_id` numeric string or integer	The ID of the offline dataset.
`fundraiser_campaign_id` numeric string or integer	The ID of the fundraiser campaign.
`custom_event_str` string	The event from an App Event of a mobile app, not in the standard event list.
`mcme_conversion_id` numeric string or integer	The ID of a MCME conversion.
`conversion_goal_id` numeric string or integer	The ID of a Conversion Goal.
`offsite_conversion_event_id` numeric string or integer	The ID of a Offsite Conversion Event
`boosted_product_set_id` numeric string or integer	The ID of the Boosted Product Set within an Ad Set level Product Catalog. Should only be present when the advertiser has opted into Product Set Boosting.
`lead_ads_form_event_source_type` enum{inferred, offsite_crm, offsite_web, onsite_crm, onsite_web}	The event source of lead ads form.
`value_semantic_type` enum {VALUE, MARGIN, LIFETIME_VALUE}	The semantic of the event value to be using for optimization
`variation` enum {OMNI_CHANNEL_SHOP_AUTOMATIC_DATA_COLLECTION, PRODUCT_SET_AND_APP, PRODUCT_SET_AND_IN_STORE, PRODUCT_SET_AND_OMNICHANNEL, PRODUCT_SET_AND_WEBSITE}	Variation of the promoted object for a PCA ad
`omnichannel_object` Object
`app` array<JSON object>
`pixel` array<JSON object>	Required
`onsite` array<JSON object>
`whatsapp_phone_number` string
`smart_promotion_type` enum{GUIDED_CREATION, SMART_APP_PROMOTION}	smart_promotion_type
`special_ad_categories` array<enum {NONE, EMPLOYMENT, HOUSING, CREDIT, ISSUES_ELECTIONS_POLITICS, ONLINE_GAMBLING_AND_GAMING, FINANCIAL_PRODUCTS_SERVICES}>	special_ad_categories
`special_ad_category` enum{NONE, EMPLOYMENT, HOUSING, CREDIT, ISSUES_ELECTIONS_POLITICS, ONLINE_GAMBLING_AND_GAMING, FINANCIAL_PRODUCTS_SERVICES}	special_ad_category
`special_ad_category_country` array<enum {AD, AE, AF, AG, AI, AL, AM, AN, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, XK, YE, YT, ZA, ZM, ZW}>	special_ad_category_country
`spend_cap` int64	A spend cap for the campaign, such that it will not spend more than this cap. Defined as integer value of subunit in your currency with a minimum value of $100 USD (or approximate local equivalent). Set the value to 922337203685478 to remove the spend cap. Not available for Reach and Frequency or Premium Self Serve campaigns
`start_time` datetime	start_time
`status` enum{ACTIVE, PAUSED, DELETED, ARCHIVED}	Only `ACTIVE` and `PAUSED` are valid during creation. Other statuses can be used for update. If it is set to `PAUSED`, its active child objects will be paused and have an effective status `CAMPAIGN_PAUSED`.
`stop_time` datetime	stop_time

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.

Struct {

success: bool,

}

Error Codes

Error	Description
100	Invalid parameter
200	Permissions error
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.
2625	The request for a reach frequency campaign is invalid.
190	Invalid OAuth 2.0 Access Token

Deleting

You can delete a Campaign by making a DELETE request to /{campaign_id}.

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

You can dissociate a Campaign from an AdAccount by making a DELETE request to /act_{ad_account_id}/campaigns.

Parameters

Parameter Description

Parameter	Description
`before_date` datetime	Set a before date to delete campaigns before this date
`delete_strategy` enum{DELETE_ANY, DELETE_OLDEST, DELETE_ARCHIVED_BEFORE}	Delete strategy Required
`object_count` integer	Object count

before_date

datetime

Set a before date to delete campaigns before this date

delete_strategy

enum{DELETE_ANY, DELETE_OLDEST, DELETE_ARCHIVED_BEFORE}

Delete strategy

Required

object_count

integer

Object count

Return Type

Struct {

objects_left_to_delete_count: unsigned int32,

deleted_object_ids: List [

numeric string

}

Error Codes

Error	Description
100	Invalid parameter

Objective Validation

These older objectives are deprecated with the release of Marketing API v17.0. Please refer to the Outcome-Driven Ads Experiences mapping table below to find the new objectives and their corresponding destination types, optimization goals and promoted objects.

Your campaign objective choice can limit the settings available to you.

Optimization Goals

Certain campaign objectives support only certain ad set optimization_goals. See Bidding Overview, Validation.

Compatible Ad Types

Objective	Compatible Ad Types
`APP_INSTALLS`	Image Ads Video Ads Carousel Ads Instant Experience Ads App Ads Instagram Ads (see placement limitations) Segment Asset Customization Ads Placement Asset Customization Ads Multi-Language Ads Dynamic Ads Dynamic Creative
`BRAND_AWARENESS`	Image Ads Video Ads Carousel Ads Instant Experience Ads Instagram Ads (see placement limitations) Segment Asset Customization Ads Placement Asset Customization Ads Multi-Language Ads Dynamic Creative
`CONVERSIONS`	Image Ads Video Ads Carousel Ads Instant Experience Ads Collection Ads App Ads Instagram Ads (see placement limitations) Ads that click to Messenger Offer Ads Segment Asset Customization Ads Placement Asset Customization Ads Multi-Language Ads Dynamic Ads Dynamic Creative
`EVENT_RESPONSES`	Image Ads Video Ads Carousel Ads Event and Local Ads
`LEAD_GENERATION`	Image Ads Video Ads Carousel Ads Lead Ads Instagram Ads (see placement limitations) Placement Asset Customization Ads Dynamic Creative
`LINK_CLICKS`	Image Ads Video Ads Carousel Ads Instant Experience Ads Collection Ads App Ads Instagram Ads (see placement limitations) Offer Ads Segment Asset Customization Ads Placement Asset Customization Ads Multi-Language Ads Dynamic Ads Dynamic Creative
`MESSAGES`	Image Ads Video Ads Carousel Ads Instagram Ads (see placement limitations) Messenger Ads
`POST_ENGAGEMENT`	Image Ads Carousel Ads Instant Experience Ads Instagram Ads (see placement limitations)
`PRODUCT_CATALOG_SALES`	Image Ads Carousel Ads Collection Ads Instagram Ads (see placement limitations) Dynamic Ads Collaborative Ads
`REACH`	Image Ads Video Ads Carousel Ads Instant Experience Ads Instagram Ads (see placement limitations) Segment Asset Customization Ads Placement Asset Customization Ads Multi-Language Ads Dynamic Creative
`STORE_VISITS`	Image Ads Carousel Ads Instant Experience Ads Collection Ads Instagram Ads (see placement limitations) Offer Ads
`VIDEO_VIEWS`	Video Ads Carousel Ads Instant Experience Ads Instagram Ads (see placement limitations) Segment Asset Customization Ads Placement Asset Customization Ads Multi-Language Ads Dynamic Creative

Objectives and Creative Fields

See our ads guide for a list of creatives supported per objective. In the API, the objective determines which ad creatives are valid.

Objective	Creative Fields
`APP_INSTALLS`	`object_story_id` or `object_story_spec`
`CONVERSIONS`	`object_story_id` or `object_story_spec` Notes: If you are creating link ads not connected to a page, use the following creative fields: `title`, `body`, `object_url`, and `image_file` or `image_hash`. Creative cannot include link ads pointing to an app store.
`EVENT_RESPONSES`	`object_story_id` or `object_story_spec`
`LEAD_GENERATION`	`object_story_id` or `object_story_spec`
`LINK_CLICKS`	`object_story_id` or `object_story_spec` Notes: Creative cannot include link ads pointing to an app store. If you select `LINK_CLICKS` as both optimization goal and billing event, you must include `call_to_action`.
`MESSAGES`	`object_story_spec`
`PAGE_LIKES`	`object_story_id`, `object_story_spec`, `object_id`, and `body`
`POST_ENGAGEMENT`	`object_story_id` or `object_story_spec` Note: Creative cannot include link ads pointing to an app store.
`VIDEO_VIEWS`	`object_story_id` or `object_story_spec`

Objectives and Tracking Specs

Tracking specs are applied by default based on the objective specified, please see the full list of defaults by objective here.

There are two important scenarios to take into account:

Tracking pixels are not applied by default, and you must specify it explicitly when your objective is CONVERSIONS.
Mobile app ads will no longer track installs or app events by default. You must explicitly specify to track installs or app events for mobile app ads otherwise your ad will not track.

To specify to track an install or app event, set the following in your ad:

tracking_specs=[{'action.type':['mobile_app_install'],'application':[{your_app_id}]},{'action.type':['app_custom_event'],'application':[{your_app_id}]}]

Objective and Promoted Objects

Certain objectives require the promoted_object to be set in ad sets. See Promoted Object for more information.

Objective	Required promoted_object Fields
`APP_INSTALLS`	`application_id` and `object_store_url` If `optimization_goal` is `OFFSITE_CONVERSIONS`: `application_id`, `object_store_url`, and `custom_event_type`
`CONVERSIONS`	`pixel_id` (Conversion pixel ID) `pixel_id` (Facebook pixel ID) and `custom_event_type` `pixel_id` (Facebook pixel ID), `pixel_rule`, and `custom_event_type` `event_id` (Facebook event ID) and `custom_event_type` For mobile app events: `application_id`, `object_store_url`, and `custom_event_type` For offline conversions: `offline_conversion_data_set_id` (Offline dataset ID), and `custom_event_type`
`LINK_CLICKS`	For mobile app or Instant Experiences app engagement link clicks: `application_id` and `object_store_url`.
`PRODUCT_CATALOG_SALES`	`product_set_id`, or `product_set_id` and `custom_event_type`
`PAGE_LIKES`	`page_id`
`OFFER_CLAIMS`	`page_id`

Objective and Placements

Certain types of ad placements are valid only for specific objectives or creatives. See Business Help Center, Available ad placements for marketing objectives.

The table below shows some placements and their compatible objectives or creatives. You can pick a combination of those compatible placements. Note that:

With LEAD_GENERATION, device_platforms: desktop cannot be selected together with publisher_platforms: instagram.
If your objective is website traffic, story for facebook_positions does not support destination_type: messenger.
If your objective is website traffic, story for messenger_positions does not support destination_type: messenger.
If your objective is website traffic, ig_search and explore_home for instagram_positions do not support destination_type: whatsapp & messenger.

Objective	Creative	Placement
`APP_INSTALLS`, promoting an Instant Experiences app	Desktop app ads	`device_platforms`: `desktop`
`APP_INSTALLS`, promoting a mobile app	Photo or video mobile app ads	`device_platforms`: `mobile` `publisher_platforms`: `facebook`, `feed`, `instagram`, `audience_network` `facebook_positions`: `feed`, `video_feeds`, `instant articles` and `story` `audience_network_positions`: `classic`, `rewarded_video` `messenger_positions`: `story`
`BRAND_AWARENESS`	all	`publisher_platforms`: `facebook`, `instagram`, `audience_network`. `facebook_positions`: `feed`, `video_feeds`, `instream_video` and `story`, which is currently under limited availability `instagram_positions`: `stream` `audience_network_positions`: `classic`, `instream_video`
`CONVERSIONS`	Photo or video link ads from a page	We support `BRAND_AWARENESS`, `APP_INSTALL`, `POST_ENGAGEMENT`, `VIDEO_VIEWS`, `REACH`, `WEBSITE_CONVERSIONS`, and `TRAFFIC`. Also supported: `right_hand_column` and `story` for `facebook_positions` and `messenger_positions`: `messenger_home` and `story`. `facebook_positions`: `story` only supports the objective `WEBSITE_CONVERSIONS` `messenger_positions`: `story` only supports the objective `WEBSITE_CONVERSIONS` Exception: `instream_video` is not supported for this objective.
`CONVERSIONS`	Link ads not connected to a page	`facebook_positions`: `right_hand_column`
`CONVERSIONS` (promoting mobile app)	Photo or video mobile app ads	`device_platforms`: `mobile`. `facebook_positions`: `right_hand_column` and `story`. `story` as a `facebook_positions` for this objective does not support `destination_type`: `messenger`. `messenger_positions`: `messenger_home` `story` as a `messenger_positions` for this objective does not support `destination_type: messenger`.
`EVENT_RESPONSES`	Event ads	As of 3.0, you cannot use `right_hand_column` for `facebook_positions`
`EVENT_RESPONSES`	Page post ads	`publisher_platforms`: `facebook`. As of 3.0, you cannot use `right_hand_column` for `facebook_positions`
`LEAD_GENERATION`	Page post ads	`device_platforms`: `mobile`, `desktop` `publisher_platforms`: `facebook`, `instagram` `facebook_positions`: `feed` and `story`, which is in limited availability instagram_positions: stream As of 3.0, you cannot use `right_hand_column` for `facebook_positions`
`LINK_CLICKS`	Photo or video link ads from a page	All, including `right_hand_column` and `messenger_positions`: `messenger_home` and `story`.
`LINK_CLICKS`	Link ads not connected to a page	`facebook_positions`: `right_hand_column`
`LINK_CLICKS`, promoting an Instant Experiences app	Desktop app ads	`device_platforms`: `desktop` `facebook_positions`: `right_hand_column`
`LINK_CLICKS`, promoting a mobile app	Photo or video mobile app ads	`device_platforms`: `mobile`, `facebook_positions`: `right_hand_column`
`PAGE_LIKES`	Video creatives	`publisher_platforms`: `facebook` As of 3.0, you cannot use `right_hand_column` for `facebook_positions`
`POST_ENGAGEMENT`	Page post ads with video or photo	`publisher_platforms`: `facebook`, `instagram` `device_platforms`: `mobile`, `desktop` As of 3.0, you cannot use `right_hand_column` for `facebook_positions`
`POST_ENGAGEMENT`	Page post ads with text only	`publisher_platforms`: `facebook`, `instagram` `device_platforms`: `mobile`, `desktop` As of 3.0, you cannot use `right_hand_column` for `facebook_positions`
`POST_ENGAGEMENT`	New campaign	`publisher_platforms`: `facebook`, `instagram` As of 3.0, you cannot use `right_hand_column` for `facebook_positions`
`PRODUCT_CATALOG_SALES`	dynamic ads	All, including `right_hand_column` for `facebook_positions`.
`REACH`	Reach ads	All except `right_hand_column` for `facebook_positions` as of 3.0. Includes `messenger_positions`: `story` and `story` for `facebook_positions`.
`STORE_VISITS`	store visit ads	`publisher_platforms`: `facebook` As of 3.0, you cannot use `right_hand_column` for `facebook_positions`
`VIDEO_VIEWS`	Video ads	`publisher_platforms`: `facebook`, `instagram`, `audience_network`. Includes `story` for `facebook_positions` but not with the `optimation_goal` set to `TWO_SECOND_CONTINUOUS_VIDEO_VIEWS`. As of 3.0, you cannot use `right_hand_column` for `facebook_positions`

Objective, Optimization Goal and `attribution_spec`

Use click-through and view-through attribution windows for ad set to track conversions then use for ads delivery optimization. This is different from the attribution window you use for ads reporting. With attribution_spec, select a combination of click-through or view-through windows of 1 day or 7 days. The combinations you can use depend on your ad set's optimization_goal and campaign's objective.

Recommended Default attribution_spec

You may not have provided attribution_spec when you created ads sets optimized for Value Optimization. This is an optimization available for conversions, app installs, and product catalog sales objectives. In the past, we defaulted to a 1-day click through attribution window.

Objective	Optimization Goal	Allowed Combination
`CONVERSIONS, PRODUCT_CATALOG_SALES`	`OFFSITE_CONVERSIONS`	1-day click 7-day click 1-day click and 1-day view 7-day click and 1-day view
`APP_INSTALLS, LINK_CLICKS`	`OFFSITE_CONVERSIONS`	1-day click 7-day click (`LINK_CLICKS` only)
`APP_INSTALLS`	`APP_INSTALLS`	1-day click 1-day click and 1-day view
`CONVERSIONS`	`INCREMENTAL_OFFSITE_ CONVERSIONS`	Null click, Null view

For all other optimization_goal and objective combinations, you can only use 1-day click for attribution_spec.

Outcome-Driven Ads Experiences Objective Validation

Objective values

The following are newer objectives:

OUTCOME_APP_PROMOTION
OUTCOME_AWARENESS
OUTCOME_ENGAGEMENT
OUTCOME_LEADS
OUTCOME_SALES
OUTCOME_TRAFFIC

These newer objectives will eventually replace the original objectives APP_INSTALLS, BRAND_AWARENESS, CONVERSIONS, EVENT_RESPONSES, LEAD_GENERATION, LINK_CLICKS, LOCAL_AWARENESS, MESSAGES, OFFER_CLAIMS, PAGE_LIKES, POST_ENGAGEMENT, PRODUCT_CATALOG_SALES, REACH, STORE_VISITS, VIDEO_VIEWS. We will continue supporting these original objectives throughout 2022.

Limitations

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.

Example

Outcome-Driven Ads Experiences

curl -X POST \  
  -F 'name="New ODAX Campaign"' \  
  -F 'objective="OUTCOME_ENGAGEMENT"' \  
  -F 'status="PAUSED"' \  
  -F 'special_ad_categories=[]' \  
  -F 'access_token=ACCESS_TOKEN \  
  https://graph.facebook.com/v11.0/
  act_AD_ACCOUNT_ID/campaigns

Legacy

curl -X POST \
  -F 'name="New Campaign"' \
  -F 'objective="APP_INSTALLS"' \
  -F 'status="PAUSED"' \
  -F 'special_ad_categories=[]' \
  -F 'access_token=ACCESS_TOKEN \
  https://graph.facebook.com/v11.0/
  act_AD_ACCOUNT_ID/campaigns

Objective Mapping

Old Objective	New Objective	Destination Type	Optimization Goal	Promoted Object
`BRAND_AWARENESS`	`OUTCOME_AWARENESS`	—	`AD_RECALL_LIFT`	`page_id`
`REACH`	`OUTCOME_AWARENESS`	—	`REACH`	`page_id`
`REACH`	`OUTCOME_AWARENESS`	—	`IMPRESSIONS`	`page_id`
`LINK_CLICKS`	`OUTCOME_TRAFFIC`	—	`LINK_CLICKS`	`application_id`, `object_store_url`
			`LANDING_PAGE_VIEWS`	—
			`REACH`	`application_id`, `object_store_url`
			`IMPRESSIONS`	—
		`MESSENGER`	`LINK_CLICKS`	—
			`REACH`	—
			`IMPRESSIONS`	—
		`WHATSAPP`	`LINK_CLICKS`	`page_id`
			`REACH`	`page_id`
			`IMPRESSIONS`	`page_id`
		`PHONE_CALL`	`QUALITY_CALL`	—
		`PHONE_CALL`	`LINK_CLICKS`	—
`POST_ENGAGEMENT`	`OUTCOME_ENGAGEMENT`	`ON_POST`	`POST_ENGAGEMENT`	—
			`REACH`	—
			`IMPRESSIONS`	—
`PAGE_LIKES`	`OUTCOME_ENGAGEMENT`	`ON_PAGE`	`PAGE_LIKES`	`page_id`
`EVENT_RESPONSES`	`OUTCOME_ENGAGEMENT`	`ON_EVENT`	`EVENT_RESPONSES`	—
			`POST_ENGAGEMENT`	—
			`REACH`	—
			`IMPRESSIONS`	—
`APP_INSTALL`	`OUTCOME_APP_PROMOTION`	—	`LINK_CLICKS`	`application_id`, `object_store_url`
			`OFFSITE_CONVERSIONS`	`application_id`, `object_store_url`
			`APP_INSTALLS`	`application_id`, `object_store_url`
`VIDEO_VIEWS`	`OUTCOME_AWARENESS`	—	`THRUPLAY`	`page_id`
	`OUTCOME_AWARENESS`	—	`TWO_SECOND_CONTINUOUS_VIDEO_VIEWS`	`page_id`
	`OUTCOME_ENGAGEMENT`	`ON_VIDEO`	`THRUPLAY`	—
	`OUTCOME_ENGAGEMENT`	`ON_VIDEO`	`TWO_SECOND_CONTINUOUS_VIDEO_VIEWS`	—
`LEAD_GENERATION`	`OUTCOME_LEADS`	`ON_AD`	`LEAD_GENERATION`	`page_id`
		`ON_AD`	`QUALITY_LEAD`	`page_id`
		`LEAD_FROM_MESSENGER`	`LEAD_GENERATION`	`page_id`
		`LEAD_FROM_IG_DIRECT`	`LEAD_GENERATION`	`page_id`
		`PHONE_CALL`	`QUALITY_CALL`	`page_id`
`MESSAGES`	`OUTCOME_ENGAGEMENT`	`MESSENGER`	`CONVERSATIONS`	`page_id`
		`MESSENGER`	`LINK_CLICKS`	`page_id`
		`MESSENGER`	`LEAD_GENERATION`	`page_id`
`CONVERSIONS` (See Available conversion locations and events by objective in Meta Ads Manager for more information on available conversion events by objective.)	`OUTCOME_ENGAGEMENT`	—	`OFFSITE_CONVERSIONS`	`pixel_id`, `custom_event_type`
			`OFFSITE_CONVERSIONS`	`application_id`, `object_store_url`
			`LINK_CLICKS`	`pixel_id`, `custom_event_type`
			`LINK_CLICKS`	`application_id`, `object_store_url`
			`REACH`	`pixel_id`, `custom_event_type`
			`REACH`	`application_id`, `object_store_url`
			`LANDING_PAGE_VIEWS`	`pixel_id`, `custom_event_type`
			`IMPRESSIONS`	`pixel_id`, `custom_event_type`
	`OUTCOME_LEADS`	—	`OFFSITE_CONVERSIONS`	`pixel_id`, `custom_event_type`
			`OFFSITE_CONVERSIONS`	`application_id`, `object_store_url`
			`LINK_CLICKS`	`pixel_id`, `custom_event_type`
			`LINK_CLICKS`	`application_id`, `object_store_url`
			`REACH`	`pixel_id`, `custom_event_type`
			`REACH`	`application_id`, `object_store_url`
			`LANDING_PAGE_VIEWS`	`pixel_id`, `custom_event_type`
			`IMPRESSIONS`	`pixel_id`, `custom_event_type`
	`OUTCOME_SALES`	—	`OFFSITE_CONVERSIONS`	`pixel_id`, `custom_event_type`
		—	`OFFSITE_CONVERSIONS`	`application_id`, `object_store_url`
		`MESSENGER`	`CONVERSATIONS`	`page_id`, `pixel_id`, `custom_event_type`
		`PHONE_CALL`	`QUALITY_CALL`	`page_id`
`PRODUCT_CATALOG_SALES`	`OUTCOME_SALES`	`WEBSITE`	`LINK_CLICKS`	Campaign: `product_catalog_id` Ad set: `product_set_id`, `custom_event_type`
`STORE_VISITS`	`OUTCOME_AWARENESS`	—	`REACH`	`place_page_set_id`

Campaign

Limits

New Required Field for All Campaigns

Reading

Example

Parameters

Fields

Edges

Error Codes

Creating

Parameters

Return Type

Error Codes

Parameters

Return Type

Error Codes

Example

Parameters

Return Type

Error Codes

Updating

Parameters

Return Type

Error Codes

Deleting

Parameters

Return Type

Error Codes

Parameters

Return Type

Error Codes

Objective Validation

Optimization Goals

Compatible Ad Types

Objectives and Creative Fields

Objectives and Tracking Specs

Objective and Promoted Objects

Objective and Placements

Objective, Optimization Goal and attribution_spec

Outcome-Driven Ads Experiences Objective Validation

Objective values

Limitations

Example

Objective Mapping

Objective, Optimization Goal and `attribution_spec`