# A/B Testing API for Reels and Videos



This document shows you how to create an A/B test for reels and videos published on a Facebook Page.

You can run up to 50 tests at once with a minimum of 2 posts and a maximum of 4 posts per test.

## Before You Start

You need the following:

* The ID for the Facebook Page where the test is being conducted
* A Page access token requested from a user who can perform the `CREATE_CONTENT` task on the Page
* The user must grant your app the following permissions using Facebook Login:
    * `pages_manage_engagement`
    * `pages_show_list`
    * `pages_manage_posts`
    * `pages_read_engagement`
    * `pages_read_user_content`
* The IDs for the reels or videos, in draft status, that you want to compare
    * The reels or videos must be uploaded to Meta servers but not yet published

### Limitations

* An A/B test can only be created on Facebook Pages
* A reel or video that has already been published can not be used in an A/B test
* A reel or video cannot be used in multiple A/B tests

## Create an A/B Test

To create an A/B test, send a `POST` request to the `/`***`PAGE`***`/ab_tests` endpoint, where ***`PAGE`*** is the ID for the Facebook Page, and include the following parameters:

_Required_

* `control_video_id` – the ID for the video that, in the event of a tie, will be selected as the winning video
* `description` – the description for your experiment
* `experiment_video_ids` – the IDs for the videos you are comparing
* `name` – the name for your experiment
* `optimization_goal` – the goal of your experiment must be one of the following:

* `AVG_TIME_WATCHED`
* `COMMENTS`
* `IMPRESSIONS`

* `IMPRESSIONS_UNIQUE`
* `LINK_CLICKS`
* `REACTIONS`

* `REELS_PLAYS`
* `SHARES`
* `VIDEO_VIEWS_60S`

_Optional_

* `duration` – the length of time, in seconds, to run the test
    * minimum duration is 30 minutes (1800 seconds)
    * maximum duration is 1 week (604800 seconds)
* `scheduled_experiment_timestamp` – the UNIX timestamp for the time to start the test,
    * default to the time you create the test

### Example Request

_Formatted for readability. Replace bold, italics values, such as **`PAGE`**, with your values._

```curl
curl -X POST "https://graph.facebook.com/v25.0/YOUR_PAGE_ID/ab_tests"
     -H "Content-type: application/json"
     -d '{
           "name": "YOUR_TEST_NAME",
           "description": "YOUR_TEST_DESCRIPTION",
           "optimization_goal": "YOUR_OPTIMIZATION_GOAL",
           "experiment_video_ids": [YOUR_EXPERIMENTAL_VIDEO_ID_1, YOUR_EXPERIMENTAL_VIDEO_ID_2],
           "control_video_id": YOUR_EXPERIMENTAL_VIDEO_ID_1_AS_CONTROL
,           "duration": 1800,
}'
```

On success your app will receive a JSON response with the ID for your A/B test.

```json
{
  "id": "AB_TEST_ID"
}
```

## Get A/B Test Results

You can get data about an A/B test during the experiment or after it has concluded.

### For a specific test

To get data about a specific A/B test, send a `GET` request to the ***`/AB_TEST_ID`*** enpoint where ***`AB_TEST_ID`*** is the ID for the test you are interested in.

```json
curl -i -X GET "https://graph.facebook.com/AB_TEST_ID"
```

On success your app will receive a JSON response with details about the experiment such as the name, goal, IDs for the videos, published status, videos insights for each test video, and a declaration for which video performed the best. In the example here, EXPERIMENTAL_VIDEO_ID_1 performed the best.

```json
{
  "id": YOUR_AB_TEST_ID,
  "name": "YOUR_AB_TEST_NAME",
  "description": "YOUR_AB_TEST_DESCRIPTION",
  "optimization_goal": "REELS_PLAYS",
  "experiment_video_ids": [YOUR_EXPERIMENTAL_VIDEO_ID_1, YOUR_EXPERIMENTAL_VIDEO_ID_2],
  "control_video_id": VIDEO_ID_1_AS_CONTROL,
  "publish_status": "LIVE",
  "creation_time": "1686665092",
  "updated_time": "1686665092",
  "scheduled_experiment_timestamp": "1686665092",
  "test_insights": {
      "timestamp": "1686665092",
      "videos": {
          YOUR_EXPERIMENTAL_VIDEO_ID_1: {
              "plays": 10,
              "impressions": 1,
              "fan_impressions": 1,
              "link_clicks": 1,
              "comments": 1,
              "shares": 1,
              "reactions": 1,
              "video_views_60s": 1,
              "video_views_3s": 1,
              "video_views_15s": 1,
              "avg_video_views": 1,
              "video_views": 1,
              "instream_ads_earnings": 1,
              "avg_time_watched": 1,
              "video_retention_graph": {
                  "0": 1,
                  "1": 1,
                  "2": 0.5,
                  "3": 0.2
              }
          }
          YOUR_EXPERIMENTAL_VIDEO_ID_2: {
              "plays": 5,
              "impressions": 1,
              "fan_impressions": 1,
              "link_clicks": 1,
              "comments": 0,
              "shares": 0,
              "reactions": 1,
              "video_views_60s": 1,
              "video_views_3s": 1,
              "video_views_15s": 1,
              "avg_video_views": 1,
              "video_views": 1,
              "instream_ads_earnings": 0,
              "avg_time_watched": 1,
              "video_retention_graph": {
                  "0": 1,
                  "1": 1,
                  "2": 0.5,
                  "3": 0.2
              }
          }
      },
      "declared_winning_video": YOUR_EXPERIMENTAL_VIDEO_ID_1,
  }
}
```

### For All Tests on a Page

To get a list of all A/B tests conducted on your Facebook Page, send a `GET` request to the `/***PAGE***/ab_tests` endpoint where ***`PAGE`*** is the ID for the Page you are interested in. Add the `since` and `unti` parameters to get data for tests run during a specific time period.

**Note:** When using the `since` and `until` parameters in your `GET` request, the date for `until` must be a date after the date for `since`. For example, if `since` is 2023-01-31, `until` must be after 2023-01-31. You can use both parameters, or one or the other. Date formats can be any of the following:

* `today`, `yesterday`

* Epoch timestamps (`1676057525`)

* dd mmm yyyy (`31 jan 2023`) or dd-mm-yyyy (`31-1-2023`)

```curl
curl -X GET "https://graph.facebook.com/v25.0/PAGE/ab_tests"
```

On success your app receives a JSON response with an array of test objects.

```json
{
  "data": [
  ... {AB_TEST_RESPONSE_OBJECT_1},
  ... {AB_TEST_RESPONSE_OBJECT_2},
  ... {AB_TEST_RESPONSE_OBJECT_3}
  ],
  "cursors": {
    "before":"QVFIUkxLWWtMb3BSQV91aF81NkN4c1RYczJZAQ0NQOHpQ",
    "after":"QVFIUkxLWWtMb3BSQV91aF81NkN4c1RYczJZAQ0NQOH"
  }
}
```

## Delete an A/B test

You can delete an A/B test once it has concluded.

To delete an A/B test, send a `DELETE` request to the `AB_TEST_ID` endpoint where ID is the ID for the A/B test you want to delete.

```curl
curl -X DELETE "https://graph.facebook.com/v25.0/AB_TEST_ID"
```

Note that the posts in the A/B test will not be deleted.

## References

| Endpoint | Description |
| --- | --- |
| `/page/ab_tests` | Create and read A/B tests for a specific Facebook Page |
| `/AB_TEST_ID` | A specific A/B test |

## More Resources

- [Graph API Overview](https://developers.facebook.com/docs/graph-api/overview)

– Learn more about the Graph API from Meta

- [Facebook Login](https://developers.facebook.com/documentation/facebook-login) – Learn how to implement Facebook Login to ask for permissions from a person

- [Facebook Page Tasks](https://developers.facebook.com/documentation/pages-api/overview#tasks) – Learn more about the tasks a person can perform on a Facebook Page

- [Page Access Tokens](https://developers.facebook.com/documentation/facebook-login/guides/access-tokens#pagetokens) – Learn more about Page access tokens and securing API calls

- [Paginated Results](https://developers.facebook.com/docs/graph-api/results) – Learn more about paginated results returned via the Graph API

- [Permissions](https://developers.facebook.com/docs/permissions) – Learn about permissions needed to access API endpoints

- [Upload a Video](https://developers.facebook.com/documentation/video-api/getting-started) – Learn how to upload videos to the Meta servers