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 removed kpi_custom_conversion_id, kpi_type, and kpi_results.
Beginning September 15, 2022, with the release of Marketing API v15.0, advertisers will no longer be allowed to create incremental conversion optimization campaigns. Existing conversion optimization campaigns will behave normally.
Ads About Social Issues, Elections, and Politics
Beginning with the release of Marketing API v15.0, advertisers will no longer be able to create Special Ad Audiences. See Special Ad Audiences details here for more information.
Reading
Returns the campaigns under this ad account. A request with no filters returns only campaigns that were not archived or deleted.
Example
GET /v24.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?effective_status=%5B%22ACTIVE%22%2C%22PAUSED%22%5D&fields=name%2Cobjective',
'{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();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 -X GET -G \
-d 'effective_status=[
"ACTIVE",
"PAUSED"
]' \
-d 'fields="name,objective"' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v24.0/act_<AD_ACCOUNT_ID>/campaignsParameters
| Parameter | Description |
|---|---|
date_presetenum{today, yesterday, this_month, last_month, this_quarter, maximum, data_maximum, 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_statuslist<enum{ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ARCHIVED, ADSET_PAUSED, IN_PROCESS, WITH_ISSUES}> | Default value: Veceffective status for the campaigns |
is_completedboolean | If |
time_range{'since':YYYY-MM-DD,'until':YYYY-MM-DD} | Date range used to aggregate insights metrics |
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 |
|---|---|
insightsEdge<AdsInsights> | Analytics summary for all objects |
total_countunsigned int32 | Total number of objects |
Error Codes
| Error | Description |
|---|---|
| 200 | Permissions error |
| 100 | Invalid parameter |
| 190 | Invalid OAuth 2.0 Access Token |
| 80004 | There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting#ads-management. |
| 613 | Calls to this api have exceeded the rate limit. |
| 368 | The action attempted has been deemed abusive or is otherwise disallowed |
| 2635 | You are calling a deprecated version of the Ads API. Please update to the latest version. |
| 3018 | The start date of the time range cannot be beyond 37 months from the current date |
| 2500 | Error parsing graph query |
Creating
campaigns edge from the following paths: Example
POST /v24.0/act_<AD_ACCOUNT_ID>/campaigns HTTP/1.1
Host: graph.facebook.com
name=My+campaign&objective=OUTCOME_TRAFFIC&status=PAUSED&special_ad_categories=%5B%5D&is_adset_budget_sharing_enabled=0/* 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' => 'OUTCOME_TRAFFIC',
'status' => 'PAUSED',
'special_ad_categories' => '[]',
'is_adset_budget_sharing_enabled' => '0',
),
'{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": "OUTCOME_TRAFFIC",
"status": "PAUSED",
"special_ad_categories": "[]",
"is_adset_budget_sharing_enabled": "0"
},
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);Bundle params = new Bundle();
params.putString("name", "My campaign");
params.putString("objective", "OUTCOME_TRAFFIC");
params.putString("status", "PAUSED");
params.putString("special_ad_categories", "[]");
params.putString("is_adset_budget_sharing_enabled", "0");
/* 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();NSDictionary *params = @{
@"name": @"My campaign",
@"objective": @"OUTCOME_TRAFFIC",
@"status": @"PAUSED",
@"special_ad_categories": @"[]",
@"is_adset_budget_sharing_enabled": @"0",
};
/* 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 \
-F 'name="My campaign"' \
-F 'objective="OUTCOME_TRAFFIC"' \
-F 'status="PAUSED"' \
-F 'special_ad_categories=[]' \
-F 'is_adset_budget_sharing_enabled=0' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v24.0/act_<AD_ACCOUNT_ID>/campaignsParameters
| Parameter | Description |
|---|---|
adlabelslist<Object> | Ad Labels associated with this campaign |
enum{LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS} | Choose bid strategy for this campaign to suit your specific business goals.
Each strategy has tradeoffs and may be available for certain Notes:
|
budget_schedule_specslist<JSON or object-like arrays> | Initial high demand periods to be created with the campaign. |
buying_typestring | Default value: AUCTIONThis 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: |
campaign_optimization_typeenum{NONE, ICO_ONLY} | campaign_optimization_type |
daily_budgetint64 | Daily budget of this campaign. All adsets under this campaign will share this budget. You can either set budget at the campaign level or at the adset level, not both. |
execution_optionslist<enum{validate_only, include_recommendations}> | Default value: SetAn execution setting |
is_skadnetwork_attributionboolean | To create an iOS 14 campaign, enable SKAdNetwork attribution for this campaign. |
is_using_l3_scheduleboolean | is_using_l3_schedule |
iterative_split_test_configslist<Object> | Array of Iterative Split Test Configs created under this campaign . |
lifetime_budgetint64 | Lifetime budget of this campaign. All adsets under this campaign will share this budget. You can either set budget at the campaign level or at the adset level, not both. |
namestring | Name for this campaign Supports Emoji |
objectiveenum{APP_INSTALLS, BRAND_AWARENESS, CONVERSIONS, EVENT_RESPONSES, LEAD_GENERATION, LINK_CLICKS, LOCAL_AWARENESS, MESSAGES, OFFER_CLAIMS, OUTCOME_APP_PROMOTION, OUTCOME_AWARENESS, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_TRAFFIC, PAGE_LIKES, POST_ENGAGEMENT, PRODUCT_CATALOG_SALES, REACH, STORE_VISITS, VIDEO_VIEWS} | Campaign's objective. If it is specified the API will validate that any ads created under the campaign match that objective. |
promoted_objectObject | The object this campaign is promoting across all its ads. It’s required for Meta iOS 14+ app promotion (SKAdNetwork or Aggregated Event Measurement) campaign creation. Only |
source_campaign_idnumeric string or integer | Used if a campaign has been copied. The ID from the original campaign that was copied. |
array<enum {NONE, EMPLOYMENT, HOUSING, CREDIT, ISSUES_ELECTIONS_POLITICS, ONLINE_GAMBLING_AND_GAMING, FINANCIAL_PRODUCTS_SERVICES}> | special_ad_categories Required |
array<enum {AC, AD, AE, AF, AG, AI, AL, AM, AN, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, XK, YE, YT, ZA, ZM, ZW}> | special_ad_category_country |
spend_capint64 | 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 |
start_timedatetime | start_time |
statusenum{ACTIVE, PAUSED, DELETED, ARCHIVED} | Only |
stop_timedatetime | stop_time |
topline_idnumeric string or integer | Topline ID |
Return Type
id in the return type.id: numeric string, success: bool, Error Codes
| Error | Description |
|---|---|
| 100 | Invalid parameter |
| 613 | Calls to this api have exceeded the rate limit. |
| 200 | Permissions error |
| 2635 | You are calling a deprecated version of the Ads API. Please update to the latest version. |
| 190 | Invalid OAuth 2.0 Access Token |
| 80004 | There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting#ads-management. |
| 300 | Edit failure |
Updating
Deleting
/act_{ad_account_id}/campaigns.Parameters
| Parameter | Description |
|---|---|
before_datedatetime | Set a before date to delete campaigns before this date |
delete_strategyenum{DELETE_ANY, DELETE_OLDEST, DELETE_ARCHIVED_BEFORE} | Delete strategy Required |
object_countinteger | Object count |
Return Type
objects_left_to_delete_count: unsigned int32, deleted_object_ids: List [Error Codes
| Error | Description |
|---|---|
| 100 | Invalid parameter |