Graph API Reference: Ad Account campaigns - Documentation

Marketing API Version

Ad Account Campaigns

Reading

The ad campaigns of this ad account

GET /v2.10/{ad-account-id}/campaigns HTTP/1.1
Host: graph.facebook.com

/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/{ad-account-id}/campaigns'
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */

/* make the API call */
FB.api(
    "/{ad-account-id}/campaigns",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{ad-account-id}/campaigns",
    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:@"/{ad-account-id}/campaigns"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps

ads_management
ads_read

Page management Apps

No data

Other Apps

No data

Parameters

Name	Description
`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
`time_range` {'since':YYYY-MM-DD,'until':YYYY-MM-DD}	Date range used to aggregate insights metrics
`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

Reading from this edge will return a JSON formatted result:

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

`data`

A list of Campaign 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).

Field Description

Field	Description
`insights`	Analytics summary for all objects
`total_count` unsigned int32	Total number of objects Default

insights

Analytics summary for all objects

total_count

unsigned int32

Total number of objects

Default

Validation Rules

Error	Description
100	Invalid parameter
200	Permissions error
274	The 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
273	This Ads API call requires the user to be admin of the ad account
272	This Ads API call requires the user to be admin of the application
278	Reading advertisements requires an access token with the extended permission ads_read

Creating

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.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps

ads_management

Page management Apps

No data

Other Apps

Permissions are not usually requested.

Parameters

Name	Description
`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.
`name` string	Name for this campaign
`objective` enum{APP_INSTALLS, BRAND_AWARENESS, CONVERSIONS, EVENT_RESPONSES, LEAD_GENERATION, LINK_CLICKS, LOCAL_AWARENESS, 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{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` 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

Error	Description
100	Invalid parameter
274	The 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
200	Permissions error
2615	Invalid call to update this adaccount
294	Managing advertisements requires an access token with the extended permission for ads_management
272	This Ads API call requires the user to be admin of the application
273	This Ads API call requires the user to be admin of the ad account

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

Name	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	Default value: `200` Object count

Return Type

Struct {

objects_left_to_delete_count: unsigned int32,

deleted_object_ids: List [

numeric string

}

Validation Rules

Error	Description
100	Invalid parameter
273	This Ads API call requires the user to be admin of the ad account