Graph API Version

Ad Study Cell

Reading

A lift study cell.

Examples

To read the details of an Ad study cell, make an HTTP GET request to

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

Example

Graph API Explorer
GET /v5.0/{ad-study-cell-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-cell-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-cell-id}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{ad-study-cell-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-cell-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
id
numeric string

ID of the lift study cell.

ad_entities_count
unsigned int32

The sum of the number of ad accounts, ad campaigns and ad sets in this cell.

control_percentage
float

The percent of the total population in the control group, who will not see the ads.

name
string

Name of the lift study cell

treatment_percentage
float

The percentage of the total population who will see the ads

Edges

EdgeDescription

Ad accounts in the cell.

Ad sets in the cell.

Ad campaigns in the cell.

Validation Rules

ErrorDescription
200Permissions error

Creating

Cell creation is part of Ad Study creation since percentage fields (e.g. treatment_percentage) of all the cells of a study are correlated. Please see Ad Study Creating section for details.

You can't perform this operation on this endpoint.

Updating

You can update most of the cell fields (e.g. name, description, associated objects like adaccounts, adcampaigns, etc) at cell level. However, If you want to update the percentage fields of the cell (e.g treatment_percentage), you must do it at study level along with other cells. Please see Ad Study for details

Examples

To update study cell fields:

curl \
-F 'name="new group name"' \
-F 'adcampaigns=[<AD_SET_ID>]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/<AD_STUDY_CELL_ID>

You can update an AdStudyCell by making a POST request to /{ad_study_cell_id}.

Parameters

ParameterDescription
adaccounts
list<int64>

A list of ad accounts that belong to this cell

adsets
list<numeric string or integer>

A list of ad sets that belong to this cell

campaigns
list<numeric string or integer>

A list of ad campaigns that belong to this cell

creation_template
enum {AUTOMATIC_PLACEMENTS, BRAND_AWARENESS, FACEBOOK, FACEBOOK_AUDIENCE_NETWORK, FACEBOOK_INSTAGRAM, FACEBOOK_NEWS_FEED, FACEBOOK_NEWS_FEED_IN_STREAM_VIDEO, IN_STREAM_VIDEO, INSTAGRAM, MOBILE_OPTIMIZED_VIDEO, PAGE_POST_ENGAGEMENT, REACH, TV_COMMERCIAL, TV_FACEBOOK, VIDEO_VIEW_OPTIMIZATION, LOW_FREQUENCY, MEDIUM_FREQUENCY, HIGH_FREQUENCY}

Template the study cell adhered to in the creation UI

description
string

A user provided description for the purpose of this cell.

name
string

A user provided label for this cell.

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

Deleting

To delete a study cell:

curl -X DELETE
"https://graph.facebook.com/<API_VERSION>/<AD_STUDY_CELL_ID>"

You can't perform this operation on this endpoint.