X Ads API campaigns: the limits its docs state twice

#Quick answer

X Ads API campaigns are created with POST accounts/:account_id/campaigns, and the two objects that call depends on - an ads account and a funding instrument - cannot be created through the API in production. Six of the 87 Campaign Management endpoints are marked SANDBOX ONLY, and they are exactly those create paths. Worse for anyone building quota logic: the campaign ceiling and the line item ceiling are each documented twice with different numbers. 4,000 or 8,000 campaigns. 256 or 4,000 active line items. Pick wrong and your integration either refuses work it could do or promises work the API will reject.

Last updated: November 2026

Everything below was read on 14 November 2026 against X's own documentation and the flattened corpus at docs.x.com/llms-full.txt, which is 4,858,201 bytes of every doc page in one file and therefore the cheapest way to prove how many times X says something.

#The two objects you cannot create

Campaign structure is four objects deep: funding instrument, campaign, line item, promoted post. Budget and schedule live on the campaign. Targeting, bidding, objective and creative live on the line item. Nothing serves until a creative is attached.

Only the bottom two of those four are yours to create.

Funding instruments are explicit about it: "Funding Instruments can not be created via the Ads API, they have to be already established by the advertiser's account manager at X (for credit lines) or via ads.x.com (for credit cards)." The ads account is the same story by omission. POST accounts exists in the reference, and it carries a SANDBOX ONLY banner and a resource URL on ads-api-sandbox.x.com.

Six endpoints carry that banner, and the set is revealing:

In production you can rename an ads account with PUT accounts/:account_id. You cannot create one, delete one, grant it a beta feature, or give it money. That is deliberate and sensible - these are billing objects - but it changes the shape of any onboarding flow you build. An agency tool cannot provision an advertiser. It can only attach to an advertiser who has already been provisioned by a human at X or through the Ads UI.

Against that, the sandbox is genuinely useful here. Call POST accounts on ads-api-sandbox.x.com, mint a funding instrument of type CREDIT_LINE with whatever credit limit you like, and build the whole integration while your X Ads API access application is still in review. X notes there is no risk of incurring costs on a sandbox funding instrument, and sandbox campaigns never serve to users.

#Every ceiling, stated twice

Here is what X publishes about how much one ads account can hold.

Two of those rows are straight contradictions, and they are not typos buried in an old changelog. I grepped the full corpus: 4,000 active campaigns appears once, 8,000 active campaigns appears once, 256 active line items appears once, 4,000 active line items appears once. Four load-bearing numbers, four single mentions, two disagreements.

The 256 figure is the one that matters most, because it is 15 times smaller than the alternative and it lives on POST accounts/:account_id/line_items - the page you read while writing the call. If 256 is real, a single campaign at the 100-line-item maximum consumes 39% of your account's entire line item budget. If 4,000 is real, line items are effectively unlimited for most advertisers. There is no way to tell from the documentation which is true, and the API returns no quota endpoint to ask.

What makes this expensive rather than merely untidy is the definition of "active". The glossary says a paused campaign is still active for limit purposes. The overview says paused campaigns count as active until their designated end times. The endpoint reference says there is no limit to the number of inactive campaigns. Combine them and you get the rule nobody writes down: a paused campaign with a null end_time never stops counting. If your tool pauses campaigns instead of deleting them, which is the safe-looking choice, you will walk into the 200 ceiling and the error will not explain why.

Practical advice: treat 200 campaigns and 256 active line items as your real budget, delete what you will not reuse rather than leaving it paused forever, and ask the advertiser's X account manager to confirm their account's actual raised limit in writing before you design around either published number.

#The walkthrough runs on dead versions

Ads API endpoints are versioned in the URL path, and version 12 has been current since 27 October 2022. Two versions are accepted at a time, so /11/ and /12/ work and everything older does not.

"Creating a Campaign - Step-by-Step", the single page a new integrator follows end to end, calls /8/ fourteen times, /9/ seven times and /5/ once. Not one example in that narrative is on a live version. Per X's own version table, /9/ reached end of life on 31 March 2022, /8/ on 31 August 2021, and /5/ on 3 March 2020.

Its reference page, one click away, uses ads-api.x.com/12 in 159 places. So the facts are current and the copy-pasteable commands are not. Read the guide for the sequence, take the paths from the reference, and if you want to see the version that actually works in a guide, the Dynamic Product Ads walkthrough is on /12/ throughout.

#Fields with exactly one legal value

Three parameters on the campaign write path are vestigial, and knowing which saves a day of integration guesswork.

budget_optimization is documented with a default of LINE_ITEM and possible values of, in full, LINE_ITEM. There is one legal value. It exists because there used to be more.

standard_delivery is now explicitly "deprecated at the campaign level", because budget optimization is always LINE_ITEM, so standard versus accelerated pacing is set on the line item instead. X's own MCP documentation confirms the practical consequence: create_campaign does not accept standard_delivery at all.

entity_status is the one to be careful with. Its default on POST campaigns is ACTIVE. The MCP server, by contrast, always creates campaigns and line items PAUSED and requires an explicit activate_campaign call. Same company, same underlying endpoint, opposite default. If you write directly against REST and omit entity_status, you get a live campaign. It cannot serve yet - the response returns servable: false with reasons_not_servable: ["INCOMPLETE"] until a line item and creative exist - but the moment those attach, it spends. Send entity_status=PAUSED on every create and activate deliberately.

One more asymmetry worth knowing before you build an edit screen: the goal enum on POST line_items has 16 values and the enum on PUT line_items/:line_item_id has 15. The missing one is SITE_VISITS, which is the default goal for WEBSITE_CLICKS - and the PUT page's own pay_by description still says "The SITE_VISITS goal supports IMPRESSION values." A documented value absent from the enum on the same page that discusses it.

#The limit that stops you first

Ads API rate limits have no programmatic index. You read them from x-rate-limit-* and x-account-rate-limit-* response headers, and X states plainly that it generally cannot raise them.

Core entity reads - campaigns, line items - get 10,000 per 15 minutes at ad account level, which is generous. Writes get 450 per minute as a category. The number that bites is global reads, meaning any GET without an :account_id in the path: 5 per 15 minutes. Twenty-one of the 87 Campaign Management endpoints are shaped that way, including every targeting discovery call and, critically, GET accounts - the first request in both official walkthroughs.

Call GET accounts in a debug loop and you are locked out in under a minute for reasons the error will not make obvious. Fetch the account list once, cache the account_id, and never ask again.

Targeting discovery sits in an awkward spot here too. The rate limit chart lists both a "Targeting Criteria" category at 400 per 15 minutes and the 5-per-15-minutes global read bucket, and endpoints like GET targeting_criteria/locations qualify for both descriptions with no statement of which applies. Treat them as global reads, cache the results - locations, interests, devices and TV markets barely change - and you never have to find out.

#What this means if you are not building a campaign tool

Most people reading about X Ads API campaigns are weighing paid reach against organic reach, not writing an integration. Two things from the above are worth carrying over.

First, the objective list is the shape of the product. Eight values, priced per objective: CPE for ENGAGEMENTS, CPF for FOLLOWERS, CPM for REACH, CPLC for WEBSITE_CLICKS. You are buying one action type per campaign, and you cannot mix objectives inside a campaign, which is why real X ads costs vary so much by goal. Promoted Trends are not purchasable through the API at all.

Second, spend is not spend for three days. X says billing metrics should be treated as speculative until roughly 72 hours after the event, and that the final number is always lower because it is corrected for spam and low-quality traffic. Any dashboard that reconciles same-day is reconciling a number that will shrink.

If you want the paid side automated end to end, the sanctioned route is this API plus X custom audiences for targeting and OAuth 2.0 for auth - and the clock on that auth matters, since X API OAuth 1.0a user authentication stops working on 31 January 2027 while the Ads API fundamentals pages still instruct you to sign with it. The lowest-effort way to drive it today is X's own hosted server, covered in our X MCP server walkthrough, which wraps all of this in 74 tools and defaults to paused writes.

For the organic half of the same account, X-Autopilot runs on your own Mac with your own session and residential IP instead of a shared cloud pool, which lowers the detection surface compared with cloud schedulers without eliminating it. Browser-driven automation of your own account is a gray area X has never endorsed, and no tool can honestly tell you otherwise. The Ads API is the opposite: approved, documented, rate limited in writing, and billed to a funding instrument you set up by hand.

#The bottom line

The X Ads API campaign surface works, and it is better specified than most ad APIs - 87 endpoints, real enums, a free sandbox that mints fake money. What it does not have is a single authoritative statement of how much one account can hold. Two pages claim different raised campaign ceilings, two pages claim line item caps 15 times apart, and three pages disagree about whether a paused campaign counts.

Until X reconciles them, build against the smaller number in every pair, delete rather than pause, cache GET accounts on first call, and send entity_status=PAUSED on every create. None of those choices costs you anything if the generous numbers turn out to be the real ones.