AB Tests
ab-tests

AB Tests

Run in Postman ❯ 

GET accounts/:account_id/ab_tests

Retrieve details for some or all A/B tests.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/ab_tests

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
ab_test_ids
optional

Scope the response to just the desired A/B Tests by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: hr7l0
count
optional

Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
optional

Specifies a cursor to get the next page of results. See Pagination for more information.

Type: string

Example: 8x7v00oow
live_during
optional

Scope the response to A/B Tests that were or that will be live during the given date range. This returns A/B Tests whose start and end times overlap—partially or fully—with the given date range.

Specify values as comma-separated dates, expressed in ISO 8601. The earlier date should be specified first.

Type: string

Example: 2020-11-01T08:00:00Z,2020-12-01T08:00:00Z
q
optional

An optional query to scope resource by name. Omit this parameter to retrieve all.

Type: string

Min, Max length: 1, 80
sort_by
optional

Sorts by supported attribute in ascending or descending order. See Sorting for more information.

Type: string

Example: created_at-asc
status
optional

Scope the response to A/B Tests with the desired status.

Type: enum

Possible values: COMPLETED, LIVE, SCHEDULED
user_id
optional

Scope the response to A/B Tests created by the specified user ID.

Note: Cannot be specified at the same time as username.

Type: long

Example: `756201191646691328.
username
optional

Scope the response to A/B Tests created by the specified username. Do not include the leading "@" symbol.

Note: Cannot be specified at the same time as user_id.

Type: string

Example: `apimctestface.
with_deleted
optional

Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t"
    }
  },
  "data": [
    {
      "created_at": "2022-05-25T00:00:00Z",
      "created_by": {
        "user_id": "756201191646691328",
        "username": "apimctestface"
      },
      "deleted": false,
      "description": "documentation example",
      "end_time": "2022-05-30T01:00:00Z",
      "entities": [
        {
          "id": "p1bcx",
          "account_id": "18ce54d4x5t"
        },
        {
          "id": "p1bcy",
          "account_id": "18ce54d4x5t"
        }
      ],
      "entity_type": "CAMPAIGN",
      "id": "hr7l0",
      "name": "first AB test",
      "start_time": "2022-05-25T01:00:00Z",
      "status": "SCHEDULED",
      "user_groups": [
        {
          "id": "p1bcx",
          "name": "first group",
          "description": null,
          "size": "50.0",
          "entity_ids": [
            "f2qcw",
            "f2tht"
          ]
        },
        {
          "id": "p1bcy",
          "name": "second group",
          "description": "second AB test group",
          "size": "50.0",
          "entity_ids": [
            "f2rqi",
            "f2tws"
          ]
        }
      ],
      "updated_at": "2022-05-25T00:00:00Z",
      "updated_by": {
        "user_id": "756201191646691328",
        "username": "apimctestface"
      }
    }
  ],
  "next_cursor": null
}

POST accounts/:account_id/ab_tests

Create a new A/B Test.

All parameters are sent in the request body and a Content-Type of application/json is required.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/ab_tests

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
end_time
required

The time, expressed in ISO 8601, that the A/B Test will end.

Type: string

Example: 2020-10-02T00:00:00Z
entity_type
required

The type of entity to be used for user group splits.

Type: enum

Possible values: CAMPAIGN, LINE_ITEM
start_time
required

The time, expressed in ISO 8601, that the A/B Test will begin.

Type: string

Example: 2022-05-30T00:00:00Z
user_groups
required

Describes the user groups. More information in the table below. Between 2 and 30 user groups may be specified.

Type: array of objects
description
optional

The description for the A/B Test. Maximum length: 1,024 characters.

Type: string

Example: documentation example
name
optional

The name for the A/B Test. Maximum length: 255 characters.

Type: string

Example: first AB test

User Groups

Name Description
entity_ids
required

An array of entity IDs.

Note: Entities can only be associated with one A/B Test.

Type: array

Example: ["dxi0l", "e66bl"]
size
required

The percentage of users to allocate to this user group. This is a numeric value represented as a string with at most two digits after the decimal point. For example, represent 40% as either: 40, 40.0, or 40.00.

Note: The size values across objects must add up to 100.00.

Type: array

Min, Max: 1.00, 99.00
description
optional

The description for the user group. Maximum length: 1,024 characters.

Type: string

Example: second AB test group
name
optional

The name for the user group. Maximum length: 255 characters.

Type: string

Example: first group

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests -d '{"end_time": "2022-05-30T01:00:00Z", "entity_type" : "CAMPAIGN", "start_time": "2022-05-25T01:00:00Z", "user_groups": [{"entity_ids": ["f2qcw", "f2tht"], "size": "50.00", "name": "first group"},{"entity_ids": ["f2rqi", "f2tws"], "size": "50.00", "name": "second group", "description": "second AB test group"}], "name": "first AB test", "description": "documentation example"}'

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "end_time": "2022-05-30T01:00:00Z",
      "entity_type": "CAMPAIGN",
      "start_time": "2022-05-25T01:00:00Z",
      "user_groups": [
        {
          "entity_ids": [
            "f2qcw",
            "f2tht"
          ],
          "size": "50.0",
          "name": "first group"
        },
        {
          "entity_ids": [
            "f2rqi",
            "f2tws"
          ],
          "size": "50.0",
          "name": "second group",
          "description": "second AB test group"
        }
      ],
      "name": "first AB test",
      "description": "documentation example"
    }
  },
  "data": {
    "created_at": "2022-05-25T00:00:00Z",
    "created_by": {
      "user_id": "756201191646691328",
      "username": "apimctestface"
    },
    "deleted": false,
    "description": "documentation example",
    "end_time": "2022-05-30T01:00:00Z",
    "entities": [
      {
        "id": "p1bcx",
        "account_id": "18ce54d4x5t"
      },
      {
        "id": "p1bcy",
        "account_id": "18ce54d4x5t"
      }
    ],
    "entity_type": "CAMPAIGN",
    "id": "hr7l0",
    "name": "first AB test",
    "start_time": "2022-05-25T01:00:00Z",
    "status": "SCHEDULED",
    "user_groups": [
      {
        "id": "p1bcx",
        "name": "first group",
        "description": null,
        "size": "50.0",
        "entity_ids": [
          "f2qcw",
          "f2tht"
        ]
      },
      {
        "id": "p1bcy",
        "name": "second group",
        "description": "second AB test group",
        "size": "50.0",
        "entity_ids": [
          "f2rqi",
          "f2tws"
        ]
      }
    ],
    "updated_at": "2022-05-25T00:00:00Z",
    "updated_by": {
      "user_id": "756201191646691328",
      "username": "apimctestface"
    }
  }
}

PUT accounts/:account_id/ab_tests/:ab_test_id

Update the specified A/B Test.

All parameters are sent in the request body and a Content-Type of application/json is required.

This endpoint supports partial JSON with object IDs. The following principles apply:

  • To add or remove objects or elements, pass in the entire array (and its substructures); this is a replacement operation
    • Think of this as recreating the array
  • Otherwise, modify (change, add, remove) existing fields by referencing key names or IDs
    • To remove a field, set its value to null
    • Fields that are not passed in are not modified

In general, A/B Tests can only be updated while the status is SCHEDULED. There is one exception: it's possible to update the A/B Test's end_time while it's LIVE.

Resource URL

https://ads-api.x.com/12/accounts/18ce54d4x5t/:ab_test_id

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
ab_test_id
required

A reference to the A/B Test you are operating with in the request.

Type: string

Example: hr7l0
description
optional

The description for the A/B Test. Maximum length: 1,024 characters.

Note: Can only be updated while the A/B Test status is SCHEDULED.

Type: string

Example: documentation example
end_time
optional

The time, expressed in ISO 8601, that the A/B Test will end.

Note: Can only be updated while the A/B Test status is SCHEDULED or LIVE.

Type: string

Example: 2020-10-02T00:00:00Z
name
optional

The name for the A/B Test. Maximum length: 255 characters.

Note: Can only be updated while the A/B Test status is SCHEDULED.

Type: string

Example: first AB test
start_time
optional

The time, expressed in ISO 8601, that the A/B Test will begin.

Note: Can only be updated while the A/B Test status is SCHEDULED.

Type: string

Example: 2022-05-30T00:00:00Z
user_groups
required

Describes the user groups. More information in the table below.

Note: Can only be updated while the A/B Test status is SCHEDULED.

Type: array of objects

User Groups

Name Description
id
sometimes required

A reference to the user group object you are operating with in the request.

Note: Required when modifying (changing, adding, or removing) user group object fields.

Note: Do not specify an ID when adding or removing entire user group objects.

Type: string

Example: p1bcx
description
optional

The description for the user group. Maximum length: 1,024 characters.

Note: Unset (remove) by specifying the field with a null value.

Type: string

Example: second AB test group
entity_ids
optional

An array of entity IDs.

Note: This is a replacement operation. It overwrites whatever was previously set.

Note: Entities can only be associated with one A/B Test.

Type: array

Example: ["dxi0l", "e66bl"]
name
optional

The name for the user group. Maximum length: 255 characters.

Note: Unset (remove) by specifying the field with a null value.

Type: string

Example: first group
size
optional

The percentage of users to allocate to this user group. This is a numeric value represented as a string with at most two digits after the decimal point. For example, represent 40% as either: 40, 40.0, or 40.00.

Note: The size values across objects must add up to 100.00.

Type: string

Min, Max: 1.00, 99.00

Example Request

This request makes the following modifications.

  1. Removes the A/B Test description
  2. Changes the end time
  3. Adds a description to the first user group
  4. Changes the percentage of users in each user group
  5. Add an entity ID (f2syz) to the second user group

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests/hr7l0 -d '{"description": null, "end_time": "2022-06-01T01:00:00Z", "user_groups": [{"id": "p1bcx", "description": "first AB test group", "size": "60.00"},{"id": "p1bcy", "size": "40.00", "entity_ids": ["f2rqi", "f2tws", "f2syz"]}]}'

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "ab_test_id": "hr7l0",
      "description": null,
      "end_time": "2022-06-01T01:00:00Z",
      "user_groups": [
        {
          "id": "p1bcx",
          "description": "first AB test group",
          "size": "60.0"
        },
        {
          "id": "p1bcy",
          "size": "40.0",
          "entity_ids": [
            "f2rqi",
            "f2tws",
            "f2syz"
          ]
        }
      ]
    }
  },
  "data": {
    "created_at": "2020-05-25T00:00:00Z",
    "created_by": {
      "user_id": "756201191646691328",
      "username": "apimctestface"
    },
    "deleted": false,
    "description": null,
    "end_time": "2022-06-01T01:00:00Z",
    "entities": [
      {
        "id": "p1bcx",
        "account_id": "18ce54d4x5t"
      },
      {
        "id": "p1bcy",
        "account_id": "18ce54d4x5t"
      }
    ],
    "entity_type": "CAMPAIGN",
    "id": "hr7l0",
    "name": "first AB test",
    "start_time": "2022-05-25T01:00:00Z",
    "status": "SCHEDULED",
    "user_groups": [
      {
        "id": "p1bcx",
        "name": "first group",
        "description": "first AB test group",
        "size": "60.0",
        "entity_ids": [
          "f2qcw",
          "f2tht"
        ]
      },
      {
        "id": "p1bcy",
        "name": "second group",
        "description": "second AB test group",
        "size": "40.0",
        "entity_ids": [
          "f2rqi",
          "f2tws",
          "f2syz"
        ]
      }
    ],
    "updated_at": "2022-05-25T00:17:23Z",
    "updated_by": {
      "user_id": "756201191646691328",
      "username": "apimctestface"
    }
  }
}

DELETE accounts/:account_id/ab_tests/:ab_test_id

Delete the specified A/B Test.

Note: Deleting an A/B Test is not reversible and subsequent attempts to delete the resource will return HTTP 404.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/ab_tests/:ab_test_id

Parameters

Name Description
ab_test_id
required

A reference to the A/B Test you are operating with in the request.

Type: string

Example: hr7l0

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests/hr7l0

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "ab_test_id": "hr7l0"
    }
  },
  "data": {
    "created_at": "2022-05-25T00:00:00Z",
    "created_by": {
      "user_id": "756201191646691328",
      "username": "apimctestface"
    },
    "deleted": true,
    "description": null,
    "end_time": "2022-06-01T01:00:00Z",
    "entities": [
      {
        "id": "p1bcx",
        "account_id": "18ce54d4x5t"
      },
      {
        "id": "p1bcy",
        "account_id": "18ce54d4x5t"
      }
    ],
    "entity_type": "CAMPAIGN",
    "id": "hr7l0",
    "name": "first AB test",
    "start_time": "2022-05-25T01:00:00Z",
    "status": "SCHEDULED",
    "user_groups": [
      {
        "id": "p1bcx",
        "name": "first group",
        "description": "first AB test group",
        "size": "60.0",
        "entity_ids": [
          "f2qcw",
          "f2tht"
        ]
      },
      {
        "id": "p1bcy",
        "name": "second group",
        "description": "second AB test group",
        "size": "40.0",
        "entity_ids": [
          "f2rqi",
          "f2tws",
          "f2syz"
        ]
      }
    ],
    "updated_at": "2022-06-02T00:18:31Z",
    "updated_by": {
      "user_id": "756201191646691328",
      "username": "apimctestface"
    }
  }
}