X-Autopilot

X Ads API targeting: the update route that is missing

X's Ads API guide tells you to update targeting with a PUT that X removed in 2018, and the audience estimate now drops interests and keywords.

X-Autopilot Team··12 min read
On this page · 10 sections

The short version

  • ▸There is no PUT on targeting criteria and there has not been since 2018. X announced the removal on 1 February 2018 in the Ads API v3 release and shut off v2 on 1 August 2018. The Campaign Management guide still names PUT accounts/:account_id/targeting_criteria three times as the way to update targeting, and two of those links point at the GET endpoint.
  • ▸The audience estimate now excludes the criteria most plans are built on. A developer measured it on 12 November 2026: adding INTEREST or any keyword match type returns a warning with code AUDIENCE_ESTIMATE_PARTIAL_TARGETING and an unsupported_targeting_types array. Neither that code nor that field appears anywhere in X's 4.86 MB documentation corpus.
  • ▸A line item with no targeting criteria does not fail to serve. X states it will target all users worldwide. That sentence appears once, in a sub-section of the guide, and nothing in the POST line_items contract requires targeting before the budget starts spending.
  • ▸Stacking primary targeting types widens reach rather than narrowing it. Followers, custom audiences, interests and keywords are unioned with each other, then AND-ed against location, gender, language, device and age. Adding keywords to an interest-targeted ad group makes it bigger.
  • ▸Five of the 22 gated account features are targeting features, and the endpoint that grants them is sandbox-only. AGE_TARGETING, VALIDATED_AGE_TARGETING, EVENT_TARGETING, INSTALLED_APP_CATEGORY_TARGETING and ENGAGER_RETARGETING can be switched on in the sandbox and cannot be requested by a developer in production at all.

Quick answer

X Ads API targeting is five endpoints, 12 discovery lookups and one estimator, and the single most-cited instruction about it is wrong. X's Campaign Management guide tells you to update targeting with PUT accounts/:account_id/targeting_criteria. X removed that endpoint in Ads API v3, announced on 1 February 2018. The real update path is POST batch, with Create and Delete operations in the same array. Separately, as of 12 November 2026 the audience estimate returns a warning that it excluded your interest and keyword criteria from the number it just gave you.

Last updated: November 2026

Everything below comes from X (formerly Twitter) documentation and X's own developer forum, read on 15 November 2026 against v12. Each claim links the page or thread it came from.

The update route left in 2018 and the guide never noticed

The Campaign Management guide opens its targeting section like this: "To set new targeting criteria you need to use POST accounts/:account_id/targeting_criteria and PUT accounts/:account_id/targeting_criteria to update them."

That PUT does not exist. The v3 release note is explicit about it under a heading called Removed:

The PUT accounts/:account_id/targeting_criteria endpoint is no longer available. We've decided to make this change because the replace behavior with this endpoint caused advertiser confusion and it was not consistent with our other PUT endpoints that update a single resource at a time.

Partners got six months. v2 was shut off on 1 August 2018. Eight years and nine major versions later, the guide names the endpoint three times: once in the opening instruction, once at the end of the targeting-types section as the place to find "a summary of all values with required/optional and specific details for each", and once in the Keyword Targeting in Timelines quick start. The reference page names it zero times.

Links are worse than prose here. Two of those three PUT mentions are hyperlinked, and both resolve to the anchor for the GET endpoint. The third points at dev.x.com/ads/reference/put/..., on a hostname that no longer serves documentation.

So the honest version of the namespace is:

OperationEndpointNotes
ListGET accounts/:account_id/targeting_criterialine_item_ids required, up to 200 ids, count max 1,000
Read oneGET accounts/:account_id/targeting_criteria/:idwith_deleted available
CreatePOST accounts/:account_id/targeting_criteriaOne criterion per call
Create and deletePOST batch/accounts/:account_id/targeting_criteria500 operations, all-or-nothing
DeleteDELETE accounts/:account_id/targeting_criteria/:idSoft delete, deleted: true

There is no update. Changing a keyword means deleting a criterion and creating another, which means the criterion id your system stored is now a dead reference. If you are building a tool that diffs desired targeting against live targeting, plan for identity to be keyed on targeting_type plus targeting_value, never on id.

The estimate drops the thing you are estimating

POST accounts/:account_id/audience_estimate is how you size an audience before you buy it. The reference shows it being called with broad keywords, a location and two lookalike seeds, and returns an audience_size object with a min and a max.

On 12 November 2026 a developer building media-planning tooling measured what it actually returns. Same account, same Denmark location value, one criterion changed at a time:

Requested targetingReturned rangeExcluded by warning
Denmark only601,326 to 696,134none
Denmark + GENDER female116,091 to 132,200none
Denmark + INTEREST Sports617,375 to 705,092INTEREST
Denmark + BROAD_KEYWORD football602,422 to 708,508BROAD_KEYWORD
Denmark + EXACT_KEYWORD football607,063 to 696,843EXACT_KEYWORD
Denmark + PHRASE_KEYWORD football613,830 to 691,880PHRASE_KEYWORD

Gender narrowed the number by roughly 80%. Every interest and keyword request came back at or above the country-only control, with a warning attached:

"warnings": [{
  "code": "AUDIENCE_ESTIMATE_PARTIAL_TARGETING",
  "message": "Some targeting options are not included in audience estimates. Your campaign will still serve using all selected targeting.",
  "unsupported_targeting_types": ["INTEREST"]
}]

Two things make this worth building defensively against. First, the response is an HTTP 200 with isError: false, so a client that reads audience_size and ignores everything else records a national population as the size of a sports-interest segment. Second, neither AUDIENCE_ESTIMATE_PARTIAL_TARGETING nor unsupported_targeting_types appears anywhere in X's 4.86 MB documentation bundle. The response contract is real and undocumented, which is the same shape of problem we found in the X Ads API error vocabulary.

The reference compounds it by requiring what the estimator drops: "It is required that you specify at least one primary targeting criterion", with a link to the list of primary criteria. Keywords and interests are two of the five primary types. The thread asking whether the exclusion is intentional, a regression, or specific to the access tier has sat without a reply since it was posted.

An empty line item is a global buy

One sentence in the guide, inside the Targeting Criteria Combinations sub-section, in bold: "If no targeting criteria is specified for a line item, the line item will target all users worldwide."

Nothing enforces targeting earlier in the flow. POST line_items needs a campaign id, an objective and a placement. The targeting call is a separate request against a separate endpoint, and the gap between those two requests is a window in which a funded, unpaused line item is eligible to serve to everyone on the platform. The X Ads API campaign hierarchy is four objects deep and the order matters more than the docs imply.

Create line items with entity_status paused, attach targeting, verify with a GET scoped to that line_item_id, then unpause. It costs one extra call.

Primary types widen, other types narrow

This is the part most people carry in wrong from other ad platforms, where every added dimension is an intersection. X splits its targeting types into two classes and combines them differently:

"Primary" typesOther types
Followers ofLocations
Custom audiencesGender
InterestsLanguages
KeywordsDevices and platforms
TVAge

Here is the combination rule, in X's own notation: [(Followers) ∪ (Custom Audiences) ∪ (Interests) ∪ (Keywords)] AND (Location) AND (Gender) AND (Languages) AND (Devices and Platforms). Same type OR-ed, primary types unioned, other types AND-ed.

Read that twice before you add a keyword list to an interest-targeted ad group, because the result is a bigger audience, not a tighter one. If you want an intersection of interest and keyword, X does not offer it on one line item. You build it as separate line items and compare, which is also the only way to attribute the difference, since the A/B testing namespace will not tell you which cell won.

Exclusions behave the opposite way and are cheap. operator_type=NE on any criterion turns it into a negative, and the v3 crosswalk collapsed the old dedicated negative types into exactly that: NEGATIVE_PHRASE_KEYWORD became PHRASE_KEYWORD plus NE.

31 documented types, 15 of them ever demonstrated

The targeting_type enum on POST targeting_criteria lists 31 values: 22 non-keyword, four keyword, two custom audience, two app store category, and APP_LIST for Twitter Audience Platform exclusions.

Pull every "targeting_type": "..." string out of every example response in X's whole documentation bundle and you get 17 distinct values. Fifteen are in the enum. Two are not:

  • NEGATIVE_PHRASE_KEYWORD
  • NEGATIVE_BEHAVIOR

Both are pre-v3 spellings. The 2018 migration table replaced the first with PHRASE_KEYWORD plus NE, and the second with BEHAVIOR plus NE, and BEHAVIOR itself is gone from the enum now, surviving only as the error constant BEHAVIOR_OR_BEHAVIOR_EXPANDED_NOT_FOUND. The example payload carrying them is in the account history endpoint, which is also the only place in the corpus where an age bucket value appears at all: AGE_21_TO_34, twice. The guide says the age bucket enums live on the Enumerations page and links to the Ads API introduction, which is a page of navigation cards with no enumerations on it.

Sixteen documented types appear in no example anywhere, including every engagement-retargeting type, WIFI_ONLY, APP_LIST, CUSTOM_AUDIENCE_EXPANDED and TV_SHOW. The guide also describes three video-viewer targeting types, VIDEO_VIEW, VIDEO_VIEW_PARTIAL and VIDEO_VIEW_COMPLETE, that are absent from the enum and from the ENGAGEMENT_TYPE value list, which the same guide says accepts only IMPRESSION or ENGAGEMENT.

Stale examples are the theme. The device lookup demonstrates iPhone 3GS and iPhone 4. The platform version lookup demonstrates Android 4.0 and 4.1. The platform list still has five values, one of which is BlackBerry phones and tablets. The TV show lookup still returns a genre field a decade after X removed TV genre targeting, effective 19 October 2016.

Discovery is cheap to write and expensive to call

Twelve GET targeting_criteria/* endpoints turn human-readable targets into the opaque ids that targeting_value expects. They are the part of the namespace you will call most and the part most likely to stall your integration.

X's rate limit chart gives Targeting Criteria 400 requests per 15 minutes as a category, and tv_markets and tv_shows 2,000 each as endpoints. Then a separate row caps "Global Reads (GET endpoints without :account_id)" at five per 15 minutes. Every discovery endpoint except one has no account_id in its path, so both rows describe them and the chart never says which wins. Treat them as global reads and cache aggressively: five calls per 15 minutes will not paginate a location list, and X tells you to refresh these weekly anyway because the values change without notice.

Three more details that cost real time:

  • network_operators lists count twice in its parameter table, and its country_code description says that without the parameter "only partner audiences for the United States are returned". That sentence was copy-pasted in from the audiences namespace. It is a carrier lookup.
  • events marks event_types as a required enum and then describes it as "an optional query to scope to certain event types" in the same block.
  • The location filter and the location response disagree. You filter with location_type=CITIES and the created criterion comes back with "location_type": "CITY". A query for Los Angeles returns eight rows, two of which are literally named Los Angeles. Pick the wrong hash and you have bought a different city.

Of 16 distinct reference.md# anchors linked for targeting across the guide and the reference, one resolves. The rendered page keeps slashes and underscores in its anchor ids, like get-targeting_criteria/interests, while every link kebab-cases them. That includes both links to the list of primary targeting criteria that the audience estimate says is required reading.

Five of the gated features are targeting features

GET accounts/:account_id/features returns which beta and limited-release features your ad account has. The enum has 22 values. Five of them govern targeting: AGE_TARGETING, VALIDATED_AGE_TARGETING, EVENT_TARGETING, INSTALLED_APP_CATEGORY_TARGETING and ENGAGER_RETARGETING.

So the targeting_type enum tells you what the API parses, and this endpoint tells you what your account may use. The two are not the same list, and the gap is not something you can close yourself. X states plainly that "API developers can not request access to features on behalf of an advertiser", and that the request has to come from the advertiser to their X account manager.

The trap sits in the sandbox. POST accounts/:account_id/features grants any of the 22 to a sandbox account, and it is marked sandbox-only. Age targeting, event targeting and engager retargeting will all work perfectly in your test environment and return a permissions error the first time a real advertiser runs them. Call GET features as part of your production onboarding and gate the UI on the response.

One jurisdiction rule to carry too, since it is enforced on your side rather than X's: X's ads policies prohibit targeting Russia with non-Russian-language ads, and X requires partner tools to show the warning "Ads targeting Russia must be in the Russian language" to the user who selects it.

The caps worth writing down

Per line item: 1,000 keywords, 100 interests, 100 users for SIMILAR_TO_FOLLOWERS_OF_USER, 2,000 locations, one event, one age bucket. TV_SHOW needs a LOCATION criterion already present in the same locale. Per account: 100 line items per campaign, 200 active campaigns, 8,000 active line items. Per request: 500 batch operations, count up to 1,000 on most lookups but 50 on tv_shows and 50 suggestions from targeting_suggestions.

Emoji targeting works through keyword targeting using the Unicode codepoint, and targeting one emoji targets all its variations. Broad match, the default, silently expands your term, so "car repair" also matches "automobile fix" unless you prefix each word with a plus sign. Unordered keywords are deprecated.

The bottom line

Capability is not the problem: 31 types, real exclusions, batch writes, and a discovery endpoint for nearly every dimension. What is unreliable is the map. The documented way to update targeting has not existed since 2018, the documented list of primary criteria is behind a dead anchor, the estimator silently discards the two dimensions most plans are built on, and an empty line item is a worldwide buy rather than an error.

Build against the reference, not the guide, verify every write with a scoped GET, and read the warnings array even on a 200. If you want the paid side automated, pair this namespace with X custom audiences for the audience half and watch the auth clock, because X Ads API carries the date OAuth 1.0a user authentication stops working.

If your problem is organic reach rather than paid reach, targeting is the wrong tool entirely. X-Autopilot runs replies and posting from your own Mac in your own browser session, which keeps a lower detection surface than cloud tools logging in from a shared IP pool, and it is a grey area rather than a sanctioned one: we make no claim that browser automation complies with X's terms, and X's automation rules are what to read before deciding. The trade-offs are set out on the download page.

Frequently asked

Answers indexed by Google + AI assistants.

How do you update targeting criteria in the X Ads API?+

You delete and recreate, in one call. POST batch/accounts/:account_id/targeting_criteria accepts a JSON array where each item has an operation_type of Create or Delete, up to 500 items, and the whole batch succeeds or fails together. There is no PUT: X removed PUT accounts/:account_id/targeting_criteria in Ads API v3, announced 1 February 2018, because its replace behaviour confused advertisers and did not match X's other PUT endpoints. The practical consequence is that a targeting criterion has no stable identity across an edit, since the new criterion comes back with a new id.

Why does the X audience estimate ignore my interest or keyword targeting?+

Because the endpoint is currently excluding those dimensions and telling you so in a warning rather than an error. Measured on 12 November 2026 against v12, a Denmark plus INTEREST Sports request returned 617,375 to 705,092 with warnings containing the code AUDIENCE_ESTIMATE_PARTIAL_TARGETING, the message that some targeting options are not included in audience estimates, and unsupported_targeting_types set to INTEREST. Denmark alone returned 601,326 to 696,134, so the narrower audience read larger than the control. The forum report asking whether this is intentional has no reply.

What happens if a line item has no targeting criteria?+

It targets everyone. X's Campaign Management guide states that if no targeting criteria is specified for a line item, the line item will target all users worldwide. Nothing in the POST line_items parameter table makes targeting a prerequisite, so a campaign created in the correct order with the targeting call left out is a live global buy. Create the line item paused, attach targeting, then unpause.

How many targeting types does the X Ads API support?+

The POST targeting_criteria contract lists 31 targeting_type values across five groups: 22 non-keyword types, four keyword types, two custom audience types, two app store category types, and APP_LIST for Twitter Audience Platform exclusions. Only 15 of the 31 appear in any example response in X's documentation. Two values that do appear in examples, NEGATIVE_PHRASE_KEYWORD and NEGATIVE_BEHAVIOR, are not in the enum at all: they are the pre-v3 spellings that the 2018 migration table replaced with a base type plus operator_type NE.

What are the X Ads API targeting limits per line item?+

Per line item: up to 1,000 keywords, 100 interests, 100 users for similar-to-followers targeting, 2,000 locations, one event, and one age bucket. Across the account: 100 line items per campaign, 200 active campaigns, and 8,000 active line items. Batch targeting writes cap at 500 operations per request. TV_SHOW targeting additionally requires at least one LOCATION criterion already on the line item, in the same locale as the show.

Sources
Related searches
x ads api targetingx ads api targeting_criteriatwitter ads api targeting criteriax ads api audience estimatex ads api targeting types listpost batch targeting criteria x ads apix ads api interest targetingx ads api keyword targetinghow to update targeting x ads apix ads apix ads api campaignsx custom audiences apix ads managerads api version 12line item targetingx ads cost
DY
Deepak YadavBuilding X-Autopilot

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 →
Try X-Autopilot.
$199 once. No subscription, no monthly bill. Real Chrome on your Mac.
See pricing▶
Free PDF · the X Growth Playbook

The exact playbook we use to grow on X

The bio that converts, the daily reply loop, the posting cadence, and the tool stack, in one no-fluff PDF. Drop your email and it's yours.

No spam. Unsubscribe anytime.

Free tools

Try it yourself.

All free X tools →
Keep reading

Related posts.