Marketing API Version

Campaign

Limits

The following are the limits on ad campaigns

LimitValue

Maximum number of ad campaigns per regular ad account

5000 non deleted ad campaigns

Maximum number of ad campaigns per bulk ad account

10000 non deleted ad campaigns

Maximum number of ad sets per ad campaign

10000 non deleted ad sets

Maximum length of an ad campaign name

400 characters

Maximum number of archived ad campaigns per ad account

50k archived ad campaigns

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

Parameters

This endpoint doesn't have any parameters.

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

buying_type

string

Buying type, possible values are:
AUCTION: default
RESERVED: for reach and frequency ads

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

effective_status

enum {ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ARCHIVED, ADSET_PAUSED}

The effective status of this campaign. For example, when all Ad Sets beneath the campaign are paused, the effective status is ADSET_PAUSED.

name

string

Campaign's name

objective

string

Campaign's objective

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

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

updated_time

datetime

Updated Time

Edges

EdgeDescription

ads

Ads under this campaign

adsets

The ad sets under this campaign

insights

Insights on advertising performance of this campaign

stats

Reference document for using Facebook Marketing APIs to get ad statistics on impressions, clicks, performance, and more

Validation Rules

ErrorDescription
100Invalid parameter
278Reading advertisements requires an access token with the extended permission ads_read
274The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.
273This Ads API call requires the user to be admin of the ad account
272This Ads API call requires the user to be admin of the application

Creating

The redownload parameter which exists when creating ad sets and ads is not supported on this endpoint.

Examples

Create a campaign

use FacebookAds\Object\Campaign;
use FacebookAds\Object\Fields\CampaignFields;

$campaign = new Campaign(null, 'act_<AD_ACCOUNT_ID>');

$campaign->setData(array(
  CampaignFields::NAME => 'My First Campaign',
  CampaignFields::OBJECTIVE => '<OBJECTIVE>',
));

$campaign->create(array(
  Campaign::STATUS_PARAM_NAME => Campaign::STATUS_PAUSED,
));
from facebookads.adobjects.campaign import Campaign

campaign = Campaign(parent_id='act_<AD_ACCOUNT_ID>')
campaign.update({
    Campaign.Field.name: 'My First Campaign',
    Campaign.Field.objective: '<OBJECTIVE>',
})

campaign.remote_create(params={
    'status': Campaign.Status.paused,
})
print(campaign)
Campaign campaign = new AdAccount(act_<AD_ACCOUNT_ID>, context).createCampaign()
  .setName("My First Campaign")
  .setObjective(<OBJECTIVE>)
  .setStatus(Campaign.EnumStatus.VALUE_PAUSED)
  .execute();
String campaign_id = campaign.getId();
curl \
  -F 'name=My First Campaign' \
  -F 'objective=<OBJECTIVE>' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/act_<AD_ACCOUNT_ID>/campaigns
You can make a POST request to campaigns edge from the following paths:
When posting to this edge, a Campaign will be created.

Parameters

NameDescription
adlabels
list<Object>

Ad Labels associated with 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).

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.

name
string

Name for this campaign

objective
enum{BRAND_AWARENESS, CANVAS_APP_ENGAGEMENT, CANVAS_APP_INSTALLS, CONVERSIONS, EVENT_RESPONSES, EXTERNAL, LEAD_GENERATION, LINK_CLICKS, LOCAL_AWARENESS, MOBILE_APP_ENGAGEMENT, MOBILE_APP_INSTALLS, 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 ad groups created under the campaign match that objective.
Currently, BRAND_AWARENESS can only be used on ad accounts with CAN_CREATE_BRAND_AWARENESS_OBJECTIVE_ADS capability. With that objective, all creatives used should use 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 campaign group 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{COMPLETE_REGISTRATION, CONTENT_VIEW, SEARCH, RATE, TUTORIAL_COMPLETION, ADD_TO_CART, ADD_TO_WISHLIST, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, PURCHASE, LEAD, LEVEL_ACHIEVED, ACHIEVEMENT_UNLOCKED, SPENT_CREDITS, OTHER}

The event from an App Event of a mobile app, or tag of an conversion pixel.

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
int

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_set_id
numeric string or integer

The ID of a Product Set within a Campaign Group level Product Catalog. Used with Dynamic Product Ads.

event_id
numeric string or integer

The ID of a Facebook Event

spend_cap
unsigned int32

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). Leave blank for unlimited spend. Not available for Reach and Frequency or Premium Self Serve campaigns

status
enum{ACTIVE, PAUSED, ARCHIVED, DELETED}

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.

Return Type

Struct {
id: numeric string,
success: bool,
}
You may perform a POST request to the following edge from this node:

Validation Rules

ErrorDescription
100Invalid parameter
274The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API
2625The request for a reach frequency campaign is invalid.
273This Ads API call requires the user to be admin of the ad account
272This Ads API call requires the user to be admin of the application
294Managing advertisements requires an access token with the extended permission for ads_management
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.

Updating

Examples

Update the name of the ad campaign

use FacebookAds\Object\Campaign;
use FacebookAds\Object\Fields\CampaignFields;

$campaign = new Campaign(<CAMPAIGN_ID>);
$campaign->{CampaignFields::NAME} = 'My new campaign name';
$campaign->update();
from facebookads.adobjects.campaign import Campaign

campaign = Campaign(<CAMPAIGN_ID>)

campaign[Campaign.Field.name] = 'New Name'
campaign.remote_update()
new Campaign(<CAMPAIGN_ID>, context).update()
  .setName("My new campaign name")
  .execute();
curl \
  -F 'name=My new campaign name' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/<CAMPAIGN_ID>
You can update a Campaign by making a POST request to /{campaign_id}.

Parameters

NameDescription
adlabels
list<Object>

Ad Labels associated with this campaign

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.

name
string

Name for this campaign

objective
enum{BRAND_AWARENESS, CANVAS_APP_ENGAGEMENT, CANVAS_APP_INSTALLS, CONVERSIONS, EVENT_RESPONSES, EXTERNAL, LEAD_GENERATION, LINK_CLICKS, LOCAL_AWARENESS, MOBILE_APP_ENGAGEMENT, MOBILE_APP_INSTALLS, 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 ad groups created under the campaign match that objective.
Currently, BRAND_AWARENESS can only be used on ad accounts with CAN_CREATE_BRAND_AWARENESS_OBJECTIVE_ADS capability. With that objective, all creatives used should use 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 campaign group 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{COMPLETE_REGISTRATION, CONTENT_VIEW, SEARCH, RATE, TUTORIAL_COMPLETION, ADD_TO_CART, ADD_TO_WISHLIST, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, PURCHASE, LEAD, LEVEL_ACHIEVED, ACHIEVEMENT_UNLOCKED, SPENT_CREDITS, OTHER}

The event from an App Event of a mobile app, or tag of an conversion pixel.

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
int

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_set_id
numeric string or integer

The ID of a Product Set within a Campaign Group level Product Catalog. Used with Dynamic Product Ads.

event_id
numeric string or integer

The ID of a Facebook Event

spend_cap
unsigned int32

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). Leave blank for unlimited spend. Not available for Reach and Frequency or Premium Self Serve campaigns

status
enum{ACTIVE, PAUSED, ARCHIVED, DELETED}

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.

Return Type

Struct {
success: bool,
}
You may perform a POST request to the following edge from this node:

Validation Rules

ErrorDescription
100Invalid parameter
274The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API
2625The request for a reach frequency campaign is invalid.
273This Ads API call requires the user to be admin of the ad account
272This Ads API call requires the user to be admin of the application
294Managing advertisements requires an access token with the extended permission for ads_management
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.

Deleting

Examples

Delete the ad campaign

use FacebookAds\Object\Campaign;

$campaign = new Campaign(<CAMPAIGN_ID>);
$campaign->delete();
from facebookads.adobjects.campaign import Campaign

campaign = Campaign(<CAMPAIGN_ID>)
campaign.remote_delete()
new Campaign(<CAMPAIGN_ID>, context).update()
  .setStatus(Campaign.EnumStatus.VALUE_DELETED)
  .execute();
curl \
  -F 'status=DELETED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/<CAMPAIGN_ID>
You can dissociate a Campaign from an AdAccount by making a DELETE request to /act_{ad_account_id}/campaigns.

Parameters

NameDescription
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
Default value: 1000

Object count

Return Type

Struct {
objects_left_to_delete_count: unsigned int32,
deleted_object_ids: List [
numeric string
],
}
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,
}
You may perform a DELETE request to the following edge from this node:

Validation Rules

ErrorDescription
100Invalid parameter
274The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API