Ad Campaign

Overview

With ad campaigns, you can now group ad sets together and retrieve unique statistics across multiple Facebook sets.

To get started, you should create a new ad campaign and assign ad sets to that ad campaign. Each ad campaign has an objective that must be valid across the ad sets within that campaign. By setting an objective you will ensure that your ad campaigns will be set up with valid ads in each campaign.

After your ads begin delivering, you can query stats for this ad campaign. The statistics returned will be unique stats, deduped across the sets.

This document describes campaigns per Facebook's new object model. If you are looking for ad sets (originally named campaigns) please see here. To take advantage of this new object model, enable the "New Campaign Structure" migration in your app's settings panel.

Create

To create an ad campaign, make an HTTP POST call to

 https://graph.facebook.com/act_{ad_account_id}/adcampaign_groups

with the following fields:

nametypedescriptionrequired

name

string

User-defined name of this campaign

yes

objective

string

Objective of this ad campaign. If it is specified the API will validate that any ad groups created under the campaign match that objective. Allowed values are:
NONE (default)
OFFER_CLAIMS
PAGE_LIKES
CANVAS_APP_INSTALLS
CANVAS_APP_ENGAGEMENT
EVENT_RESPONSES
POST_ENGAGEMENT
WEBSITE_CONVERSIONS
MOBILE_APP_INSTALLS
MOBILE_APP_ENGAGEMENT
WEBSITE_CLICKS

no

campaign_group_status

string

Possible values are ACTIVE (default) or PAUSED. If the campaign_group_status field is set to PAUSED, any active ad sets and ads will be paused. Any previously active ad sets will have a campaign_status of 10 and any previously active ads will have an adgroup_status of CAMPAIGN_GROUP_PAUSED.

yes

buying_type

string

If you specify a buying_type, all ad sets in this campaign must match the buying type.
Possible values are:
AUCTION (default)
FIXED_CPM

no

Response

A JSON array of the following:

namedescription

id

Facebook ID of the ad campaign created

Then, to add sets to the campaign, refer to the ad set creation documentation.

The redownload flag to retrieve details about the adcampaign group upon creation is not supported.

Read

By ad campaign

July 2nd Breaking Change Notice: the output types of id and account_id will be string

To read the details of an ad campaign, make an HTTP GET request to

 https://graph.facebook.com/{ad_campaign_group_id}

And specify the fields you wish to retrieve. Only id is returned by default. The fields are:

namedescription

id

Facebook ID of the ad campaign

account_id

Account ID of the ad account that owns this ad campaign

objective

Ad campaign objective

name

Name of the ad campaign

campaign_group_status

Possible values are ACTIVE, PAUSED, DELETED. If the campaign_group_status field is set to PAUSED, any active ad sets and ads will be paused. Any previously active ad sets will have a campaign_status of 10 and any previously active ads will have an adgroup_status of CAMPAIGN_GROUP_PAUSED.

buying_type

Possible values are:
AUCTION (default)
FIXED_CPM
MIXED (some legacy campaigns may have this buying type)

Please see Cursor-based pagination for paging through response.

By ad account

You can also read all campaigns of an ad account by making an HTTP GET request to

 https://graph.facebook.com/act_(ad_account_id)/adcampaign_groups

July 2nd Breaking Change Notice: the count, offset, and limit fields will be deprecated and you will need to use cursor-based paging.

and specify the fields you wish to retrieve, as defined above. Only id is returned by default. You can also filter which ad campaigns you want in the response by specifying the below as URL params with their associated value:

nametypedescription

campaign_group_status

array of strings

Possible values are ACTIVE, PAUSED, DELETED. Default is ['ACTIVE','PAUSED']. If the campaign_group_status field is set to PAUSED, any active ad sets and ads will be paused. Any previously active ad sets will have a campaign_status of 10 and any previously active ads will have an adgroup_status of CAMPAIGN_GROUP_PAUSED.

is_completed

boolean

An ad campaign is completed (true) if all active or paused ad sets associated with it have reached their end time. For ad sets with a daily spend limit and no end time, this will always return false. By default will return all results.

The response will be an array of JSON objects containing the ad campaign ids and any other fields as defined in the query.

Update

You can update certain fields of the ad campaign by making an HTTP POST call to

 https://graph.facebook.com/{ad_campaign_group_id}

with the following optional fields:

nametypedescription

name

string

New name of the campaign. Cannot be an empty string

objective

string

Update from NONE to a valid objective, or from a valid objective back to NONE

campaign_group_status

string

Possible values are ACTIVE, PAUSED. If the campaign_group_status field is set to PAUSED, any active ad sets and ads will be paused. Any previously active ad sets will have a campaign_status of 10 and any previously active ads will have an adgroup_status of CAMPAIGN_GROUP_PAUSED.

Response

When an objective other than NONE is specified, the API will validate that all ad groups in the campaign match the specified objective. The response will be true if the update call was successful and validation passes. The response will be false if the objective validation fails, in which case all other fields specified will not be updated.

Delete

To delete an ad campaign, make an HTTP DELETE call to

 https://graph.facebook.com/{ad_campaign_group_id}

The response will be true if successful.

Note that this will delete all ad sets and ad groups that are connected to this ad campaign.

Query Statistics

To request statistics by campaign ID, submit an HTTP GET request to

 https://graph.facebook.com/{ad_campaign_group_id}/stats

And specify the statistics you wish to retrieve, defined here.

Optionally you can filter by the following fields:

nametypedescription

start_time

UNIX timestamp format or parseable date

Specify the start date when filtering by a time range

end_time

UNIX timestamp format or parseable date

Specify the end date when filtering by a time range

Response

A JSON array keyed off of a data element of the fields specified in the GET call. For example:

{"data":[{"impressions":0,"clicks":0,"spent":0}]}

Note that the following endpoints are not supported for ad campaigns

  • /act_{ad_account_id}/adcampaigngroupstats
  • /{ad_campaign_group_id}/conversionstats

Connections

An ad campaign object has connections to other information. To query an ad campaign's connections, make an HTTP GET call to

 https://graph.facebook.com/{ad_campaign_group_id}/{connection_name}

July 2nd Breaking Change Notice: the count, offset, and limit fields will be deprecated and you will need to use cursor-based paging for the connections below.

The list below details which connections are available:

NameDescription

adcampaigns

The ad sets that participate in this campaign. This endpoint maintains a legacy naming convention.

adgroups

The ad groups that participate in this campaign.

stats

The statistics for the ad campaign

Limits

The following are the limits on ad campaigns

  • How many campaigns can a regular ad account have? : 1,000 non-deleted campaigns
  • How many campaigns can a bulk ad account have? : 10,000 non-deleted campaigns
  • How many sets can a campaign have? 10,000 non-deleted sets

Examples

Create an ad campaign

curl \
-F "name=my campaign group" \
-F "campaign_group_status=PAUSED" \
-F "objective=NONE" \
-F "access_token=___" \
"https://graph.facebook.com/act_123456/adcampaign_groups"

Read the name, objective, and id fields of the ad campaign

curl -G \
-d "fields=name,objective" \
-d "access_token=___" \
"https://graph.facebook.com/6013254986348"

// Response
{"name":"my campaign group","objective":"NONE","id":"6013254986348"}

Filter to get all ad campaigns with paused status

curl -G \
-d "fields=name,objective" \
-d "campaign_group_status=['PAUSED']" \
-d "access_token=___" \
"https://graph.facebook.com/act_123456/adcampaign_groups"

Update the name of the ad campaign

curl \
-F "name=my new campaign name" \
-F "access_token=___" \
"https://graph.facebook.com/6013254986348"

Query by ad campaign and set a minimum start time in parseable date format

curl -G \
-d "start_time=2013-03-01" \
-d "fields=impressions,clicks,spent" \
-d "access_token=___" \
"https://graph.facebook.com/6013254986348/stats"

Query by ad campaign and set a minimum end time in UNIX time

curl -G \
-d "end_time=1367823600" \
-d "fields=impressions,clicks,spent" \
-d "access_token=___" \
"https://graph.facebook.com/6013254986348/stats"

Delete the ad campaign

curl -XDELETE \
-F "access_token=___" \
"https://graph.facebook.com/6013254986348"
Was this document helpful?