Ad campaign

A campaign for managing ads, represented in the Graph API.

Before using this object, see Ads on the Graph API.

See below for information about how to use this object.

The adcampaign object has the following connection:

adgroup

The adcampaign object is a connection of the following object:

adaccount

To read an adcampaign object you need ads_management permission

Example

Retrieve the information for a campaign with a call to:

https://graph.facebook.com/[CAMPAIGN_ID]?access_token=___

To retrieve information for multiple campaigns use the ids parameter as follows:

https://graph.facebook.com?ids=60036768798069,60047687098847,6004657687980&access_token=___

Fields

Name	Description	Permissions	Type
`id`	The campaign ID	`ads_management`	`long`
`account_id`	The ad account which contains this campaign	`ads_management`	`long`
`name`	Campaign name of 100 characters or less; required to create a new campaign	`ads_management`	`string`
`start_time`	A unix timestamp; optional when creating and updating campaigns	`ads_management`	`int`
`end_time`	A unix timestamp; optional when creating and updating campaigns. When retrieving campaigns, this field is ommitted if the campaign has no end date. When creating a campaign with a daily budget, specify `end_time=0` to set the campaign to be "ongoing" and have no end date	`ads_management`	`int`
`daily_budget`	Defined in cents, minimum 100; daily or lifetime budget must be set when creating a a campaign; can be updated	`ads_management`	`int`
`campaign_status`	A campaign status is active (status 1), paused (status 2), or deleted (status 3). Note when a campaign reaches its end date the status remains as 1. A completed campaign can be restarted by editing the end_time to be a time in the future.	`ads_management`	`int`
`lifetime_budget`	Defined in cents, minimum 100; can be updated; either a `lifetime_budget`, or a `daily_budget`; an updated budget begins spending from zero (if there's a switch in budget types, the entire campaign-spend to date is set to zero for the purposes of calculating the remaining budget); For more information, see Facebook's Help Center. If you specify a `lifetime_budget`, you should also specify an `end_time` for the campaign.	`ads_management`	`int`

Connections

The adcampaign object has the following connections.

Name	Description	Permissions	Returns
adgroups	The ads in this campaign	`ads_management`	`array` of `adgroup` objects
stats	The statistics for campaign	`ads_management`	`array` of `adstatistics` objects
adcreatives	The creatives for the campaigns	`ads_management`	`adcreative`

Using Ad Campaign objects

A campaign is a group of ads that share the same daily or lifetime budget and schedule. The individual ads have separate bids and targeting. Campaigns enable you to group ads according to your criteria, and you can retrieve the ad-related statistics that apply to a campaign.

Retrieving campaigns

You can retrieve the basic data for all the campaigns in an account.

Alternatively, you can retrieve the basic data for a specific campaign when you specify the campaign ID (unique in the Graph API).

Retrieving campaigns for an account

To retrieve the basic data for all campaigns in an account, make a call to /act_<ACCOUNT NUMBER>/adcampaigns.

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

curl  "https://graph.facebook.com/act_368811234/adcampaigns?
date_format=U&access_token=___"

The response is in the format:

{"data": [
      {
     "id": "6003266501234",
     "account_id": 368811234,
     "campaign_id": 6003266501234,
     "name": "Acme",
     "start_time": 1302027273,
     "updated_time": 1302027509,
     "daily_budget": 500,
     "campaign_status": 3,
     "daily_imps": "0",
     "topline_id": 0,
     "inflation": 0
      },
      {
     "id": "6003266531123",
     "account_id": 368811234,
     "campaign_id": 6003266531123,
     "name": "Champ",
     "start_time": 1302028741,
     "end_time": 1310668740,
     "updated_time": 1308178443,
     "campaign_status": 1,
     "lifetime_budget": 10000,
     "daily_imps": "0",
     "topline_id": 0,
     "inflation": 0
      }
   ]}

Note: At most 500 campaigns can be retrieved in a single call. Use the pagination links in the API response to retrieve further campaigns

When retrieving the adcampaigns of an account you can include deleted campaigns in the response by using the include_deleted parameter.

https://graph.facebook.com/act_368811234/adcampaigns?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 adcampaign IDs, as described in the next section, the include_deleted parameter will be ignored and all of the requested adcampaigns will be returned.

Retrieving basic data for specific campaigns

Retrieving the basic data for specific campaigns is similar to selecting for any object type in the Graph API. The campaign ID is a unique ID so you can specify a request similar to the following:

curl  "https://graph.facebook.com/6003266501234?
date_format=U&access_token=___"

A sample response is: { "id": "6003266501234", "account_id": 368811234, "campaign_id": 6003266501234, "name": "Champ", "start_time": 1302027273, "updated_time": 1308881905, "daily_budget": 500, "campaign_status": 3, "daily_imps": "0", "topline_id": 0, "inflation": 0 }

If you want to retrieve the basic data for multiple campaigns, specify their IDs as follows:

curl  "https://graph.facebook.com?
ids=6003417013123,6003266531123&date_format=U&access_token=___"

A sample response is:

{"6003417013123": {
    "id": "6003417013123",
    "account_id": 368811234,
    "campaign_id": 6003417013123,
    "name": "Champ",
    "start_time": 1308876042,
    "end_time": 0,
    "updated_time": 1308876042,
    "daily_budget": 1000,
    "campaign_status": 1,
    "daily_imps": "0",
    "topline_id": 0,
    "inflation": 0
   },
   "6003266531123": {
    "id": "6003266531123",
    "account_id": 368811234,
    "campaign_id": 6003266531123,
    "name": "NewChamp",
    "start_time": 1302028741,
    "end_time": 1310668740,
    "updated_time": 1308884751,
    "campaign_status": 1,
    "lifetime_budget": 10000,
    "daily_imps": "0",
    "topline_id": 0,
    "inflation": 0
   }}

You can also filter campaigns based on their status, specify the campaign_status parameter in your query, with its value set to an array of campaign status values:

curl  "https://graph.facebook.com?
act_368811234/adcampaigns?campaign_status=[2,3]&access_token=___"

Retrieving the Remaining Budget

The remaining budget (spend) is included in the response if you specify the following in the request:

include_budget_remaining=1

Creating Campaigns

To create a campaign, include a daily budget of at least USD $10 and a campaign name. See above for descriptions of the input parameters (e.g. daily budget, lifetime budget, start time, and active/paused/deleted status).

To create a campaign, specify the data for the campaign in a POST request to the following URL:

https://graph.facebook.com/act_AccountID/adcampaigns

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

 curl -d  "name=Chm&daily_budget=1000&campaign_status=1" 
 "https://graph.facebook.com/act_368811234/adcampaigns?access_token=___"

The result could be similar to the following:

 {"id":6003417011234}

If you want to create a campaign that is not in an active state, then instead of specifying campaign_status=1, specify the following to indicate paused status:

campaign_status=2

Redownloading campaign after creation

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

If you specify the following:

 curl -d  "name=Chm&daily_budget=1000&campaign_status=1&redownload=1" 
 "https://graph.facebook.com/act_368811234/adcampaigns?access_token=___"

The result would be similar to the following:

{"id":"6003826063039","data":{"campaigns":{"6003826063039":{"account_id":19643108,"campaign_id":6003826063039,"name":"Chm","daily_budget":1000,"campaign_status":1,"daily_imps":0,"id":"6003826063039","start_time":1319727249,"end_time":null,"updated_time":1319727249}}}}

Updating and Deleting Campaigns

To update a campaign, specify the data for the campaign in a request to the following URL:

https://graph.facebook.com/CampaignID

You could specify an update to a campaign’s daily budget by specifying a request similar to the following:

curl -d "daily_budget=1100" "https://graph.facebook.com/
6003417011234?access_token=___"

The result could be similar to the following:

true

If you want to update the campaign status, specify campaign_status=1 for active, or campaign_status=2 for paused.

Note: Specifying `end_time`=0 unsets the campaign's end time (if any) and will make it an ongoing campaign with no end date.

Redownloading campaign after updating

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

If you specify the following:

curl -d "daily_budget=1100&redownload=1" "https://graph.facebook.com/
6003417011234?access_token=___"

The result would be similar to the following:

{"result":true,"data":{"campaigns":{"6003826063039":{"account_id":19643108,"campaign_id":6003826063039,"name":"Chm","daily_budget":1100,"campaign_status":1,"daily_imps":0,"id":"6003826063039","start_time":1319727249,"end_time":null,"updated_time":1319727249}}}}

Deleting a campaign

In the legacy Ads API, to delete a campaign, a campaign status of 3 was specified; see campaign_specs array.

In the Graph API, use the HTTP DELETE method to delete an object, such as an adCampaign object:

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

Also note that in the Graph API, you can specify the name of an HTTP method in a URL, as a shortcut for some operations. Thus, you could delete a campaign by specifying its ID as part of a URL similar to the following:

https://graph.facebook.com/6003386561234?method=DELETE&access_token=___

The result could be similar to the following:

true

Updated about 2 weeks ago

Best Practices

Reference

Specs

Advanced Targeting

Queries

Objects

Ad campaign

Example

Fields

Connections

Using Ad Campaign objects

Retrieving campaigns

Retrieving campaigns for an account

Retrieving basic data for specific campaigns

Retrieving the Remaining Budget

Creating Campaigns

Redownloading campaign after creation

Updating and Deleting Campaigns

Note: Specifying `end_time`=0 unsets the campaign's end time (if any) and will make it an ongoing campaign with no end date.

Redownloading campaign after updating

Deleting a campaign

Best Practices

Reference

Specs

Advanced Targeting

Queries

Objects

Ad campaign

Example

Fields

Connections

Using Ad Campaign objects

Retrieving campaigns

Retrieving campaigns for an account

Retrieving basic data for specific campaigns

Retrieving the Remaining Budget

Creating Campaigns

Redownloading campaign after creation

Updating and Deleting Campaigns

Note: Specifying end_time=0 unsets the campaign's end time (if any) and will make it an ongoing campaign with no end date.

Redownloading campaign after updating

Deleting a campaign

Note: Specifying `end_time`=0 unsets the campaign's end time (if any) and will make it an ongoing campaign with no end date.