Video API

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 -X POST "https://graph.facebook.com/v21.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.

{
  "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.

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.

{
  "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 -X GET "https://graph.facebook.com/v21.0/PAGE/ab_tests"

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

{ 
  "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 -X DELETE "https://graph.facebook.com/v21.0/AB_TEST_ID"

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

References

EndpointDescription

/page/ab_tests

Create and read A/B tests for a specific Facebook Page

/AB_TEST_ID

A specific A/B test

More Resources