X Ads API A/B testing: the page that stops mid-sentence
X's Ads API can split your campaigns into 30 randomized user groups. Its documentation is one page, it has no reference, and it ends mid-sentence.
The short version
- ▸A/B testing is real and it works through POST accounts/:account_id/ab_tests. It is also documented on exactly one page, which has no reference entry, and that page ends mid-sentence in the middle of the Updating section. The string ab_tests appears four times in X's entire 4.86 MB documentation corpus, all four on that one page.
- ▸Both links on that page to the endpoint reference point at developer.x.com, the retired portal. Both 307-redirect to the docs homepage, and docs.x.com has no measurement reference page to replace them. The request and response schema for A/B tests is not published anywhere.
- ▸The page contains two copies of its own overview and they disagree. One says variations are set at the campaign level and that line item support is planned 'in the future'. The other documents entity_type: LINE_ITEM as shipped. Line item support actually shipped on 16 August 2022.
- ▸There is no documented way to read a result. The Analytics namespace never mentions user groups or A/B tests, so there is no segmentation that splits stats by test cell. You create the split through the API and then diff campaign or line item stats yourself.
- ▸The Ads Manager UI is the mirror image. Since January 2023 it runs self-serve A/B tests that report a winning cell, cost per event and win probability if rerun, but it only supports creative as the test variable and caps you at 5 buckets. The API tests creative, targeting, bid type and bid unit across up to 30 groups, and declares no winner.
Quick answer
X Ads API A/B testing works, and it is more capable than the Ads Manager version: POST accounts/:account_id/ab_tests splits your audience into up to 30 randomized, mutually exclusive user groups and will test creative, targeting, bid type or bid unit. The catch is everything around it. The feature has one documentation page, no reference entry, two dead links to the reference that does not exist, and the page itself stops mid-sentence. There is also no documented way to read a result: nothing in the Analytics namespace segments stats by user group, so the API that runs the experiment will not tell you who won.
Last updated: November 2026
If you have searched for this endpoint on X (formerly Twitter) and come up with one thin page, that page is the whole thing. Here is what it says, what it does not, and how to build around the gap.
What the endpoint actually does
A/B tests on X are a layer over campaigns or line items you have already built. You do not create variants inside the test. You create two or more near-identical campaigns that differ in exactly one thing, then create a test that assigns randomized, mutually exclusive slices of your reachable audience to each one.
The object is nested: top-level fields for the test, plus a user_groups array.
| Field | Where | Rule |
|---|---|---|
start_time, end_time | test | Both must be in the future and must overlap the flight dates of the entities being split |
| duration | test | At least 1 day for non-app campaigns, at least 5 days for app-based campaigns |
entity_type | test | CAMPAIGN or LINE_ITEM |
user_groups | test | Minimum 2, maximum 30 |
size | each group | A string from 1.00 to 99.00; sizes across all groups must total 100.00 |
entity_ids | each group | The campaign ids or line item ids forming that group's pool |
name, description | test and group | Optional, on both levels |
Line item level splits carry four extra restrictions that the campaign level does not: every line item in the campaign has to be included in the test, splits must be equal, there can be at most 5 user groups, and each group may hold exactly one line item. So the headline "up to 30 groups" is a campaign-level number only. At the ad group level you get 5.
Writes go in the general Ads API write bucket, 450 requests per minute shared across POST, PUT and DELETE for the whole API. There is no ab_tests row in the rate limit chart, which is consistent with the rest of this feature's paper trail.
The documentation problem, measured
X's docs are usually generous about volume. This page is the exception, and it is worth being specific about how thin it is, because it changes how you should plan the build.
It is one page in 4.86 MB. The flattened documentation corpus X publishes at llms-full.txt was 4,858,201 bytes when we fetched it on 14 November 2026. The string ab_tests occurs four times in it: two prose links and two copies of the same twurl example, all within a 300-line stretch of one file.
It has no reference. Every other Ads API namespace pairs a narrative guide with a reference page listing parameters and example responses per endpoint. A/B testing does not. The page links twice to what should be that reference, at developer.x.com/en/docs/x-ads-api/measurement/api-reference/ab-tests, and both links 307-redirect to the docs homepage. Asking docs.x.com for x-ads-api/measurement/reference.md returns 404. The request and response schema for this endpoint is not published anywhere, which is why the example JSON blobs on the page are load-bearing. Copy them carefully.
It contradicts itself about its own main feature. The page carries two copies of its Overview. The first says variations "are set at the campaign level" and that "in the future, we plan to support variations at the line item level." The second says they "are set at either the campaign level or the ad group level" and documents entity_type: LINE_ITEM. Line item support shipped on 16 August 2022, per X's own announcement update. The future-tense copy is still live more than four years later, in the same scroll.
It ends mid-sentence. The Usage section says "the subsections below describe creating and updating A/B Tests. Reading and deleting work like they do with all other Ads API endpoints." There is a Creating section. The Updating section begins, names the PUT endpoint, and the last words on the page are "The endpoint requires that a JSON blob be sent in the request. The Content-Type". That is where the rendered page ends, immediately before the pagination footer. There is no Reading section and no Deleting section at all.
Its one example runs on a dead version. The twurl sample calls /8/accounts/18ce54d4x5t/ab_tests. By X's own version table, v8 reached end of life on 31 August 2021. Everything current is on /12/, which the rest of the Ads API docs use in 353 places. Same pattern as the step-by-step guide in X Ads API campaigns, which still calls /8/, /9/ and /5/.
Even its example disagrees with its own spec. The spec says size is "a string representation of a numeric value between 1.00 and 99.00." In the campaign-level example response, the first group has "size": "50.0" and the second has "size": 50. Send the string.
The part that is genuinely missing: results
This is the gap that matters for anyone building on it.
Search the whole documentation corpus for "user group" and every hit is on the A/B testing page. The Ads API Analytics namespace, which is where every other performance number comes from, never mentions A/B tests, user groups, test cells or splits. There is no segmentation_type for them, no ab_test_id filter, nothing.
So the API will randomize your audience, hold the groups mutually exclusive, and run the test for the window you specified. It will not tell you the outcome. You get a status of SCHEDULED and an id, and that is the extent of the feedback.
The workaround is bookkeeping, and you have to set it up before the test runs, not after:
- When you create the test, persist your own mapping of
user_group.idto theentity_idsyou put in it. The API will give those ids back on a read, but you want them in your own store keyed to the test. - Pull normal campaign or line item analytics per entity for the test window. Our X Ads API analytics guide covers the metric set and the sync versus async job split.
- Aggregate by group, then normalize. Groups with different
sizevalues reached different audience fractions, so absolute totals are not comparable without dividing through. - Hold the comparison to the test window only. X finalizes billing metrics up to three days after the event and states the final billable figure will be lower than the speculative one, so a cost-per-result comparison read on day one will move.
That is a real analysis, not a push of a button. Budget for it.
The UI runs the opposite trade
Since January 2023, X has shipped self-serve A/B testing inside Ads Manager, and the two products diverged in a way that makes the choice easy once you see it side by side.
Ads API ab_tests | Ads Manager UI | |
|---|---|---|
| Variables you can test | Creative, targeting, bid type, bid unit | Creative only: images, videos, text, CTAs |
| Groups per test | Up to 30 at campaign level, 5 at line item level | Up to 5 buckets, 5 ads each |
| Split sizes | Any sizes totalling 100.00 at campaign level | Equal buckets |
| Result reporting | None documented | Winning cell, volume of events, cost per event, win probability if rerun |
| Mid-flight data | Pull it yourself | Available during the flight |
Read that table once and the rule falls out. If your variable is creative, run the test in Ads Manager and let X compute the winner. If your variable is targeting, bid type or bid unit, the API is your only option and you own the measurement. There is no door that gives you both.
That is also the honest answer to "should I automate this?" If you are testing which X ads creative pulls better, automating ab_tests buys you a worse version of something the UI does for free. If you are testing audience definitions or bidding across a large account where clicking through Ads Manager is not viable, the API is worth the bookkeeping, and the costs you are optimizing are the ones in our X ads cost breakdown.
Before you build
Four things to settle up front, since the docs will not settle them for you.
Decide your entity level first. Switching from CAMPAIGN to LINE_ITEM is not a parameter change, it is a different set of constraints: equal splits only, 5 groups maximum, one line item per group, and all line items in the campaign conscripted into the test. Model whichever one you pick properly rather than trying to support both.
Build your campaigns to be identical except one thing. X is explicit that while you can test many variations at once, testing one at a time is what makes the difference attributable. Two campaigns that differ in creative and bid type teach you nothing about either.
Expect to discover behaviour by trying it. With no reference page and no Reading or Deleting section, the error responses are your documentation. Test against the sandbox host first, where campaigns never serve and funding instruments carry no cost.
Do not expect a verdict. The single most common wrong assumption about this endpoint is that it reports. It does not. If someone hands you a requirement that says "use the X A/B testing API to pick the winning ad," the API half of that sentence does not exist and the work is in your aggregation layer.
For the organic side of the same account, a split test is a different exercise entirely, and X-Autopilot handles that locally on your Mac with your own session and residential IP instead of a shared cloud pool, which lowers the detection surface compared with cloud schedulers rather than eliminating it. Browser automation of your own account remains a gray area X has never endorsed, and we will not claim otherwise. The Ads API is the sanctioned path, which is exactly why its gaps are worth mapping rather than guessing at.
The bottom line
POST accounts/:account_id/ab_tests is a working, capable endpoint sitting behind the thinnest documentation page in the X Ads API: no reference, two dead links to the reference, a self-contradicting overview, a code sample on a version that died in 2021, and a final sentence that never finishes. The feature's real limit is not the 30 groups. It is that nothing in the Analytics namespace knows those groups exist, so the experiment runs blind unless you build the measurement yourself. Plan that work in from the start, or run creative tests in Ads Manager and let X do the math.
Frequently asked
Answers indexed by Google + AI assistants.
Does the X Ads API support A/B testing?+
Yes. POST accounts/:account_id/ab_tests creates a test, PUT accounts/:account_id/ab_tests/:ab_test_id updates one, and both accept JSON bodies only with Content-Type set to application/json. X announced it on 10 June 2022 as an API-exclusive launch and added line item level splits on 16 August 2022. What it does not have is a published reference: the two links to one on X's A/B testing page both point at the retired developer.x.com portal and redirect to a homepage.
How many user groups can one X A/B test have?+
Between 2 and 30 at the campaign level. Each group needs a size, given as a string between 1.00 and 99.00, and the sizes across all groups must add up to exactly 100.00. Line item level tests are tighter: no more than 5 user groups, only equal splits, exactly one line item per group, and every line item in the campaign has to be included in the test.
How long does an X Ads API A/B test have to run?+
At least one day for non-app campaigns and at least five days for app-based campaigns. The start_time and end_time must both be in the future relative to when you create the test, and they must overlap the flight dates of the campaigns or line items you are splitting. X recommends changing only one variable at a time so the performance difference can be attributed to it.
How do I read the results of an X Ads API A/B test?+
Not through the A/B testing endpoints, and not through a segmentation. The phrases user group and A/B test appear nowhere in the Ads API Analytics namespace, so there is no documented way to pull stats broken out by test cell. The workable approach is to record which campaign or line item ids went into which user group when you create the test, then pull normal analytics per entity and aggregate by group yourself. The Ads Manager UI does compute a winner, so if a verdict is what you need, run the test there instead.
What can I A/B test on X ads?+
It depends which door you use, and the two do not match. The API states it supports any campaign variable including creative, targeting, bid type and bid unit. The Ads Manager UI, per X's own help page, supports only creative as the test variable: images, videos, text and CTAs. So targeting and bidding tests are API-only, and a computed winning cell is UI-only.
Can I trust the code sample on X's A/B testing page?+
Copy the JSON structure, not the URL. The only request example on the page calls /8/accounts/18ce54d4x5t/ab_tests. Version 8 of the Ads API reached end of life on 31 August 2021. The current version is 12, introduced 27 October 2022, and the rest of the Ads API docs use ads-api.x.com/12 in 353 places. The example response also disagrees with the spec on its own field type, giving one group size as the string 50.0 and the next as the number 50.
- X developer docs, Ads API 'AB Testing': the ab_tests create and update endpoints, 2 to 30 user groups, size as a string from 1.00 to 99.00 summing to 100.00, entity_type of CAMPAIGN or LINE_ITEM, the one-day and five-day minimum durations, the four line item level restrictions, and the page text ending mid-sentence in the Updating section (fetched 14 November 2026)
- X Developers forum, Ads API announcement 'New: A/B Testing on the Ads API', posted 10 June 2022 with an update dated 16 August 2022 adding line item level support: the API-exclusive launch, the new ab_tests endpoint, and the minimum of 2 and maximum of 30 user groups
- X Business help centre, 'A/B Testing in the Ads Manager UI': self-serve A/B testing launched January 2023, creative as the only supported test variable, up to 5 mutually exclusive buckets with up to 5 ads each, reporting at ad group level, and the winning cell defined as lowest cost per selected metric alongside volume of events, cost per event and win probability if rerun (accessed 14 November 2026)
- X developer docs, Ads API 'Versions': version 12 on /12/ introduced 27 October 2022 with deprecation and end of life both TBD, and version 8 on /8/ end of life 31 August 2021 (accessed 14 November 2026)
- X developer docs, 'llms-full.txt', the flattened documentation corpus at 4,858,201 bytes: four occurrences of ab_tests and zero occurrences of 'user group' outside the single A/B testing page (fetched and grepped 14 November 2026)
- X developer docs, Ads API 'Rate limiting': writes across POST, PUT and DELETE sharing one category bucket of 450 requests per minute, and the statement that there is no programmatic index of per-endpoint limits (accessed 14 November 2026)
Product designer and indie hacker. Runs the agent on his own X account every day and writes up what the data shows, including when it's inconvenient.
Follow on X →