# 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
```
curl \
-F &#039;name=&quot;new study&quot;&#039; \
-F &#039;description=&quot;test creative&quot;&#039; \
-F &#039;start_time=1435622400&#039; \
-F &#039;end_time=1436918400&#039; \
-F &#039;type=SPLIT_TEST&#039; \
-F &#039;cells=[&#123;name:&quot;Group A&quot;,treatment_percentage:50,adsets:[&lt;AD_SET_ID&gt;]&#125;,&#123;name:&quot;Group B&quot;,treatment_percentage:50,adsets:[&lt;AD_SET_ID&gt;]&#125;]&#039; \
-F &#039;access_token=&lt;ACCESS_TOKEN&gt;&#039; \
https://graph.facebook.com/&lt;API_VERSION&gt;/&lt;BUSINESS_ID&gt;/ad_studies
```

Use ad study for these experiments:

| Study Type | Use Case |
| --- | --- |
| [Split Testing](https://developers.facebook.com/documentation/ads-commerce/marketing-api/guides/split-testing) | Inform near-term optimization decisions. Example: Is Creative A doing better than Creative B? |
| [Conversion Lift](https://developers.facebook.com/documentation/ads-commerce/marketing-api/guides/lift-studies) | Measure incremental impact of Facebook ads on business outcomes. |
| [Multi-Cell Conversion Lift](https://developers.facebook.com/documentation/ads-commerce/marketing-api/guides/lift-studies) | Measure incremental impact of different Facebook ads strategies on business outcomes. |
| [Brand Lift Results](https://developers.facebook.com/docs/marketing-api/guides/brand_lift) | Retrieve and analyze your brand lift study results. |

See [Lift Study](https://developers.facebook.com/documentation/ads-commerce/marketing-api/guides/lift-studies) for setting up Conversion Lift and Multi-Cell Conversion Lift.

## Reading

A lift study object

### Examples &#123;#read-examples&#125;

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

```
https://graph.facebook.com/&lt;API_VERSION&gt;/&lt;AD_STUDY_ID&gt;
```

To read about the cells in a study:

### cURL
```
curl -G \
-d &#039;fields=&quot;name,treatment_percentage,campaigns,adsets,adaccounts&quot;&#039; \
-d &#039;access_token=&lt;ACCESS_TOKEN&gt;&#039; \
https://graph.facebook.com/&lt;API_VERSION&gt;/&lt;AD_STUDY_ID&gt;/cells

// The response
&#123;
  &quot;data&quot;: [
    &#123;
      &quot;id&quot;: &quot;&lt;CELL_ID&gt;&quot;,
      &quot;name&quot;: Group A,
      &quot;treatment_percentage&quot;: 50,
      &quot;adsets&quot;: &#123;
        &quot;data&quot;: [
          &#123;
           &quot;id&quot;: &quot;&lt;AD_SET_ID&gt;&quot;
          &#125;
        ],
      &#125;
    &#125;,
    &#123;
      &quot;id&quot;: &quot;&lt;CELL_ID&gt;&quot;,
      &quot;name&quot;: Group B,
      &quot;treatment_percentage&quot;: 50,
      &quot;adsets&quot;: &#123;
        &quot;data&quot;: [
          &#123;
            &quot;id&quot;: &quot;&lt;AD_SET_ID&gt;&quot;
          &#125;
        ],
      &#125;
    &#125;
  ],
&#125;
```

#### Example

### HTTP
```
GET /v25.0/&#123;ad-study-id&#125; HTTP/1.1
Host: graph.facebook.com
```

### PHP SDK
```
/* PHP SDK v5.0.0 */
/* make the API call */
try &#123;
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb-&gt;get(
    &#039;/&#123;ad-study-id&#125;&#039;,
    &#039;&#123;access-token&#125;&#039;
  );
&#125; catch(Facebook\Exceptions\FacebookResponseException $e) &#123;
  echo &#039;Graph returned an error: &#039; . $e-&gt;getMessage();
  exit;
&#125; catch(Facebook\Exceptions\FacebookSDKException $e) &#123;
  echo &#039;Facebook SDK returned an error: &#039; . $e-&gt;getMessage();
  exit;
&#125;
$graphNode = $response-&gt;getGraphNode();
/* handle the result */
```

### JavaScript SDK
```
/* make the API call */
FB.api(
    &quot;/&#123;ad-study-id&#125;&quot;,
    function (response) &#123;
      if (response &amp;&amp; !response.error) &#123;
        /* handle the result */
      &#125;
    &#125;
);
```

### Android SDK
```
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    &quot;/&#123;ad-study-id&#125;&quot;,
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() &#123;
        public void onCompleted(GraphResponse response) &#123;
            /* handle the result */
        &#125;
    &#125;
).executeAsync();
```

### iOS SDK
```
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:&#064;&quot;/&#123;ad-study-id&#125;&quot;
                                      parameters:params
                                      HTTPMethod:&#064;&quot;GET&quot;];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) &#123;
    // Handle the result
&#125;];
```

Try it in [Graph API Explorer](https://developers.facebook.com/tools/explorer/?method=GET&amp;path=%7Bad-study-id%7D&amp;version=v25.0)

If you want to learn how to use the Graph API, read our [Using Graph API guide](https://developers.facebook.com/docs/graph-api/using-graph-api)

#### Parameters

This endpoint doesn&#039;t have any parameters.

#### Fields

| Field | Description |
| --- | --- |
| `id`&lt;br&gt;&lt;br&gt;*numeric string* | ID of the Lift study&lt;br&gt;&lt;br&gt;&lt;br&gt;**[default]**&lt;br&gt; |
| `business`&lt;br&gt;&lt;br&gt;*[Business](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/business)* | The business that owns this study if it exists.&lt;br&gt; |
| `canceled_time`&lt;br&gt;&lt;br&gt;*datetime* | Time stamp when study was canceled&lt;br&gt; |
| `cooldown_start_time`&lt;br&gt;&lt;br&gt;*datetime* | Cooldown start time&lt;br&gt; |
| `created_by`&lt;br&gt;&lt;br&gt;*[User](https://developers.facebook.com/docs/graph-api/reference/user)* | Who Lift study was created by&lt;br&gt; |
| `created_time`&lt;br&gt;&lt;br&gt;*datetime* | When was the Lift study created&lt;br&gt; |
| `description`&lt;br&gt;&lt;br&gt;*string* | Description&lt;br&gt;&lt;br&gt;&lt;br&gt;**[default]**&lt;br&gt; |
| `end_time`&lt;br&gt;&lt;br&gt;*datetime* | End time&lt;br&gt;&lt;br&gt;&lt;br&gt;**[default]**&lt;br&gt; |
| `name`&lt;br&gt;&lt;br&gt;*string* | Name of the Lift study&lt;br&gt;&lt;br&gt;&lt;br&gt;**[default]**&lt;br&gt; |
| `observation_end_time`&lt;br&gt;&lt;br&gt;*datetime* | Observation end time&lt;br&gt; |
| `results_first_available_date`&lt;br&gt;&lt;br&gt;*string* | When results for at least one objective of the study are available&lt;br&gt; |
| `start_time`&lt;br&gt;&lt;br&gt;*datetime* | Start time&lt;br&gt;&lt;br&gt;&lt;br&gt;**[default]**&lt;br&gt; |
| `type`&lt;br&gt;&lt;br&gt;*string* | The type of study, either audience segmentation or lift.&lt;br&gt; |
| `updated_by`&lt;br&gt;&lt;br&gt;*[User](https://developers.facebook.com/docs/graph-api/reference/user)* | Updated by&lt;br&gt; |
| `updated_time`&lt;br&gt;&lt;br&gt;*datetime* | Updated time&lt;br&gt; |

#### Edges

| Edge | Description |
| --- | --- |
| [`cells`](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-study/cells)&lt;br&gt;&lt;br&gt;*Edge&lt;AdStudyCell&gt;* | The cells which are part of the objective&lt;br&gt; |
| [`objectives`](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-study/objectives)&lt;br&gt;&lt;br&gt;*Edge&lt;AdStudyObjective&gt;* | The objectives which are part of the objective&lt;br&gt; |

#### Error Codes

| Error Code | Description |
| --- | --- |
| 368 | The action attempted has been deemed abusive or is otherwise disallowed |
| 100 | Invalid parameter |
| 190 | Invalid OAuth 2.0 Access Token |

## Creating

### Requirements &#123;#remarks&#125;

- `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`.

### /&#123;user_id&#125;/ad_studies
You can make a POST request to *ad_studies* edge from the following paths:

- [/&#123;user_id&#125;/ad_studies](https://developers.facebook.com/docs/graph-api/reference/user/ad_studies)

When posting to this edge, an [AdStudy](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-study) will be created.

#### Parameters

| Parameter | Description |
| --- | --- |
| `cells`&lt;br&gt;&lt;br&gt;*list&lt;Object&gt;* | A shape to describe the cells of the study&lt;br&gt;&lt;br&gt;&lt;br&gt;`description` *string*&lt;br&gt;&lt;br&gt;`id` *int64*&lt;br&gt;&lt;br&gt;`name` *string*&lt;br&gt;&lt;br&gt;`creation_template` *enum &#123;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&#125;*&lt;br&gt;&lt;br&gt;`adaccounts` *list&lt;int64&gt;*&lt;br&gt;&lt;br&gt;`ads` *list&lt;numeric string or integer&gt;*&lt;br&gt;&lt;br&gt;`adsets` *list&lt;numeric string or integer&gt;*&lt;br&gt;&lt;br&gt;`campaigns` *list&lt;numeric string or integer&gt;*&lt;br&gt;&lt;br&gt;`control_percentage` *float with at most two digits after decimal point*&lt;br&gt;&lt;br&gt;`treatment_percentage` *float with at most two digits after decimal point* |
| `client_business`&lt;br&gt;&lt;br&gt;*numeric string or integer* | Business associated with study&lt;br&gt; |
| `confidence_level`&lt;br&gt;&lt;br&gt;*float* | Confidence level used in power calculation and final report&lt;br&gt; |
| `cooldown_start_time`&lt;br&gt;&lt;br&gt;*integer* | The beginning of the pre measurement cooldown period. This period ends when the study period starts.&lt;br&gt; |
| `creative_test_config`&lt;br&gt;&lt;br&gt;*JSON object* | (Optional) Configuration for launching a 2-5 cell creative test. Specify either daily_budget or lifetime_budget_percentage to set the budget allocation for the study across the cells&#039; ads. Study &quot;type&quot; field must be defined as SPLIT_TEST_V2 when creative_test_config is included in the request.&lt;br&gt; |
| `description`&lt;br&gt;&lt;br&gt;*string* | A brief description about the purpose of the study.&lt;br&gt; |
| `end_time`&lt;br&gt;&lt;br&gt;*integer* | The time when the study period ends.&lt;br&gt; |
| `name`&lt;br&gt;&lt;br&gt;*string* | The name of the study.&lt;br&gt; |
| `objectives`&lt;br&gt;&lt;br&gt;*list&lt;Object&gt;* | A vector of objects describing the objectives assigned to this study&lt;br&gt;&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;&lt;br&gt;`is_primary` *boolean*&lt;br&gt;&lt;br&gt;`name` *string*&lt;br&gt;&lt;br&gt;`type` *enum &#123;SALES, NONSALES, MAE, TELCO, FTL, MAI, PARTNER, BRANDLIFT, BRAND, MPC_CONVERSION, CONVERSIONS&#125;*&lt;br&gt;&lt;br&gt;`offsite_datasets` *list&lt;JSON or object-like arrays&gt;*&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;**[required]**&lt;br&gt;&lt;br&gt;&lt;br&gt;`event_names` *list&lt;string&gt;*&lt;br&gt;&lt;br&gt;`adspixels` *list&lt;JSON or object-like arrays&gt;*&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;**[required]**&lt;br&gt;&lt;br&gt;&lt;br&gt;`event_names` *list&lt;string&gt;*&lt;br&gt;&lt;br&gt;`customconversions` *list&lt;JSON or object-like arrays&gt;*&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;**[required]**&lt;br&gt;&lt;br&gt;&lt;br&gt;`event_names` *list&lt;string&gt;*&lt;br&gt;&lt;br&gt;`applications` *list&lt;JSON or object-like arrays&gt;*&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;**[required]**&lt;br&gt;&lt;br&gt;&lt;br&gt;`event_names` *list&lt;string&gt;*&lt;br&gt;&lt;br&gt;`offline_conversion_data_sets` *list&lt;JSON or object-like arrays&gt;*&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;**[required]**&lt;br&gt;&lt;br&gt;&lt;br&gt;`event_names` *list&lt;string&gt;*&lt;br&gt;&lt;br&gt;`product_sets` *list&lt;JSON or object-like arrays&gt;*&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;**[required]**&lt;br&gt;&lt;br&gt;&lt;br&gt;`event_names` *list&lt;string&gt;*&lt;br&gt;&lt;br&gt;`product_catalogs` *list&lt;JSON or object-like arrays&gt;*&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;**[required]**&lt;br&gt;&lt;br&gt;&lt;br&gt;`event_names` *list&lt;string&gt;* |
| `observation_end_time`&lt;br&gt;&lt;br&gt;*integer* | The end of the observation period for this study, this period starts when the study period ends.&lt;br&gt; |
| `start_time`&lt;br&gt;&lt;br&gt;*integer* | The time when the study period starts.&lt;br&gt; |
| `type`&lt;br&gt;&lt;br&gt;*enum &#123;LIFT, SPLIT_TEST, CONTINUOUS_LIFT_CONFIG, GEO_LIFT, BACKEND_AB_TESTING, CREATIVE_SPEND_ENFORCEMENT, PORTFOLIO_OPTIMIZER, VERSION_CONTROL&#125;* | The type of ad study, either SPLIT_TEST or LIFT.&lt;br&gt; |
| `viewers`&lt;br&gt;&lt;br&gt;*list&lt;int&gt;* | The list of people who this study has been shared with.&lt;br&gt; |

#### Return Type

This endpoint supports [read-after-write](https://developers.facebook.com/docs/graph-api/overview#read-after-write) and will read the node represented by *id* in the return type.

```
Struct  &#123;
id: numeric string,
cell_ids:  List  [numeric string],
objective_ids:  List  [numeric string],
&#125;
```

#### Error Codes

| Error Code | Description |
| --- | --- |
| 100 | Invalid parameter |
| 200 | Permissions error |

### /&#123;business_id&#125;/ad_studies
You can make a POST request to *ad_studies* edge from the following paths:

- [/&#123;business_id&#125;/ad_studies](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/business/ad_studies)

When posting to this edge, an [AdStudy](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-study) will be created.

#### Parameters

| Parameter | Description |
| --- | --- |
| `cells`&lt;br&gt;&lt;br&gt;*list&lt;Object&gt;* | Describes the cells in the study.&lt;br&gt;&lt;br&gt;**[required]**&lt;br&gt;&lt;br&gt;&lt;br&gt;`description` *string*&lt;br&gt;&lt;br&gt;`id` *int64*&lt;br&gt;&lt;br&gt;`name` *string*&lt;br&gt;&lt;br&gt;`creation_template` *enum &#123;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&#125;*&lt;br&gt;&lt;br&gt;`adaccounts` *list&lt;int64&gt;*&lt;br&gt;&lt;br&gt;`ads` *list&lt;numeric string or integer&gt;*&lt;br&gt;&lt;br&gt;`adsets` *list&lt;numeric string or integer&gt;*&lt;br&gt;&lt;br&gt;`campaigns` *list&lt;numeric string or integer&gt;*&lt;br&gt;&lt;br&gt;`control_percentage` *float with at most two digits after decimal point*&lt;br&gt;&lt;br&gt;`treatment_percentage` *float with at most two digits after decimal point* |
| `client_business`&lt;br&gt;&lt;br&gt;*numeric string or integer* | Business associated with the study.&lt;br&gt; |
| `confidence_level`&lt;br&gt;&lt;br&gt;*float* | Confidence level used in power calculations and final study report.&lt;br&gt; |
| `cooldown_start_time`&lt;br&gt;&lt;br&gt;*integer* | Start of the pre-measurement cool-down period. This period ends when the study period starts.&lt;br&gt; |
| `creative_test_config`&lt;br&gt;&lt;br&gt;*JSON object* | (Optional) Configuration for launching a 2-5 cell creative test. Specify either daily_budget or lifetime_budget_percentage to set the budget allocation for the study across the cells&#039; ads. The study&#039;s &quot;type&quot; field must also be defined as SPLIT_TEST_V2 when creative_test_config is included in the request.&lt;br&gt; |
| `description`&lt;br&gt;&lt;br&gt;*string* | The purpose of the study.&lt;br&gt; |
| `end_time`&lt;br&gt;&lt;br&gt;*integer* | Time when the study period ends.&lt;br&gt;&lt;br&gt;**[required]**&lt;br&gt; |
| `name`&lt;br&gt;&lt;br&gt;*string* | Name of the study.&lt;br&gt;&lt;br&gt;**[required]**&lt;br&gt; |
| `objectives`&lt;br&gt;&lt;br&gt;*list&lt;Object&gt;* | A vector of objects describing the objectives assigned to this study.&lt;br&gt;&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;&lt;br&gt;`is_primary` *boolean*&lt;br&gt;&lt;br&gt;`name` *string*&lt;br&gt;&lt;br&gt;`type` *enum &#123;SALES, NONSALES, MAE, TELCO, FTL, MAI, PARTNER, BRANDLIFT, BRAND, MPC_CONVERSION, CONVERSIONS&#125;*&lt;br&gt;&lt;br&gt;`offsite_datasets` *list&lt;JSON or object-like arrays&gt;*&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;**[required]**&lt;br&gt;&lt;br&gt;&lt;br&gt;`event_names` *list&lt;string&gt;*&lt;br&gt;&lt;br&gt;`adspixels` *list&lt;JSON or object-like arrays&gt;*&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;**[required]**&lt;br&gt;&lt;br&gt;&lt;br&gt;`event_names` *list&lt;string&gt;*&lt;br&gt;&lt;br&gt;`customconversions` *list&lt;JSON or object-like arrays&gt;*&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;**[required]**&lt;br&gt;&lt;br&gt;&lt;br&gt;`event_names` *list&lt;string&gt;*&lt;br&gt;&lt;br&gt;`applications` *list&lt;JSON or object-like arrays&gt;*&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;**[required]**&lt;br&gt;&lt;br&gt;&lt;br&gt;`event_names` *list&lt;string&gt;*&lt;br&gt;&lt;br&gt;`offline_conversion_data_sets` *list&lt;JSON or object-like arrays&gt;*&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;**[required]**&lt;br&gt;&lt;br&gt;&lt;br&gt;`event_names` *list&lt;string&gt;*&lt;br&gt;&lt;br&gt;`product_sets` *list&lt;JSON or object-like arrays&gt;*&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;**[required]**&lt;br&gt;&lt;br&gt;&lt;br&gt;`event_names` *list&lt;string&gt;*&lt;br&gt;&lt;br&gt;`product_catalogs` *list&lt;JSON or object-like arrays&gt;*&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;**[required]**&lt;br&gt;&lt;br&gt;&lt;br&gt;`event_names` *list&lt;string&gt;* |
| `observation_end_time`&lt;br&gt;&lt;br&gt;*integer* | The end of the observation period for this study. This period starts when the study period ends.&lt;br&gt; |
| `start_time`&lt;br&gt;&lt;br&gt;*integer* | The time when the study period starts.&lt;br&gt;&lt;br&gt;**[required]**&lt;br&gt; |
| `type`&lt;br&gt;&lt;br&gt;*enum &#123;LIFT, SPLIT_TEST, CONTINUOUS_LIFT_CONFIG, GEO_LIFT, BACKEND_AB_TESTING, CREATIVE_SPEND_ENFORCEMENT, PORTFOLIO_OPTIMIZER, VERSION_CONTROL&#125;* | The type of ad study, such as `SPLIT_TEST` or `LIFT`.&lt;br&gt; |
| `viewers`&lt;br&gt;&lt;br&gt;*list&lt;int&gt;* | This study is shared with these people.&lt;br&gt; |

#### Return Type

This endpoint supports [read-after-write](https://developers.facebook.com/docs/graph-api/overview#read-after-write) and will read the node represented by *id* in the return type.

```
Struct  &#123;
id: numeric string,
&#125;
```

#### Error Codes

| Error Code | Description |
| --- | --- |
| 100 | Invalid parameter |
| 200 | Permissions error |

## Updating

To update study fields:

### cURL
```
curl \
-F &#039;name=&quot;new name&quot;&#039; \
-F &#039;end_time=1437004800&#039; \
-F &#039;access_token=&lt;ACCESS_TOKEN&gt;&#039; \
https://graph.facebook.com/&lt;API_VERSION&gt;/&lt;AD_STUDY_ID&gt;
```

Add a cell an existing study and change `treatment_percentage` of all the cells:

### cURL
```
curl \
-F &#039;cells=[&#123;id:&lt;CELL_ID&gt;,treatment_percentage:50&#125;,&#123;id:&lt;CELL_ID&gt;,treatment_percentage:10&#125;,&#123;name:&quot;Group C&quot;,treatment_percentage:20,adsets:[&lt;AD_SET_ID&gt;]&#125;]&#039; \
-F &#039;access_token=&lt;ACCESS_TOKEN&gt;&#039; \
https://graph.facebook.com/&lt;API_VERSION&gt;/&lt;AD_STUDY_ID&gt;
```

### Limitations &#123;#remarks&#125;

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.

### /&#123;ad_study_id&#125;
You can update an [AdStudy](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-study) by making a POST request to [/&#123;ad_study_id&#125;](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-study).

#### Parameters

| Parameter | Description |
| --- | --- |
| `cells`&lt;br&gt;&lt;br&gt;*list&lt;Object&gt;* | A shape to describe the cells of the study&lt;br&gt;&lt;br&gt;&lt;br&gt;`description` *string*&lt;br&gt;&lt;br&gt;`id` *int64*&lt;br&gt;&lt;br&gt;`name` *string*&lt;br&gt;&lt;br&gt;`creation_template` *enum &#123;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&#125;*&lt;br&gt;&lt;br&gt;`adaccounts` *list&lt;int64&gt;*&lt;br&gt;&lt;br&gt;`ads` *list&lt;numeric string or integer&gt;*&lt;br&gt;&lt;br&gt;`adsets` *list&lt;numeric string or integer&gt;*&lt;br&gt;&lt;br&gt;`campaigns` *list&lt;numeric string or integer&gt;*&lt;br&gt;&lt;br&gt;`control_percentage` *float with at most two digits after decimal point*&lt;br&gt;&lt;br&gt;`treatment_percentage` *float with at most two digits after decimal point* |
| `client_business`&lt;br&gt;&lt;br&gt;*numeric string or integer* | Business associated with study&lt;br&gt; |
| `confidence_level`&lt;br&gt;&lt;br&gt;*float* | Confidence level used in power calculation and final report&lt;br&gt; |
| `cooldown_start_time`&lt;br&gt;&lt;br&gt;*integer* | The beginning of the pre measurement cooldown period. This period ends when the study period starts.&lt;br&gt; |
| `creative_test_config`&lt;br&gt;&lt;br&gt;*JSON object* | (Optional) Configuration for launching a 2-5 cell creative test. Specify either daily_budget or lifetime_budget_percentage to set the budget allocation for the study across the cells&#039; ads. Must be used with study type SPLIT_TEST_V2&lt;br&gt; |
| `description`&lt;br&gt;&lt;br&gt;*string* | A brief description about the purpose of the study.&lt;br&gt; |
| `end_time`&lt;br&gt;&lt;br&gt;*integer* | The time when the study period ends.&lt;br&gt; |
| `name`&lt;br&gt;&lt;br&gt;*string* | The name of the study.&lt;br&gt; |
| `objectives`&lt;br&gt;&lt;br&gt;*list&lt;Object&gt;* | A vector of objects describing the objectives assigned to this study&lt;br&gt;&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;&lt;br&gt;`is_primary` *boolean*&lt;br&gt;&lt;br&gt;`name` *string*&lt;br&gt;&lt;br&gt;`type` *enum &#123;SALES, NONSALES, MAE, TELCO, FTL, MAI, PARTNER, BRANDLIFT, BRAND, MPC_CONVERSION, CONVERSIONS&#125;*&lt;br&gt;&lt;br&gt;`offsite_datasets` *list&lt;JSON or object-like arrays&gt;*&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;**[required]**&lt;br&gt;&lt;br&gt;&lt;br&gt;`event_names` *list&lt;string&gt;*&lt;br&gt;&lt;br&gt;`adspixels` *list&lt;JSON or object-like arrays&gt;*&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;**[required]**&lt;br&gt;&lt;br&gt;&lt;br&gt;`event_names` *list&lt;string&gt;*&lt;br&gt;&lt;br&gt;`customconversions` *list&lt;JSON or object-like arrays&gt;*&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;**[required]**&lt;br&gt;&lt;br&gt;&lt;br&gt;`event_names` *list&lt;string&gt;*&lt;br&gt;&lt;br&gt;`applications` *list&lt;JSON or object-like arrays&gt;*&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;**[required]**&lt;br&gt;&lt;br&gt;&lt;br&gt;`event_names` *list&lt;string&gt;*&lt;br&gt;&lt;br&gt;`offline_conversion_data_sets` *list&lt;JSON or object-like arrays&gt;*&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;**[required]**&lt;br&gt;&lt;br&gt;&lt;br&gt;`event_names` *list&lt;string&gt;*&lt;br&gt;&lt;br&gt;`product_sets` *list&lt;JSON or object-like arrays&gt;*&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;**[required]**&lt;br&gt;&lt;br&gt;&lt;br&gt;`event_names` *list&lt;string&gt;*&lt;br&gt;&lt;br&gt;`product_catalogs` *list&lt;JSON or object-like arrays&gt;*&lt;br&gt;&lt;br&gt;`id` *numeric string or integer*&lt;br&gt;**[required]**&lt;br&gt;&lt;br&gt;&lt;br&gt;`event_names` *list&lt;string&gt;* |
| `observation_end_time`&lt;br&gt;&lt;br&gt;*integer* | The end of the observation period for this study, this period starts when the study period ends.&lt;br&gt; |
| `start_time`&lt;br&gt;&lt;br&gt;*integer* | The time when the study period starts.&lt;br&gt; |
| `type`&lt;br&gt;&lt;br&gt;*enum &#123;LIFT, SPLIT_TEST, CONTINUOUS_LIFT_CONFIG, GEO_LIFT, BACKEND_AB_TESTING, CREATIVE_SPEND_ENFORCEMENT, PORTFOLIO_OPTIMIZER, VERSION_CONTROL&#125;* | A type of the study.&lt;br&gt; |
| `viewers`&lt;br&gt;&lt;br&gt;*list&lt;int&gt;* | The list of people who this study has been shared with.&lt;br&gt; |

#### Return Type

This endpoint supports [read-after-write](https://developers.facebook.com/docs/graph-api/overview#read-after-write) and will read the node to which you POSTed.

```
Struct  &#123;
success: bool,
cell_ids:  List  [numeric string],
objective_ids:  List  [numeric string],
&#125;
```

#### Error Codes

| Error Code | Description |
| --- | --- |
| 100 | Invalid parameter |
| 200 | Permissions error |

## Deleting

To delete a study:

```
curl -X DELETE
&quot;https://graph.facebook.com/&lt;API_VERSION&gt;/&lt;AD_STUDY_ID&gt;&quot;
```

You can&#039;t perform this operation on this endpoint.


---

Full documentation index for this product: https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/llms.txt