Graph API Version

    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

    Graph API Explorer
    GET /v15.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/v15.0/act_<AD_ACCOUNT_ID>/campaigns
    If you want to learn how to use the Graph API, read our Using Graph API guide.

    Parameters

    ParameterDescription
    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 true, we return completed campaigns.

    time_range
    {'since':YYYY-MM-DD,'until':YYYY-MM-DD}

    Date range used to aggregate insights metrics

    since
    datetime

    A date in the format of "YYYY-MM-DD", which means from the beginning midnight of that day.

    until
    datetime

    A date in the format of "YYYY-MM-DD", which means to the beginning midnight of the following day.

    Fields

    Reading from this edge will return a JSON formatted result:

    { "data": [], "paging": {}, "summary": {} }

    data

    A list of AdCampaignGroup 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).

    FieldDescription
    insights

    Analytics summary for all objects

    total_count
    unsigned int32

    Total number of objects

    Error Codes

    ErrorDescription
    100Invalid parameter
    200Permissions error
    80004There 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.
    190Invalid OAuth 2.0 Access Token
    80000There 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.
    3018The start date of the time range cannot be beyond 37 months from the current date
    270This Ads API request is not allowed for apps with development access level (Development access is by default for all apps, please request for upgrade). Make sure that the access token belongs to a user that is both admin of the app and admin of the ad account

    Creating

    You can make a POST request to campaigns edge from the following paths:
    When posting to this edge, a Campaign will be created.

    Example

    Graph API Explorer
    POST /v15.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/v15.0/act_<AD_ACCOUNT_ID>/campaigns
    If you want to learn how to use the Graph API, read our Using Graph API guide.

    Parameters

    ParameterDescription
    adlabels
    list<Object>

    Ad Labels associated with this campaign

    bid_strategy
    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 optimization_goals:
    LOWEST_COST_WITHOUT_CAP: Designed to get the most results for your budget based on your ad set optimization_goal without limiting your bid amount. This is the best strategy if you care most about cost efficiency. However with this strategy it may be harder to get stable average costs as you spend. This strategy is also known as automatic bidding. Learn more in Ads Help Center, About bid strategies: Lowest cost.
    LOWEST_COST_WITH_BID_CAP: Designed to get the most results for your budget based on your ad set optimization_goal while limiting actual bid to your specified amount. With a bid cap you have more control over your cost per actual optimization event. However if you set a limit which is too low you may get less ads delivery. If you select this, you must provide a bid cap in the bid_amount field for each ad set in this ad campaign. Note: during creation this is the default bid strategy if you don't specify. This strategy is also known as manual maximum-cost bidding. Learn more in Ads Help Center, About bid strategies: Lowest cost.

    Notes:

    • If you do not enable campaign budget optimization, you should set bid_strategy at ad set level.
    • TARGET_COST bidding strategy has been deprecated with Marketing API v9.

    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:
    AUCTION (default)
    RESERVED (for reach and frequency ads).

    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
    validate_only: when this option is specified, the API call will not perform the mutation but will run through the validation rules against values of each field.
    include_recommendations: this option cannot be used by itself. When this option is used, recommendations for ad object's configuration will be included. A separate section recommendations will be included in the response, but only if recommendations for this specification exist.
    If the call passes validation or review, response will be {"success": true}. If the call does not pass, an error will be returned with more details. These options can be used to improve any UI to display errors to the user much sooner, e.g. as soon as a new value is typed into any field corresponding to this ad object, rather than at the upload/save stage, or after review.

    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.
    Currently, with BRAND_AWARENESS objective, all creatives should be either only images or only videos, not mixed.

    OUTCOME_APP_PROMOTION, OUTCOME_AWARENESS, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, and OUTCOME_TRAFFIC are newer objectives that will eventually replace the original objectives: 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.

    promoted_object
    Object

    The object this campaign is promoting across all its ads. Only product_catalog_id is used at the ad set level.

    application_id
    int

    The ID of a Facebook Application. Usually related to mobile or canvas games being promoted on Facebook for installs or engagement

    pixel_id
    numeric string or integer

    The ID of a Facebook conversion pixel. Used with offsite conversion campaigns.

    custom_event_type
    enum{RATE, TUTORIAL_COMPLETION, CONTACT, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, SCHEDULE, START_TRIAL, SUBMIT_APPLICATION, SUBSCRIBE, ADD_TO_CART, ADD_TO_WISHLIST, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, PURCHASE, LEAD, COMPLETE_REGISTRATION, CONTENT_VIEW, SEARCH, SERVICE_BOOKING_REQUEST, MESSAGING_CONVERSATION_STARTED_7D, LEVEL_ACHIEVED, ACHIEVEMENT_UNLOCKED, SPENT_CREDITS, LISTING_INTERACTION, D2_RETENTION, D7_RETENTION, OTHER}

    The event from an App Event of a mobile app, not in the standard event list.

    object_store_url
    URL

    The uri of the mobile / digital store where an application can be bought / downloaded. This is platform specific. When combined with the "application_id" this uniquely specifies an object which can be the subject of a Facebook advertising campaign.

    offer_id
    numeric string or integer

    The ID of an Offer from a Facebook Page.

    page_id
    Page ID

    The ID of a Facebook Page

    product_catalog_id
    numeric string or integer

    The ID of a Product Catalog. Used with Dynamic Product Ads.

    product_item_id
    numeric string or integer

    The ID of the product item.

    instagram_profile_id
    numeric string or integer

    The ID of the instagram profile id.

    product_set_id
    numeric string or integer

    The ID of a Product Set within an Ad Set level Product Catalog. Used with Dynamic Product Ads.

    event_id
    numeric string or integer

    The ID of a Facebook Event

    offline_conversion_data_set_id
    numeric string or integer

    The ID of the offline dataset.

    fundraiser_campaign_id
    numeric string or integer

    The ID of the fundraiser campaign.

    custom_event_str
    string

    The event from an App Event of a mobile app, not in the standard event list.

    mcme_conversion_id
    numeric string or integer

    The ID of a MCME conversion.

    omnichannel_object
    Object

    app
    array<JSON object>

    pixel
    array<JSON object>

    Required
    onsite
    array<JSON object>

    source_campaign_id
    numeric string or integer

    Used if a campaign has been copied. The ID from the original campaign that was copied.

    special_ad_categories
    array<enum {NONE, EMPLOYMENT, HOUSING, CREDIT, ISSUES_ELECTIONS_POLITICS, ONLINE_GAMBLING_AND_GAMING}>

    special_ad_categories

    Required
    special_ad_category_country
    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 ACTIVE and PAUSED are valid during creation. Other statuses can be used for update. If it is set to PAUSED, its active child objects will be paused and have an effective status CAMPAIGN_PAUSED.

    stop_time
    datetime

    stop_time

    topline_id
    numeric string or integer

    Topline ID

    upstream_events
    dictionary { string : <dictionary { string : <string> }> }

    Upstream events

    Return Type

    This endpoint supports read-after-write and will read the node represented by id in the return type.
    Struct {
    id: numeric string,
    success: bool,
    }

    Error Codes

    ErrorDescription
    100Invalid parameter
    80004There 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.
    200Permissions error
    2615Invalid call to update this adaccount
    300Edit failure
    900No such application exists.
    190Invalid OAuth 2.0 Access Token

    Updating

    You can't perform this operation on this endpoint.

    Deleting

    You can dissociate a Campaign from an AdAccount by making a DELETE request to /act_{ad_account_id}/campaigns.

    Parameters

    ParameterDescription
    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

    Return Type

    Struct {
    objects_left_to_delete_count: unsigned int32,
    deleted_object_ids: List [
    numeric string
    ],
    }

    Error Codes

    ErrorDescription
    100Invalid parameter