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
.
Starting June 2020, advertisers running ads about social issues, elections, and politics need to specify special_ad_categories
while creating an ad campaign. In addition, businesses still have to set authorization_category
to flag at the ad creative level. Learn more about the requirements.
Returns the campaigns under this ad account. A request with no filters returns only campaigns that were not archived or deleted.
GET /v14.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/v14.0/act_<AD_ACCOUNT_ID>/campaigns
Parameter | Description |
---|---|
date_preset enum{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_status list<enum{ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ARCHIVED, ADSET_PAUSED, IN_PROCESS, WITH_ISSUES}> | Default value: Vec effective status for the campaigns |
is_completed boolean | If |
time_range {'since':YYYY-MM-DD,'until':YYYY-MM-DD} | Date range used to aggregate insights metrics |
Reading from this edge will return a JSON formatted result:
{ "
data
": [], "paging
": {}, "summary
": {} }
data
paging
summary
Aggregated information about the edge, such as counts. Specify the fields to fetch in the summary param (like summary=insights
).
Field | Description |
---|---|
insights | Analytics summary for all objects |
total_count unsigned int32 | Total number of objects |
Error | Description |
---|---|
100 | Invalid parameter |
200 | Permissions error |
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. |
80000 | There have been too many calls from 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. |
368 | The action attempted has been deemed abusive or is otherwise disallowed |
190 | Invalid OAuth 2.0 Access Token |
3018 | The start date of the time range cannot be beyond 37 months from the current date |
campaigns
edge from the following paths: POST /v14.0/act_<AD_ACCOUNT_ID>/campaigns HTTP/1.1
Host: graph.facebook.com
name=My+campaign&objective=LINK_CLICKS&status=PAUSED&special_ad_categories=%5B%5D
/* 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' => 'LINK_CLICKS',
'status' => 'PAUSED',
'special_ad_categories' => '[]',
),
'{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": "LINK_CLICKS",
"status": "PAUSED",
"special_ad_categories": "[]"
},
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
Bundle params = new Bundle();
params.putString("name", "My campaign");
params.putString("objective", "LINK_CLICKS");
params.putString("status", "PAUSED");
params.putString("special_ad_categories", "[]");
/* 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": @"LINK_CLICKS",
@"status": @"PAUSED",
@"special_ad_categories": @"[]",
};
/* 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="LINK_CLICKS"' \
-F 'status="PAUSED"' \
-F 'special_ad_categories=[]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v14.0/act_<AD_ACCOUNT_ID>/campaigns
Parameter | Description |
---|---|
adlabels list<Object> | Ad Labels associated with this campaign |
enum{LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP} | Choose bid strategy for this campaign to suit your specific business goals.
Each strategy has tradeoffs and may be available for certain Notes:
|
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: |
campaign_optimization_type enum{NONE, ICO_ONLY} | campaign_optimization_type |
daily_budget int64 | 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_options list<enum{validate_only, include_recommendations}> | Default value: Set An execution setting |
is_skadnetwork_attribution boolean | To create an iOS 14 campaign, enable SKAdNetwork attribution for this campaign. |
is_using_l3_schedule boolean | is_using_l3_schedule |
iterative_split_test_configs list<Object> | Array of Iterative Split Test Configs created under this campaign . |
lifetime_budget int64 | 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. |
name string | Name for this campaign Supports Emoji |
objective enum{APP_INSTALLS, BRAND_AWARENESS, CONVERSIONS, EVENT_RESPONSES, LEAD_GENERATION, LINK_CLICKS, LOCAL_AWARENESS, MESSAGES, OFFER_CLAIMS, 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. The |
promoted_object Object | The object this campaign is promoting across all its ads. Only |
source_campaign_id numeric 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}> | special_ad_categories Required |
array<enum {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_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 |
start_time datetime | start_time |
status enum{ACTIVE, PAUSED, DELETED, ARCHIVED} | Only |
stop_time datetime | stop_time |
topline_id numeric string or integer | Topline ID |
upstream_events dictionary { string : <dictionary { string : <string> }> } | Upstream events |
id
in the return type.id
: numeric string, success
: bool, Error | Description |
---|---|
100 | Invalid parameter |
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. |
200 | Permissions error |
300 | Edit failure |
2615 | Invalid call to update this adaccount |
900 | No such application exists. |
190 | Invalid OAuth 2.0 Access Token |
/act_{ad_account_id}/campaigns
.Parameter | 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 | Object count |
objects_left_to_delete_count
: unsigned int32, deleted_object_ids
: List [Error | Description |
---|---|
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. |