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 these experiments:
Study Type | Use Case |
---|---|
Inform near-term optimization decisions. Example: Is Creative A doing better than Creative B? | |
Measure incremental impact of Facebook ads on business outcomes. | |
Measure incremental impact of different Facebook ads strategies on business outcomes. | |
Retrieve and analyze your brand lift study results. |
See Lift Study for setting up Conversion Lift and Multi-Cell Conversion Lift.
A lift study object
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>"
}
],
}
}
],
}
GET /v21.0/{ad-study-id} 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(
'/{ad-study-id}',
'{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(
"/{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();
/* 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
}];
Field | Description |
---|---|
id numeric string | ID of the Lift study |
business | The business that owns this study if it exists. |
canceled_time datetime | Time stamp when study was canceled |
cooldown_start_time datetime | Cooldown start time |
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 |
name string | Name of the Lift study |
observation_end_time datetime | Observation end time |
results_first_available_date string | When results for at least one objective of the study are available |
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 |
Edge | Description |
---|---|
Edge<AdStudyCell> | The cells which are part of the objective |
Edge<AdStudyObjective> | The objectives which are part of the objective |
Error | Description |
---|---|
100 | Invalid parameter |
368 | The action attempted has been deemed abusive or is otherwise disallowed |
200 | Permissions error |
2500 | Error parsing graph query |
190 | Invalid OAuth 2.0 Access Token |
treatment_percentage
for each cell should be at least 10. treatment_percentage
for all study cells should be less or equal to 100.adaccounts
, campaigns
, or adsets
.ad_studies
edge from the following paths: Parameter | Description |
---|---|
cells list<Object> | Describes the cells in the study. Required |
client_business numeric string or integer | Business associated with the study. |
confidence_level float | Confidence level used in power calculations and final study report. |
cooldown_start_time integer | Start of the pre-measurement cool-down period. This period ends when the study period starts. |
description string | The purpose of the study. |
end_time integer | Time when the study period ends. Required |
name string | Name of the study. Required |
objectives list<Object> | A vector of objects describing the objectives assigned to this study. |
observation_end_time integer | The end of the observation period for this study. This period starts when the study period ends. |
start_time integer | The time when the study period starts. Required |
type enum {LIFT, SPLIT_TEST, CONTINUOUS_LIFT_CONFIG, GEO_LIFT, BACKEND_AB_TESTING} | The type of ad study, such as |
viewers list<int> | This study is shared with these people. |
id
in the return type.id
: numeric string, Error | Description |
---|---|
100 | Invalid parameter |
ad_studies
edge from the following paths: Parameter | Description |
---|---|
cells list<Object> | A shape to describe the cells of the study |
client_business numeric string or integer | Business associated with study |
confidence_level float | Confidence level used in power calculation and final report |
cooldown_start_time integer | The beginning of the pre measurement cooldown period. This period ends when the study period starts. |
description string | A brief description about the purpose of the study. |
end_time integer | The time when the study period ends. |
name string | The name of the study. |
objectives list<Object> | A vector of objects describing the objectives assigned to this study |
observation_end_time integer | The end of the observation period for this study, this period starts when the study period ends. |
start_time integer | The time when the study period starts. |
type enum {LIFT, SPLIT_TEST, CONTINUOUS_LIFT_CONFIG, GEO_LIFT, BACKEND_AB_TESTING} | The type of ad study, either SPLIT_TEST or LIFT. |
viewers list<int> | The list of people who this study has been shared with. |
id
in the return type.id
: numeric string, cell_ids
: List [objective_ids
: List [Error | Description |
---|---|
200 | Permissions error |
100 | Invalid parameter |
To update study fields:
curl \
-F 'name="new name"' \
-F 'end_time=1437004800' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/<AD_STUDY_ID>
Add a cell an existing study and change treatment_percentage
of all the cells:
curl \
-F 'cells=[{id:<CELL_ID>,treatment_percentage:50},{id:<CELL_ID>,treatment_percentage:10},{name:"Group C",treatment_percentage:20,adsets:[<AD_SET_ID>]}]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/<AD_STUDY_ID>
To update treatment_percentage
for a cell, do it at the study level along with other cells. You also make updates to a study to add additional cells to it. You must provide the percentage of all existing and new cells in the study update since they are correlated.
Once the study runs, you cannot update start_time
, treatment_percentage
for cells. You cannot remove associated objects such as adsets
, adaccounts
, campaigns
. However, you can update end_time
to the future time if the study is not yet ended and add new associated objects to the cells if needed.
/{ad_study_id}
.Parameter | Description |
---|---|
cells list<Object> | A shape to describe the cells of the study |
client_business numeric string or integer | Business associated with study |
confidence_level float | Confidence level used in power calculation and final report |
cooldown_start_time integer | The beginning of the pre measurement cooldown period. This period ends when the study period starts. |
description string | A brief description about the purpose of the study. |
end_time integer | The time when the study period ends. |
name string | The name of the study. |
objectives list<Object> | A vector of objects describing the objectives assigned to this study |
observation_end_time integer | The end of the observation period for this study, this period starts when the study period ends. |
start_time integer | The time when the study period starts. |
type enum {LIFT, SPLIT_TEST, CONTINUOUS_LIFT_CONFIG, GEO_LIFT, BACKEND_AB_TESTING} | A type of the study. |
viewers list<int> | The list of people who this study has been shared with. |
success
: bool, cell_ids
: List [objective_ids
: List [Error | Description |
---|---|
100 | Invalid parameter |
200 | Permissions error |
To delete a study:
curl -X DELETE "https://graph.facebook.com/<API_VERSION>/<AD_STUDY_ID>"