Marketing API Version

Ad Study

Test your ads and choose the strategy that is driving the most conversions. For example, create a split test to find out which ad set performs the best:

curl \
-F 'name="new study"' \
-F 'description="test creative"' \
-F 'start_time=1435622400' \
-F 'end_time=1436918400' \
-F 'type=SPLIT_TEST' \
-F 'cells=[{name:"Group A",treatment_percentage:50,adsets:[<AD_SET_ID>]},{name:"Group B",treatment_percentage:50,adsets:[<AD_SET_ID>]}]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/ad_studies

Use ad study for three types of experiments:

Study TypeUse Case

Split Testing

Inform near-term optimization decisions. Example: Is Creative A doing better than Creative B?

Conversion Lift

Measure incremental impact of Facebook ads on business outcomes

Multi-Cell Conversion Lift

Measure and incremental impact of different Facebook ads strategies on business outcomes

See Lift Study for setting up Conversion Lift and Multi-Cell Conversion Lift.

Reading

A lift study object

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
  • ads_read
Page management Apps
No data
Other Apps
No data

Examples

To read the details for a study, make a HTTP GET to:

 https://graph.facebook.com/<API_VERSION>/<AD_STUDY_ID>

To read about the cells in a study:

curl -G \
-d 'fields="name,treatment_percentage,campaigns,adsets,adaccounts"' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/<AD_STUDY_ID>/cells


// The response
{
  "data": [
    {
      "id": "<CELL_ID>",
      "name": Group A,
      "treatment_percentage": 50,
      "adsets": {
        "data": [
          {
           "id": "<AD_SET_ID>"
          }
        ],
      }
    },
    {
      "id": "<CELL_ID>",
      "name": Group B,
      "treatment_percentage": 50,
      "adsets": {
        "data": [
          {
            "id": "<AD_SET_ID>"
          }
        ],
      }
    }
  ],
}

Examples

Graph API Explorer
GET /v2.10/{ad-study-id} HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/{ad-study-id}'
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */
/* make the API call */
FB.api(
    "/{ad-study-id}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{ad-study-id}",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{ad-study-id}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

This endpoint doesn't have any parameters.

Fields

FieldDescription

business

Business

The business that owns this study if it exists.

canceled_time

datetime

Time stamp when study was canceled

created_by

Who Lift study was created by

created_time

datetime

When was the Lift study created

description

string

Description

end_time

datetime

End time

id

numeric string

ID of the Lift study

name

string

Name of the Lift study

start_time

datetime

Start time

type

string

The type of study, either audience segmentation or lift.

updated_by

Updated by

updated_time

datetime

Updated time

Edges

EdgeDescription

cells

The cells which are part of the objective

userpermissions

User permissions for the lift study

viewers

The people who have been added to this studyas a viewer

Validation Rules

ErrorDescription
100Invalid parameter
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.
210User not visible

Creating

Requirements

  • treatment_percentage for each cell should be at least 10.
  • The sum of treatment_percentage for all study cells should be less or equal to 100.
  • Each cell must have at least one object associated with it. The object can be adaccounts, campaigns, or adsets.
You can make a POST request to customaudiences edge from the following paths:
When posting to this edge, an AdStudy will be created.

Parameters

NameDescription
account_id
numeric string

Account ID to which audience should be attached

Required
audience_name
string

Name of the new audience

Required
audience_type
enum {MOST_RESPONSIVE, NOT_MOST_RESPONSIVE}

Type of the audience to be created

Required
cell_id
numeric string or integer

Cell ID of the study, optional

objective_id
numeric string or integer

Objective ID of the study, optional

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
}
You can make a POST request to userpermissions edge from the following paths:
When posting to this edge, an AdStudy will be created.

Parameters

NameDescription
business
numeric string or integer

business

email
string

email

role
enum {ADMIN, ANALYST}

role

Required
user
int

user

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error

Updating

You can't perform this operation on this endpoint.

Deleting

To delete a study:

curl -X DELETE
"https://graph.facebook.com/<API_VERSION>/<AD_STUDY_ID>"
You can dissociate an AdStudy from an AdStudy by making a DELETE request to /{ad_study_id}/userpermissions.

Parameters

NameDescription
business
numeric string or integer

business

email
string

email

user
int

user

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
200Permissions error
100Invalid parameter