Ad group

An ad on Facebook, as represented in the Graph API. Before using this object please review the Ads on the Graph API documentation.

Topics

Fields
Connections
Limits
Retrieving AdGroups
Creating AdGroups
Estimating Reach
View Tags

Fields

Also see the adCreative object and Targeting Specs.

Name	Description	Permissions	Returns
`ad_id`	ID of the ad group, required for updating ad groups	`ads_management`	`long`
`campaign_id`	ID of the campaign, required for creating ad groups	`ads_management`	`long`
`name`	The name of the ad group, up to 100 characters in length, required for creating ad groups and can be updated	`ads_management`	`string`
`adgroup_status`	1 indicates ACTIVE, 3 indicates DELETED, 4 indicates PENDING_REVIEW, 5 indicates DISAPPROVED, 8 indicates CAMPAIGN_PAUSED (resuming the Campaign resumes the ad group), 7 indicates PENDING_BILLING_INFO and 9 indicates ADGROUP_PAUSED, and if the status is ADGROUP_PAUSED the ad group stays in that state regardless of the campaign being PAUSED or ACTIVE because you would have to resume that ad group specifically	`ads_management`	`int`
`bid_type`	Use 1 for CPC, 2 for CPM, 6 or 7 for Goal-base Optimization, and 9 for Cost Per Action ; required when creating ad groups;	`ads_management`	`int`
`max_bid`	The highest bid, defined in cents; required when creating ad groups; can be updated	`ads_management`	`string`
`conversion_specs`	The ad's conversion specification, see Conversion Specs	`ads_management`	`array`
`tracking_specs`	The ad's tracking specification, see Conversion Specs	`ads_management`	`array`
`targeting`	The ad's targeting specification, see Targeting Specs	`ads_management`	`array`
`creative`	The ad's creative elements, see `adCreative`	`ads_management`	`array`
`adgroup_id`	The ID of the ad group	`ads_management`	`long`
`updated_time`	A unix timestamp for when the ad was updated	`ads_management`	`int`
`bid_info`	The ad's bid information	`ads_management`	`array`
`disapprove_reason_descriptions`	Reason ad was not approved	`ads_management`	`array`
`view_tags`	Multiple view tags can be displayed with the ad. These tags must be supported on http and https. Only tags from approved partners are supported, please check with your Partner Manager or Facebook representative for a list of approved view tag partners.	`ads_management`	`array` of `string`
`tracking_pixel_ids`	The list of offsite pixel's ids which you want to track	`ads_management`	`array`

Connections

The adgroup object has the following connections.

Name	Description	Permissions	Returns
stats	The statistics for the adgroup	`ads_management`	`adstatistics`
reachestimate	The Reach Estimate for the adgroup	`ads_management`	`reachestimate`
keywordstats	The keyword stats for the adgroup	`ads_management`	`keywordstats`
adcreatives	The creative for the adgroup	`ads_management`	`adcreative`
targetingsentencelines	Human-readable description of the targeting for the adgroup	`ads_management`	`targetingsentencelines`
previews	Generates a Preview of an Ad group	`ads_management`	`Ad Preview` HTML snippet

Limits

The following are the limits on ad groups

How many times can an ad be edited? : 200

Using adgroup objects

An ad group contains the data necessary for an ad. Each ad group has its own bids and targeting data. You can retrieve ad-related statistics for an ad group.

Each ad group is associated with a campaign. All ad groups in a campaign have the same daily or lifetime budget and schedule.

For the creative elements of an ad group, you specify a creative array. Within the array, you can specify a new creative or the ID of an existing adCreative object. For information about the adCreative parameters, see the adCreative object.

For the targeting elements of an ad group, you specify a Targeting Specs. For more details on AdGroup targeting please see the Targeting Specs documentation.

Also see the following:

Updating and deleting ad groups
Estimating reach
Retrieving stats for an ad group

Retrieving ad groups

You can retrieve the data for all the ad groups in an account. Specify the account number as act_AccountNumber. Then use the adGroup object as a connection to act_AccountNumber. For example:

 https://graph.facebook.com/act_368811234/adgroups?access_token=____

Note: At most 1000 adgroups can be retrieved in a single call. Any adgroups in excess of this must be paged through.

To retrieve the data for a specific ad group use the adgroup ID, for example:

 https://graph.facebook.com/6003299131234?access_token=____

To retrieve the basic data for multiple ad groups, specify their IDs, for example:

 https://graph.facebook.com?ids=6003299131234,6003266531234&access_token=___

To retrieve all of the adgroups within a campaign specify the adGroup object as a connection to the campaign object, for example:

 https://graph.facebook.com/{campaign-id}/adgroups?access_token=____

To retrieve the adgroups within multiple campaigns, specify the campaign IDs, for example:

 https://graph.facebook.com/act_368811234/adgroups?campaign_ids=[11234345565,5436363546456,34563456345]&access_token=____

When retrieving adgroups from a account level or a campaign level you can filter deleted adgroups by using the include_deleted parameter

 https://graph.facebook.com/act_368811234/adgroups?include_deleted=true&access_token=____

If the include_deleted parameter is not supplied the default "false" is used. If you use the include_deleted parameter while specifying specific adgroups IDs the include_deleted parameter will be ignored and all of the requested adgroups will be returned.

Creating an ad group

Ad groups include the following elements:

Campaign under which the ad is placed
Bid type and maximum bid
Targeting elements, such as the location, maximum age, and interests of the audience defined in a Targeting Spec
Creative elements as defined in an ad creative

Before submitting the data for an ad, decide on the ad design, the pricing, the campaign, and the target audience. See Create an ad and set a budget.

Your campaign pricing can be Cost Per Click (CPC) or Cost Per Thousand Impressions (CPM). See Create an ad and set a budget.

The following example creates a new ad group using a targeting element and a creative array. Note that instead of using the following values in the creative array, you can specify the ID an existing creative.

If you specify the following:

curl -F "campaign_id=6003417011234" -F "bid_type=1"
-F "max_bid=30" -F "targeting={'countries':['US']}"
-F "creative={'type':25,'action_spec':{'action.type':'like', 'post':10150420410887685}}"
-F "name=test"
"https://graph.facebook.com/act_368811234/adgroups?access_token=____"

The result will be similar to the following:

{"id":6003493971234}

For a non-social ad, you could specify the following:

curl -F "campaign_id=6003417011234" -F "bid_type=1" -F "max_bid=30"
-F "targeting={'countries':['US']}" -F
"creative={'title':'test','body':'test','link_url':'http:\/\/www.test.com',
'image_file':'test.jpg'}" -F "name=test"
-F "test.jpg=@.\test.jpg"
"https://graph.facebook.com/act_368811234/adgroups?access_token=____"

The result will be similar to the following:

{"id":6003485421234}

When you create a new ad group, you can specify the ID of a creative (if the creative is in the ad account's creative library) instead of specifying data for a new creative. The ID of the creative is specified in the creative_id parameter as follows:

curl -F "campaign_id=6003417011234" -F "bid_type=1" -F "max_bid=30"
-F "name=Adgroup name"
-F "targeting={'countries':['US']}" -F
"creative={'creative_id':12341234}"
"https://graph.facebook.com/act_368811234/adgroups?access_token=____"

See adCreative for the ad types and other information for new creatives and for using images.

Note: Ad groups are in pending state after creation until they are approved (or rejected). Once an ad group is approved, it will be in running state. If you would like an ad group not running after approval, you can create the ad group in a paused campaign, and then resume the campaign when you are ready to run the ad group.

Redownloading adgroups after creation

You can request the newly created adgroup to be returned to you after creation. For example, you could specify a request similar to the following to create an adgroup and have it returned:

If you specify the following:

curl -F "campaign_id=6003417011234" -F "bid_type=1"
-F "max_bid=30" -F "targeting={'countries':['US']}"
-F "creative={'type':25,'action_spec':{'action.type':'like', 'post':10150420410887685}}"
-F "name=test"
-F "redownload=1"
"https://graph.facebook.com/act_368811234/adgroups?access_token=____"

The result would be similar to the following:

{"id":"6004196911039","data":{"adgroups":{"6004196911039":{"adgroup_id":6004196911039,"ad_id":6004196911039,"campaign_id":6003417011234,"name":"test","ad_status":4,"adgroup_status":4,"bid_type":1,"max_bid":"30","bid_info":{"1":"30"},"account_id":368811234,"id":"6004196911039","creative_ids":[6004196615439],"targeting":{"countries":["US"],"friends_of_connections":[{"id":"6004008089439","name":null}]},"start_time":null,"end_time":null,"updated_time":1328021899}},"creatives":{"6004196615439":{"type":25,"action_spec":"{'action.type':'like', 'post':10150420410887685}","related_fan_page":1,"cluster_id":6004008089439,"name":"Sponsored story #6004196615439","run_status":1,"preview_url":"http:\/\/www.facebook.com\/ads\/api\/creative_preview.php?cid=6004196615439","count_current_adgroups":2,"id":"6004196615439","creative_id":"6004196615439"}}}}

Retrieving object IDs

As described at adCreative, if you specify an ad type other than 1, you need to include the relevant Facebook object ID (in the object_id field). You can obtain a list of object IDs using the Graph API with /act_{account-id}/connectionobjects, which returns the objects for the session user. For most ad types, the page or event's profile image is used.

Updating and deleting ad groups

Using the ad group ID, you can update the following fields in an ad group:

name
max_bid
bid_info
adgroup_status
bid_type
targeting
creative

For example, you could specify a request similar to the following to update the ad group with the ID of 6003493971234:

curl  -F "name=newname"
"https://graph.facebook.com/6003493971234?access_token=___"

To delete an ad group, specify a request similar to the following:

 curl  -XDELETE "https://graph.facebook.com/6003417011234?access_token=___"

Redownloading adgroups after updating

You can request the newly updated adgroup to be returned to you after you update it. For example, you could specify a request similar to the following to update an adgroup and have it returned:

If you specify the following:

curl  -F "name=newname"
-F "redownload=1"
"https://graph.facebook.com/6003826035839?access_token=___"

The result will be similar to the following:

{"result":true,"data":{"adgroups":{"6003826035839":{"adgroup_id":6003826035839,"ad_id":6003826035839,"campaign_id":6003417011234,"name":"newname","ad_status":4,"adgroup_status":4,"bid_type":1,"max_bid":"30","bid_info":{"1":"30"},"account_id":19643108,"id":"6003826035839","creative_ids":[6003143516439],"targeting":{"countries":["US"],"friends_of_connections":[{"id":"125772667501234","name":"Awesome web site"}]},"start_time":null,"end_time":null,"updated_time":1319726641}},"creatives":{"6003143516439":{"view_tag":"","alt_view_tags":[],"creative_id":6003143516439,"type":9,"object_id":125772667501234,"url_tags":"","name":"Like Story #6003143516439","run_status":1,"preview_url":"http:\/\/www.facebook.com\/ads\/api\/creative_preview.php?cid=6003143516439","count_current_adgroups":2,"id":"6003143516439"}}}}

Estimating the reach of a set of targeting values

To get the estimated reach of a set of targeting values, submit the targeting values via query string parameter to /act_{account-id}/reachestimate?currency=USD&targeting_spec=. The format is the same as it would be for the targeting array used when creating an ad group.

Note that currency and targeting_spec are required for accessing /act_{account-id}/reachestimate. The returned CPC and CPM values are based on the currency specified. For the list of supported currencies, and the ISO values you can use, see the accepted currencies. targeting_spec should include a country code at least.

Retrieving ad group targeting and estimating ad group reach

You can use /{adgroup-id} to get the targeting values for an ad group.

You can use /{adgroup-id}/reachestimate to estimate the reach of an ad group.

Retrieving stats for an ad group

Statistics for an adGroup object are retrieved in the same way as for an adCampaign object.

For statistics about one or more ad groups, use /{adgroup-id}/stats.

For more details on ad stats please see the Ad Statistics documentation.

Retrieving keyword stats for an ad group

You can retrieve an ad group's keyword stats of the past 7 days (excluding the current day). The ID specified must be for an ad group active in the past 7 days. Additionally, the ad group must use keyword targeting.

For example, if you specify a request similar to the following:

 https://graph.facebook.com/6002311051234/keywordstats?access_token=____

The result will be similar to the following:

 {
    "data": {
       "#Tennis": {
       "impressions": 156529,
       "clicks": 556,
       "unique_impressions": 44483,
       "unique_clicks": 542
       },
       "#Coffee": {
       "impressions": 3265,
       "clicks": 19,
       "unique_impressions": 777,
       "unique_clicks": 19
       }  
     }
 }

View Tags

View Tags are supported for Standard Domain Ads (type 1) and Homepage Ads in Self Serve, an additional field view_tags can now be added to the AdGroups. Following are example calls:

Creating a new AdGroup with a view tag:

 curl -F 'name=AdGroupName'\
      -F 'bid_type=1'\
      -F 'max_bid=100'\
      -F 'targeting={"countries":["US"]}'\ 
      -F 'campaign_id=<CampaignID>'\
      -F 'creative={"creative_id": <CreativeID>}'\
      -F 'locations=[3]'\ 
      -F 'view_tags=http://ad.viewtagdomain.net/view_tag1'\
  'https://graph.facebook.com/act_ACCOUNTID/adgroups/?access_token=token'

Setting / Updating a view tag on an existing AdGroup

 curl -F 'view_tags=http://ad.viewtagdomain.net/view_tag2'\
  'https://graph.facebook.com/ADGROUP_ID?access_token=token'

Removing a view tag from an AdGroup (use an empty string):

 curl -F 'view_tags=""'\
   'https://graph.facebook.com/ADGROUP_ID?access_token=token'

Adding multiple view tags can be done during creation or updating of adgroups with:

      –F 'view_tags=["http://ad.viewtagdomain.net/view_tag1", "http://ad.viewtagdomain.net/view_tag2"]'\

Requirements

View tags must align with our requirements below:

Our servers are able to establish a connection with the tag server.
The final destination URL of the tag is a 1x1 pixel.
The final destination URL of the tag contains a valid SSL/TLS certificate.
The tag does not drop more than one cookie.
The size of the cookie is less than 1024 characters (1 kb).
Our servers receive a response from the tag server in less than one second.
The tag does not redirect, except as necessary to pull down the 1x1 image and then only from the same domain as the tag.

Updated about 2 weeks ago

Best Practices

Reference

Specs

Advanced Targeting

Queries

Objects

Ad group

Topics

Fields

Connections

Limits

Using adgroup objects

Retrieving ad groups

Creating an ad group

Redownloading adgroups after creation

Retrieving object IDs

Updating and deleting ad groups

Redownloading adgroups after updating

Estimating the reach of a set of targeting values

Retrieving ad group targeting and estimating ad group reach

Retrieving stats for an ad group

Retrieving keyword stats for an ad group

View Tags

Requirements