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.
On this page · 10 sections
- Quick answer
- The update route left in 2018 and the guide never noticed
- The estimate drops the thing you are estimating
- An empty line item is a global buy
- Primary types widen, other types narrow
- 31 documented types, 15 of them ever demonstrated
- Discovery is cheap to write and expensive to call
- Five of the gated features are targeting features
- The caps worth writing down
- The bottom line
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:
| Operation | Endpoint | Notes |
|---|---|---|
| List | GET accounts/:account_id/targeting_criteria | line_item_ids required, up to 200 ids, count max 1,000 |
| Read one | GET accounts/:account_id/targeting_criteria/:id | with_deleted available |
| Create | POST accounts/:account_id/targeting_criteria | One criterion per call |
| Create and delete | POST batch/accounts/:account_id/targeting_criteria | 500 operations, all-or-nothing |
| Delete | DELETE accounts/:account_id/targeting_criteria/:id | Soft 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 targeting | Returned range | Excluded by warning |
|---|---|---|
| Denmark only | 601,326 to 696,134 | none |
| Denmark + GENDER female | 116,091 to 132,200 | none |
| Denmark + INTEREST Sports | 617,375 to 705,092 | INTEREST |
| Denmark + BROAD_KEYWORD football | 602,422 to 708,508 | BROAD_KEYWORD |
| Denmark + EXACT_KEYWORD football | 607,063 to 696,843 | EXACT_KEYWORD |
| Denmark + PHRASE_KEYWORD football | 613,830 to 691,880 | PHRASE_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" types | Other types |
|---|---|
| Followers of | Locations |
| Custom audiences | Gender |
| Interests | Languages |
| Keywords | Devices and platforms |
| TV | Age |
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_KEYWORDNEGATIVE_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_operatorslistscounttwice in its parameter table, and itscountry_codedescription 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.eventsmarksevent_typesas 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=CITIESand 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.
- X developer docs, 'Campaign Management API Reference': the Targeting Criteria endpoints (GET, GET by id, POST, POST batch, DELETE and no PUT), the 31-value targeting_type enum, the operator_type values EQ, NE, GTE and LT, the 12 Targeting Options discovery endpoints, Targeting Suggestions, the audience_estimate contract and the 22-value account feature_keys enum (accessed 15 November 2026)
- X developer docs, 'Campaign Management': the instruction to use PUT accounts/:account_id/targeting_criteria to update targeting, the statement that a line item with no targeting criteria targets all users worldwide, the primary-versus-other targeting table with its union and AND semantics, the per-line-item caps on keywords, interests, locations and users, and the Russian-language display requirement (accessed 15 November 2026)
- X Developers forum, 'Ads API Version 3', posted 1 February 2018 by the Ads API team: the removal of PUT accounts/:account_id/targeting_criteria, the stated reason that its replace behaviour caused advertiser confusion, the instruction to migrate to POST batch, the 500 batch size limit, the 1 August 2018 v2 shutoff, and the non-batch to batch crosswalk retiring NEGATIVE_BEHAVIOR and the NEGATIVE_*_KEYWORD spellings
- X Developers forum, 'Ads API: PARTIAL_TARGETING excludes interests/keywords and blocks media planning', posted 12 November 2026 with no reply: six measured audience_estimate ranges on a Denmark account, the AUDIENCE_ESTIMATE_PARTIAL_TARGETING warning code, the unsupported_targeting_types field, and the observation that INTEREST, BROAD_KEYWORD, EXACT_KEYWORD and PHRASE_KEYWORD were each excluded
- X Developers forum, 'Deprecation Announcement - Changes to TV Targeting', posted 22 July 2016 with the February 2017 follow-up: TV channel and genre targeting removed effective 19 October 2016, the tv_channels and tv_genres endpoints returning UNKNOWN_CRITERIA_TYPE, and the retirement of TV_SHOW_AIRING_RESTRICTED
- X developer docs, Ads API 'Rate limiting': the Targeting Criteria category at 400 requests per 15 minutes, the tv_markets and tv_shows endpoint allowance of 2,000, the five-per-15-minutes ceiling on global reads without an account_id, and the advice to call GET targeting_criteria with the maximum count of 1,000 (accessed 15 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 →