Marketing API Version

Ad Account, Ad Campaigns

The ad campaigns associated with a given ad account.

On May 1, 2018 with the release of Marketing API 3.0 we will remove kpi_custom_conversion_id, kpi_type, and kpi_results.

Reading

The ad campaigns of this ad account

Example

Graph API Explorer
GET /v3.0/act_<AD_ACCOUNT_ID>/campaigns?effective_status=%5B%22ACTIVE%22%2C%22PAUSED%22%5D&fields=name%2Cobjective HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/act_<AD_ACCOUNT_ID>/campaigns',
    '{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",
    {
        "effective_status": "[\"ACTIVE\",\"PAUSED\"]",
        "fields": "name,objective"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("effective_status", "[\"ACTIVE\",\"PAUSED\"]");
params.putString("fields", "name,objective");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/act_<AD_ACCOUNT_ID>/campaigns",
    params,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"effective_status": @"[\"ACTIVE\",\"PAUSED\"]",
  @"fields": @"name,objective",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/act_<AD_ACCOUNT_ID>/campaigns"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
curl https://graph.facebook.com/v3.0/act_<AD_ACCOUNT_ID>/campaigns?effective_status=%5B%22ACTIVE%22%2C%22PAUSED%22%5D&fields=name%2Cobjective
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

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

Predefine date range used to aggregate insights metrics

effective_status
list<enum{ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ARCHIVED, ADSET_PAUSED}>
Default value: Array

effective status for the campaigns

is_completed
boolean

is completed

Fields

Reading from this edge will return a JSON formatted result:

{ "data": [], "paging": {}, "summary": {} }

data

A list of AdCampaignGroup nodes.

paging

For more details about pagination, see the Graph API guide.

summary

Aggregated information about the edge, such as counts. Specify the fields to fetch in the summary param (like summary=insights).

FieldDescription
insights

Analytics summary for all objects

total_count
unsigned int32

Total number of objects

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
2635You are calling a deprecated version of the Ads API. Please update to the latest version.
273This Ads API call requires the user to be admin of the ad account
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
272This Ads API call requires the user to be admin of the application
278Reading advertisements requires an access token with the extended permission ads_read
270This Ads API request is not allowed for apps with development access level (Development access is by default for all apps, please request for upgrade). Make sure that the access token belongs to a user that is both admin of the app and admin of the ad account
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.

Creating

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

Parameters

NameDescription
adlabels
list<Object>

Ad Labels associated with this campaign

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

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 .

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.

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, ADD_TO_CART, ADD_TO_WISHLIST, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, PURCHASE, LEAD, COMPLETE_REGISTRATION, CONTENT_VIEW, SEARCH, MESSAGING_CONVERSATION_STARTED_7D, 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
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_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.

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.

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
100Invalid parameter
200Permissions error
294Managing advertisements requires an access token with the extended permission for ads_management
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
2615Invalid call to update this adaccount
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
2625The request for a reach frequency campaign is invalid.
2633This shared login is disabled. Go to Ads Manager for more information.

Updating

You can't perform this operation on this endpoint.

Deleting

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: 200

Object count

Return Type

Struct {
objects_left_to_delete_count: unsigned int32,
deleted_object_ids: List [
numeric string
],
}

Validation Rules

ErrorDescription
100Invalid parameter