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. Learn more about Ad Campaign.

New Required Field For All Campaigns

Facebook is committed to protecting people from discrimination, and we are continually improving our ability to detect and deter potential abuse. It’s already against our policies to discriminate by wrongfully targeting or excluding specific groups of people. As part of a historic settlement agreement, we are making changes to the way we manage housing, employment and credit ads.

We have introduced a new field for campaign creation called special_ad_category. special_ad_category should be one of the following: HOUSING, CREDIT, EMPLOYMENT, or NONE. Campaigns set as HOUSING, EMPLOYMENT, or CREDIT have a restricted set of targeting options available. See key changes and dates to note:

  • December 4, 2019: By this date, businesses located in the US or targeting users in the US will be required to identify new and edited ad campaigns that offer housing, employment, or credit opportunities, or their ads will not be allowed to run. Businesses must specify a Special Ad Category and use the limited audience criteria available for Special Ad Category campaigns. This applies across all ad buying surfaces, including the Marketing API.
  • February 11, 2020: By this date, businesses located in the US or targeting users in the US will be required to identify any active campaigns that belong to a Special Ad Category and update the targeting settings for such campaigns, or these ads will no longer be allowed to run. This applies to all campaigns that were created or edited before Dec. 4, 2019 across all ad buying surfaces, including through the Marketing API.
  • March 31, 2020: By this date, all businesses using the Marketing API must identify whether or not new and edited campaigns belong to a Special Ad Category and update their targeting settings to comply with restrictions for Special Ad Category campaigns, or their ads will not be allowed to run. Businesses whose ads do not offer housing, employment or credit opportunities will have to indicate ‘NONE’ in the Special Ad Category field for all campaigns through the Marketing API.

If using Marketing API v5.0 or above, the Special Ad Category field is required for all ads, whether offering housing, employment or credit opportunities or not. See Special Ad Category for more 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 v5.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();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* 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

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

Date Preset

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

Time Range

since
datetime

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

until
datetime

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

Fields

FieldDescription
id
numeric string

Campaign's ID

account_id
numeric string

ID of the ad account that owns this campaign

adlabels

Ad Labels associated with this campaign

bid_strategy
enum {LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, TARGET_COST}

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.
TARGET_COST: Maintains a stable average cost based on your optimization_goal as you raise your campaign budget. We recommend this strategy if you care most about maintaining stable average costs for your ads. However, note that this may be less cost-efficient than the lowest cost strategy. Get specified target cost in the bid_amount field for each ad set in this ad campaign. Target cost bid strategy is also known as manual average-cost bidding. Learn more in Ads Help Center, About bid strategies: Target cost.
Note: If you do not enable campaign budget optimization, you should get bid_strategy at the ad set level.

boosted_object_id
numeric string

The Boosted Object this campaign has associated, if any

brand_lift_studies

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.

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.

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

issues_info

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

pacing_type
list<string>

Defines pacing type of the campaign. The value is an array of options: "standard".

promoted_object

The object this campaign is promoting across all its ads

recommendations

If there are recommendations for this campaign, this field includes them. Otherwise, will not be included in the response. (This field is not included in redownload mode.)

source_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_category
enum

The campaign's Special Ad Category. One of HOUSING, EMPLOYMENT, CREDIT, or NONE.

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

Start Time

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

Stop Time

topline_id
numeric string

Topline ID

updated_time
datetime

Updated Time. If you update spend_cap, this will not automatically update this field.

Edges

EdgeDescription

The ad studies containing this campaign

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 under this campaign

The ad sets under this campaign

The copies of this campaign

Validation Rules

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

Creating

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

Parameters

ParameterDescription
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,
}

Validation Rules

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

Parameters

ParameterDescription
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, topline, ad_account},
source_id: numeric string,
copied_id: numeric string,
}
],
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
You can make a POST request to campaigns edge from the following paths:
When posting to this edge, a Campaign will be created.

Example

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

name=My+campaign&objective=LINK_CLICKS&status=PAUSED
/* 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' => 'LINK_CLICKS',
      '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>/campaigns",
    "POST",
    {
        "name": "My campaign",
        "objective": "LINK_CLICKS",
        "status": "PAUSED"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("name", "My campaign");
params.putString("objective", "LINK_CLICKS");
params.putString("status", "PAUSED");
/* 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();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"name": @"My campaign",
  @"objective": @"LINK_CLICKS",
  @"status": @"PAUSED",
};
/* 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 \
     -d "name=My+campaign" \
     -d "objective=LINK_CLICKS" \
     -d "status=PAUSED" \
        https://graph.facebook.com/v5.0/act_<AD_ACCOUNT_ID>/campaigns
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

ParameterDescription
adlabels
list<Object>

Ad Labels associated with this campaign

bid_strategy
enum{LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, TARGET_COST}

Choose bid strategy for this campaign to suit your specific business goals. Each strategy has tradeoffs and may be available for certain optimization_goals:
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.
TARGET_COST: Maintains a stable average cost based on your optimization_goal as you raise your campaign budget. Select this strategy if you care most about maintaining stable average costs for your ads. However, note this strategy may be less cost-efficient than the lowest cost strategy. If you select this, you must provide a target cost in the bid_amount field for each ad set in this ad campaign. Target cost bid strategy is also known as manual average-cost bidding. Learn more in Ads Help Center, About bid strategies: Target cost.
Note: If you do not enable campaign budget optimization, you should set bid_strategy at ad set level.

budget_rebalance_flag
boolean

Whether to automatically rebalance budgets daily for all the adsets under this campaign.

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

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.

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, PAGE_LIKES, POST_ENGAGEMENT, PRODUCT_CATALOG_SALES, REACH, 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.

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

omnichannel_object
Object

app
list<Object>

application_id
App ID

custom_event_type
enum {JOB_ALERT_SUBSCRIBE, JOB_APPLICATION_CREATE, JOB_APPLICATION_FORM_IMPRESSION, JOB_BROWSER_IMPRESSION, JOB_OPENING_DETAIL_VIEW_IMPRESSION, ACTIVATE_APP, COMPLETE_REGISTRATION, CONTENT_VIEW, ONSITE_APP_CONTENT_VIEW, ONSITE_WEB_CONTENT_VIEW, ONSITE_WEB_APP_CONTENT_VIEW, SEARCH, RATE, TUTORIAL_COMPLETION, CONTACT, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, SCHEDULE, START_TRIAL, SUBMIT_APPLICATION, SUBSCRIBE, RECURRING_SUBSCRIPTION_PAYMENT, CANCEL_SUBSCRIPTION, VISIT_LOCATION, AD_CLICK, AD_IMPRESSION, ADD_TO_CART, ONSITE_APP_ADD_TO_CART, ONSITE_WEB_ADD_TO_CART, ONSITE_WEB_APP_ADD_TO_CART, ADD_TO_WISHLIST, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, PURCHASE, ONSITE_APP_PURCHASE, ONSITE_WEB_PURCHASE, ONSITE_WEB_APP_PURCHASE, MESSAGE_TO_BUY, LEAD, ONSITE_WEB_LEAD, LEVEL_ACHIEVED, ACHIEVEMENT_UNLOCKED, SPENT_CREDITS, FLOW_COMPLETE, SERVICE_BOOKING_REQUEST, MESSAGING_ACCEPT, MESSAGING_BLOCK, MESSAGING_DELETE_THREAD, MESSAGING_MARK_SPAM, MESSAGING_REPLY, MESSAGING_FIRST_REPLY, MESSAGING_OPEN_THREAD, MESSAGING_IGNORE_REQUEST, MESSAGING_PROMOTIONAL_OFF, MESSAGING_READ_RECEIPT, MESSAGING_DELIVERY_RECEIPT, MESSAGING_DELETE_MESSAGE, MESSAGING_CONVERSATION_STARTED_7D, MESSAGING_DEEP_CONVERSATION, MESSAGING_AUTOMATED_FLOW_COMPLETE, MESSAGING_AUTOMATED_FLOW_CANCELLED, MESSENGER_RECEIPT_TEMPLATE, REFERRAL_SENDER_INVITES_SENT, REFERRAL_SENDER_MESSAGE_SENT, REFERRAL_RECEIVER_IMPRESSION, REFERRAL_RECEIVER_CLICK, VIDEO_HOME_SELECTED, VIDEO_HOME_WATCHLIST, VIDEO_HOME_EXPLORE, VIDEO_HOME_PLAYER_START, VIDEO_HOME_90_SECOND_VIEW, FUNDRAISER_CREATE, MESSENGER_CONNECTED_CALL, MESSENGER_MISSED_CALL, D2_RETENTION, D7_RETENTION, MOVIE_SHOWTIME_CLICK, LISTING_INTERACTION, PDP_VIEW, CLICK_TO_CALL, CLICK_TO_WEBSITE, POST_SHARE, OTHER}

object_store_urls
list<string>

pixel
list<Object>

custom_event_type
enum {JOB_ALERT_SUBSCRIBE, JOB_APPLICATION_CREATE, JOB_APPLICATION_FORM_IMPRESSION, JOB_BROWSER_IMPRESSION, JOB_OPENING_DETAIL_VIEW_IMPRESSION, ACTIVATE_APP, COMPLETE_REGISTRATION, CONTENT_VIEW, ONSITE_APP_CONTENT_VIEW, ONSITE_WEB_CONTENT_VIEW, ONSITE_WEB_APP_CONTENT_VIEW, SEARCH, RATE, TUTORIAL_COMPLETION, CONTACT, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, SCHEDULE, START_TRIAL, SUBMIT_APPLICATION, SUBSCRIBE, RECURRING_SUBSCRIPTION_PAYMENT, CANCEL_SUBSCRIPTION, VISIT_LOCATION, AD_CLICK, AD_IMPRESSION, ADD_TO_CART, ONSITE_APP_ADD_TO_CART, ONSITE_WEB_ADD_TO_CART, ONSITE_WEB_APP_ADD_TO_CART, ADD_TO_WISHLIST, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, PURCHASE, ONSITE_APP_PURCHASE, ONSITE_WEB_PURCHASE, ONSITE_WEB_APP_PURCHASE, MESSAGE_TO_BUY, LEAD, ONSITE_WEB_LEAD, LEVEL_ACHIEVED, ACHIEVEMENT_UNLOCKED, SPENT_CREDITS, FLOW_COMPLETE, SERVICE_BOOKING_REQUEST, MESSAGING_ACCEPT, MESSAGING_BLOCK, MESSAGING_DELETE_THREAD, MESSAGING_MARK_SPAM, MESSAGING_REPLY, MESSAGING_FIRST_REPLY, MESSAGING_OPEN_THREAD, MESSAGING_IGNORE_REQUEST, MESSAGING_PROMOTIONAL_OFF, MESSAGING_READ_RECEIPT, MESSAGING_DELIVERY_RECEIPT, MESSAGING_DELETE_MESSAGE, MESSAGING_CONVERSATION_STARTED_7D, MESSAGING_DEEP_CONVERSATION, MESSAGING_AUTOMATED_FLOW_COMPLETE, MESSAGING_AUTOMATED_FLOW_CANCELLED, MESSENGER_RECEIPT_TEMPLATE, REFERRAL_SENDER_INVITES_SENT, REFERRAL_SENDER_MESSAGE_SENT, REFERRAL_RECEIVER_IMPRESSION, REFERRAL_RECEIVER_CLICK, VIDEO_HOME_SELECTED, VIDEO_HOME_WATCHLIST, VIDEO_HOME_EXPLORE, VIDEO_HOME_PLAYER_START, VIDEO_HOME_90_SECOND_VIEW, FUNDRAISER_CREATE, MESSENGER_CONNECTED_CALL, MESSENGER_MISSED_CALL, D2_RETENTION, D7_RETENTION, MOVIE_SHOWTIME_CLICK, LISTING_INTERACTION, PDP_VIEW, CLICK_TO_CALL, CLICK_TO_WEBSITE, POST_SHARE, OTHER}

pixel_id
Ads Pixel ID

pixel_rule
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_category
enum {NONE, EMPLOYMENT, HOUSING, CREDIT}

special_ad_category

Required
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

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.

topline_id
numeric string or integer

Topline ID

upstream_events
dictionary { string : <dictionary { string : <string> }> }

Upstream events

Return Type

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

Validation Rules

ErrorDescription
200Permissions error
100Invalid parameter
80004There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
294Managing advertisements requires an access token with the extended permission for ads_management
2625The request for a reach frequency campaign is invalid.

Updating

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

Parameters

ParameterDescription
adlabels
list<Object>

Ad Labels associated with this campaign

adset_bid_amounts
JSON object {adset ID : 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

bid_strategy
enum{LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, TARGET_COST}

Choose bid strategy for this campaign to suit your specific business goals. Each strategy has tradeoffs and may be available for certain optimization_goals:
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.
TARGET_COST: Maintains a stable average cost based on your optimization_goal as you raise your campaign budget. Select this strategy if you care most about maintaining stable average costs for your ads. However, note this strategy may be less cost-efficient than the lowest cost strategy. If you select this, you must provide a target cost in the bid_amount field for each ad set in this ad campaign. Target cost bid strategy is also known as manual average-cost bidding. Learn more in Ads Help Center, About bid strategies: Target cost.
Note: If you do not enable campaign budget optimization, you should set bid_strategy at ad set level.

budget_rebalance_flag
boolean

Whether to automatically rebalance budgets daily for all the adsets under this campaign.

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.

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, PAGE_LIKES, POST_ENGAGEMENT, PRODUCT_CATALOG_SALES, REACH, 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.

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

omnichannel_object
Object

app
list<Object>

application_id
App ID

custom_event_type
enum {JOB_ALERT_SUBSCRIBE, JOB_APPLICATION_CREATE, JOB_APPLICATION_FORM_IMPRESSION, JOB_BROWSER_IMPRESSION, JOB_OPENING_DETAIL_VIEW_IMPRESSION, ACTIVATE_APP, COMPLETE_REGISTRATION, CONTENT_VIEW, ONSITE_APP_CONTENT_VIEW, ONSITE_WEB_CONTENT_VIEW, ONSITE_WEB_APP_CONTENT_VIEW, SEARCH, RATE, TUTORIAL_COMPLETION, CONTACT, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, SCHEDULE, START_TRIAL, SUBMIT_APPLICATION, SUBSCRIBE, RECURRING_SUBSCRIPTION_PAYMENT, CANCEL_SUBSCRIPTION, VISIT_LOCATION, AD_CLICK, AD_IMPRESSION, ADD_TO_CART, ONSITE_APP_ADD_TO_CART, ONSITE_WEB_ADD_TO_CART, ONSITE_WEB_APP_ADD_TO_CART, ADD_TO_WISHLIST, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, PURCHASE, ONSITE_APP_PURCHASE, ONSITE_WEB_PURCHASE, ONSITE_WEB_APP_PURCHASE, MESSAGE_TO_BUY, LEAD, ONSITE_WEB_LEAD, LEVEL_ACHIEVED, ACHIEVEMENT_UNLOCKED, SPENT_CREDITS, FLOW_COMPLETE, SERVICE_BOOKING_REQUEST, MESSAGING_ACCEPT, MESSAGING_BLOCK, MESSAGING_DELETE_THREAD, MESSAGING_MARK_SPAM, MESSAGING_REPLY, MESSAGING_FIRST_REPLY, MESSAGING_OPEN_THREAD, MESSAGING_IGNORE_REQUEST, MESSAGING_PROMOTIONAL_OFF, MESSAGING_READ_RECEIPT, MESSAGING_DELIVERY_RECEIPT, MESSAGING_DELETE_MESSAGE, MESSAGING_CONVERSATION_STARTED_7D, MESSAGING_DEEP_CONVERSATION, MESSAGING_AUTOMATED_FLOW_COMPLETE, MESSAGING_AUTOMATED_FLOW_CANCELLED, MESSENGER_RECEIPT_TEMPLATE, REFERRAL_SENDER_INVITES_SENT, REFERRAL_SENDER_MESSAGE_SENT, REFERRAL_RECEIVER_IMPRESSION, REFERRAL_RECEIVER_CLICK, VIDEO_HOME_SELECTED, VIDEO_HOME_WATCHLIST, VIDEO_HOME_EXPLORE, VIDEO_HOME_PLAYER_START, VIDEO_HOME_90_SECOND_VIEW, FUNDRAISER_CREATE, MESSENGER_CONNECTED_CALL, MESSENGER_MISSED_CALL, D2_RETENTION, D7_RETENTION, MOVIE_SHOWTIME_CLICK, LISTING_INTERACTION, PDP_VIEW, CLICK_TO_CALL, CLICK_TO_WEBSITE, POST_SHARE, OTHER}

object_store_urls
list<string>

pixel
list<Object>

custom_event_type
enum {JOB_ALERT_SUBSCRIBE, JOB_APPLICATION_CREATE, JOB_APPLICATION_FORM_IMPRESSION, JOB_BROWSER_IMPRESSION, JOB_OPENING_DETAIL_VIEW_IMPRESSION, ACTIVATE_APP, COMPLETE_REGISTRATION, CONTENT_VIEW, ONSITE_APP_CONTENT_VIEW, ONSITE_WEB_CONTENT_VIEW, ONSITE_WEB_APP_CONTENT_VIEW, SEARCH, RATE, TUTORIAL_COMPLETION, CONTACT, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, SCHEDULE, START_TRIAL, SUBMIT_APPLICATION, SUBSCRIBE, RECURRING_SUBSCRIPTION_PAYMENT, CANCEL_SUBSCRIPTION, VISIT_LOCATION, AD_CLICK, AD_IMPRESSION, ADD_TO_CART, ONSITE_APP_ADD_TO_CART, ONSITE_WEB_ADD_TO_CART, ONSITE_WEB_APP_ADD_TO_CART, ADD_TO_WISHLIST, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, PURCHASE, ONSITE_APP_PURCHASE, ONSITE_WEB_PURCHASE, ONSITE_WEB_APP_PURCHASE, MESSAGE_TO_BUY, LEAD, ONSITE_WEB_LEAD, LEVEL_ACHIEVED, ACHIEVEMENT_UNLOCKED, SPENT_CREDITS, FLOW_COMPLETE, SERVICE_BOOKING_REQUEST, MESSAGING_ACCEPT, MESSAGING_BLOCK, MESSAGING_DELETE_THREAD, MESSAGING_MARK_SPAM, MESSAGING_REPLY, MESSAGING_FIRST_REPLY, MESSAGING_OPEN_THREAD, MESSAGING_IGNORE_REQUEST, MESSAGING_PROMOTIONAL_OFF, MESSAGING_READ_RECEIPT, MESSAGING_DELIVERY_RECEIPT, MESSAGING_DELETE_MESSAGE, MESSAGING_CONVERSATION_STARTED_7D, MESSAGING_DEEP_CONVERSATION, MESSAGING_AUTOMATED_FLOW_COMPLETE, MESSAGING_AUTOMATED_FLOW_CANCELLED, MESSENGER_RECEIPT_TEMPLATE, REFERRAL_SENDER_INVITES_SENT, REFERRAL_SENDER_MESSAGE_SENT, REFERRAL_RECEIVER_IMPRESSION, REFERRAL_RECEIVER_CLICK, VIDEO_HOME_SELECTED, VIDEO_HOME_WATCHLIST, VIDEO_HOME_EXPLORE, VIDEO_HOME_PLAYER_START, VIDEO_HOME_90_SECOND_VIEW, FUNDRAISER_CREATE, MESSENGER_CONNECTED_CALL, MESSENGER_MISSED_CALL, D2_RETENTION, D7_RETENTION, MOVIE_SHOWTIME_CLICK, LISTING_INTERACTION, PDP_VIEW, CLICK_TO_CALL, CLICK_TO_WEBSITE, POST_SHARE, OTHER}

pixel_id
Ads Pixel ID

pixel_rule
string

special_ad_category
enum {NONE, EMPLOYMENT, HOUSING, CREDIT}

special_ad_category

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

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.

upstream_events
dictionary { string : <dictionary { string : <string> }> }

Upstream events

Return Type

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

Validation Rules

ErrorDescription
200Permissions error
100Invalid parameter
80004There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
2625The request for a reach frequency campaign is invalid.
294Managing advertisements requires an access token with the extended permission for ads_management
801Invalid operation

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

Validation Rules

ErrorDescription
200Permissions error
100Invalid parameter
80004There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
You can dissociate a Campaign from an AdAccount by making a DELETE request to /act_{ad_account_id}/campaigns.

Parameters

ParameterDescription
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
],
}

Validation Rules

ErrorDescription
200Permissions error