X Ads API mobile conversions: 23 metrics behind one flag
X Ads API mobile conversions needs an account enabled for MACT, and the route that removed the partner requirement never says whether it sets that flag.
On this page · 9 sections
- Quick answer
- Two endpoints, and only one answers back
- The flag the reporting hangs on
- 23 metrics to read, 20 types to send
- The windows live somewhere you cannot reach through the API
- What the page itself is missing
- Requesting the numbers without wasting the rate limit
- Who should actually care
- The bottom line
The short version
- ▸Two routes report the same app install and only one answers back. A mobile measurement partner posting to /12/conversion_event gets a twitter_attribution node in the HTTP response, carrying campaign_id, line_item_id, line_item_objective and the post id. The direct Conversion API for App Events returns conversions_processed and a debug_id.
- ▸The reporting side is gated. X states that both MOBILE_CONVERSION and LIFE_TIME_VALUE_MOBILE_CONVERSION stats are available only to advertiser accounts enabled for MACT. The App Events page, which exists to remove the partner requirement, never says whether connecting it sets that flag.
- ▸MOBILE_CONVERSION is 23 metrics and the lifetime group is 15. INSTALL, the event every app install campaign optimises for, has no lifetime metric. Three reportable types have no matching value in the partner endpoint's 20-value conversion_type enum, and four more are spelled differently in the metric that reports them.
- ▸Attribution windows are read-only through the API. The namespace exposes two GET endpoints for app_event_tags and no POST, PUT or DELETE, so post_engagement_attribution_window and post_view_attribution_window are set in Events Manager and only inspected through code.
- ▸X tells you to request MOBILE_CONVERSION in its own analytics call, and the CONVERSION_TAGS segmentation that would split numbers by event is documented as compatible with WEB_CONVERSION only. Mobile numbers break down by age, gender, metro, region and platform, not by which event fired.
Quick answer
X Ads API mobile conversions is two send paths and one gated read. A mobile measurement partner posts to /12/conversion_event and gets the attributing campaign back in the same HTTP response. An advertiser using the Conversion API for App Events, added 29 October 2026, posts up to 500 events to /12/accounts/:account_id/measurement/app_conversions and gets back a count. The numbers then come out of the MOBILE_CONVERSION metric group, which X documents as available only to advertiser accounts enabled for MACT. Nothing on the page that removes the partner requirement says whether using it enables that flag.
Last updated: November 2026
Everything below was read on 17 November 2026 against X (formerly Twitter) Ads API v12, in X's own developer documentation. The structural problem is easy to miss because the two halves of this product are documented on pages that barely acknowledge each other: one page sends events, another page reports them, and the condition that connects them is a single sentence.
Two endpoints, and only one answers back
The Mobile Conversions page opens by pointing you somewhere else. Its first line under the MACT overview tells advertisers they can send app events directly with the Conversion API for App Events, then states plainly: "This page is for mobile measurement partners."
That split is real, and the two contracts are nothing alike.
| MACT partner route | Conversion API for App Events | |
|---|---|---|
| Route | POST /12/conversion_event | POST /12/accounts/:account_id/measurement/app_conversions |
| Who it is for | Mobile measurement partners | Advertisers, direct |
| Auth | Standard Ads API credentials | X-App-Conversion-Token header from Events Manager |
| Events per request | One | Up to 500 |
| Event names | conversion_type, a fixed 20-value enum | event_name, whatever you created in Events Manager |
| Device id | hashed_device_id, required, HMAC_SHA-256 | device_id, raw and unhashed, or hashed email, hashed phone, or IP with user agent |
| Timestamp | ISO-8601 with milliseconds | Unix milliseconds |
| Windows | click_window and view_through_window per request | Set per event in Events Manager |
| Response | Full attribution or an explicit null | conversions_processed and debug_id |
The response row is the one that matters. On the partner route, X tells you what it thinks caused the conversion while you are still holding the connection open. The twitter_attribution node is always present and set to null when X claims nothing, and when it does claim the install it hands back campaign_id, line_item_id, line_item_objective, publisher_app_id, account_id and the post id. That is a complete attribution record, per event, synchronously.
The direct route returns a number and a support identifier. Attribution still happens, but you read it later, out of reporting, aggregated. If you are building a dashboard that needs per-install attribution rather than per-campaign totals, that difference decides which path you are on, and it is not stated as a trade-off anywhere.
A smaller detail runs the other way, and it is worth noticing before a privacy review does. The partner route demands a hashed device id. The direct route takes the raw, unhashed IDFA or Android advertising id and recommends it as the best identifier. The route X built for advertisers asks for less hashing than the route it built for partners.
The flag the reporting hangs on
Sending events is the easy half. Reading them back runs through the analytics namespace, and there the mobile metric groups carry one sentence each:
Mobile conversion stats are available only to advertiser accounts enabled for MACT.
The same sentence appears under LIFE_TIME_VALUE_MOBILE_CONVERSION. It is not qualified, dated or cross-referenced.
So here is the question the documentation does not answer. The Conversion API for App Events exists specifically so an advertiser does not need a mobile measurement partner. MACT is the name of the partner programme. Does connecting X App Conversion API in Events Manager enable the account for MACT, so these metric groups start returning data, or is the flag a separate entitlement that a direct integration never touches? The App Events page says nothing about metric groups. The analytics page says nothing about the App Events route. Neither mentions the other.
Treat it as unverified and design around it. Send a test install, then immediately request MOBILE_CONVERSION for the campaign and see whether the response comes back populated, empty, or with an error. That is a one-hour check that tells you more than either page does, and it is the kind of thing worth doing before you build reporting on top of an assumption. The one related error constant in the whole Ads API table is MACT_APP_NOT_FOUND, returned as a 404, which is what you would expect if the app itself is not registered rather than if the account is not entitled.
Campaign optimisation carries a related hint. The line item documentation says the APP_CLICKS and APP_INSTALLS optimisation options "may require using a supported MACT partner". That wording predates the direct route and has not been revised since it shipped, so the honest reading is that X has not yet decided what to say about it.
23 metrics to read, 20 types to send
Count the two sides and they do not line up.
MOBILE_CONVERSION publishes 23 metrics, each one a JSON object broken out by post_view, post_engagement, assisted, order_quantity and sale_amount. The partner endpoint's conversion_type enum accepts 20 values. Three of the reportable metrics describe types that enum has no value for at all: KEY_PAGE_VIEW, DOWNLOAD and SITE_VISIT. There is a metric waiting for events the documented endpoint cannot label.
Four more pairs match in meaning and differ in spelling, which is worse than a gap because it looks like it works:
| You send | The metric reports |
|---|---|
TUTORIAL_COMPLETE | TUTORIAL_COMPLETED |
ADDED_PAYMENT_INFO | PAYMENT_INFO_ADDITION |
SPENT_CREDITS | SPENT_CREDIT |
RATED | RATE |
For the direct route the mapping problem is sharper still, because event_name is not an enum. It is whatever you named the event in Events Manager. Nothing in the documentation maps an Events Manager event name onto a mobile_conversion_* metric, so which of the 23 metrics your PURCHASE event lands in is a convention you have to confirm by sending one.
Then there is the lifetime group, which is 15 metrics rather than 23, and the omission is conspicuous: there is no lifetime metric for INSTALL. Purchases, sign-ups, updates, reservations and eleven more all have one. The single event that every app install campaign is built to produce does not. Lifetime value also has no segmentation column filled in, so those 15 metrics come back as account-wide totals only.
The windows live somewhere you cannot reach through the API
App event tags are where the attribution windows are actually configured, and the namespace exposes exactly two endpoints for them: GET accounts/:account_id/app_event_tags and the single-tag variant. No POST. No PUT. No DELETE.
What a tag returns is useful: conversion_type, os_type, app_store_identifier, deep_link_scheme, retargeting_enabled, status, last_tracked_at, and the two windows as post_engagement_attribution_window and post_view_attribution_window. Read a tag and you know exactly what X will credit.
What you cannot do is change any of it from code. Connecting an app through the direct route creates the Install event with a 14-day post-engagement window and a 1-day post-view window, and changing those means going back into Events Manager by hand. The partner route is the only one that sets windows programmatically, and it does so per event rather than per tag, through click_window with values of 1, 7, 14 or 30 days and view_through_window with 0, 1, 7, 14 or 30, where the click window must be greater than or equal to the view window. Two different mechanisms, two different scopes, and an account can be using both at once.
What the page itself is missing
Four things about the Mobile Conversions page are worth knowing before you plan work against it.
Its three cross-references are gone. The links to the Conversion Event reference, the GET conversion_attribution endpoint and the X Audience Platform overview all point at developer.x.com paths that now return a 307 to the docs.x.com home page. The tpn_attribution node in the response is documented by a link to nothing, and conversion_attribution occurs exactly once in X's entire documentation corpus: in that dead link.
The page it sends you to is not in the index. X publishes llms.txt files as the canonical index of each namespace. The Ads API Measurement section lists four pages: AB Testing, the GTM server-side guide, Mobile Conversions and Web conversions. The Conversion API for App Events page is not among them, although it resolves fine and is present in the full-text corpus. Anything that discovers X's documentation through the index will not find the newer route.
The example response does not parse. In the conversion_event example, the comma after "publisher_app_id": "333903271" is missing. Paste it into a JSON parser and it fails on the next line.
The page stops mid-example. The final block, the example response for the single app event tag, ends four lines in with an unclosed brace. There is no closing content after it. If you were reading the page to learn the shape of that response, the page does not contain it.
None of this is fatal. All of it tells you the same thing: this namespace has been left where it was while the product moved, so verify against live responses rather than against the prose. The X Ads API pillar covers the same pattern on the access and versioning pages, and X Ads API errors covers a documented sandbox host that no longer resolves.
Requesting the numbers without wasting the rate limit
Two constraints shape every reporting call you will write here.
First, X notes in the analytics parameter table that MOBILE_CONVERSION data "should be requested separately". So a campaign that needs engagement, billing and mobile conversion numbers is at least two requests per entity batch, not one, against an analytics category limit of 250 requests per 15 minutes. Add the one-placement-per-request rule covered in X Ads API analytics and the arithmetic gets tight quickly.
Second, segmentation will not tell you which event fired. The CONVERSION_TAGS segmentation is documented as compatible with the WEB_CONVERSION metric group only. Mobile conversions segment by age, gender, metro, region and platform, and that is the list. If you want installs split by event rather than by audience, you read the 23 metrics individually, because each metric is already one event type.
The entity matrix adds a third limit that catches people late: MOBILE_CONVERSION exists at campaign, line item and promoted post level, and not at account level. Advertiser-wide install totals are something you add up, not something you request. That is the same shape as the spend problem covered in X Ads API campaigns.
Who should actually care
If you run app install campaigns on X and currently pay a measurement partner, the direct route is worth a look, with the gate question answered first by test rather than by reading. If you are a partner, nothing has changed except that your path is now explicitly labelled as the partner path.
If you do not advertise an app, this namespace is not your problem, and the broader lesson is the useful part. X's advertising documentation is now layered: a 2026 route sitting on top of reference pages that stopped being maintained years earlier, with the connecting conditions stated once and never repeated. The send side and the read side of the same product disagree on event names in four places. That is normal here, and it is why the only number you should trust is one you have seen come back from a live call.
Organic posting is a far smaller surface than any of this. X-Autopilot drafts and publishes from real Chrome on your own Mac, with the session cookie staying on the machine, which is a smaller detection surface than a cloud tool posting through a shared IP pool rather than an absence of risk. Browser automation on X is a gray area and not an approved route, unlike the Ads API, which is sanctioned and metered. For the sending side of conversions specifically, X Conversion API is the page that covers the web and app endpoints field by field.
The bottom line
Mobile conversions on X now have a partner-free way in and no documented confirmation that the partner-free way turns the reporting on. Send a test event, request the metric group, and find out before you build. Then read the app event tags to see what windows X is actually crediting, because they are the only numbers in this namespace that are both authoritative and readable from code.
Frequently asked
Answers indexed by Google + AI assistants.
What is MACT in the X Ads API?+
Mobile App Conversion Tracking, X's name for the partner path that reports app installs and in-app events. A mobile measurement partner posts each event to POST https://ads-api.x.com/12/conversion_event with the app id, the conversion type, a timestamp and an HMAC_SHA-256 hash of the device advertising id, and X answers with the attribution it claims for that conversion. MACT also appears as a gate on reporting: X states that mobile conversion stats are available only to advertiser accounts enabled for it.
Can I report app installs to X without a mobile measurement partner?+
Yes, since 29 October 2026. The Conversion API for App Events accepts POST /12/accounts/:account_id/measurement/app_conversions with an X-App-Conversion-Token header generated in Events Manager, up to 500 conversions per request. You connect the app under Tools, Events manager, Manage App Events, X App Conversion API. What you give up is the attribution response: that route returns a count and a debug id, not the campaign that drove the install.
Why are my MOBILE_CONVERSION metrics empty?+
Check the gate before the code. X documents MOBILE_CONVERSION and LIFE_TIME_VALUE_MOBILE_CONVERSION as available only to advertiser accounts enabled for MACT, so an account that was never enabled returns nothing however correct the request is. After that, the usual three: the metric group has to be requested on its own rather than alongside ENGAGEMENT, mobile conversion metrics exist only at campaign, line item and promoted post level and not at account level, and the event has to be a type with a metric, which is not true of every type the API accepts.
How do I change the attribution window on an X app event?+
Not through the API. The Ads API exposes app event tags as two read endpoints, GET accounts/:account_id/app_event_tags and the single-tag variant, with no create or update route, so post_engagement_attribution_window and post_view_attribution_window are readable and not writable. Connecting an app through the Conversion API for App Events creates the Install event with a 14-day post-engagement window and a 1-day post-view window, and X says you change those later in Events Manager.
What does the X conversion_event endpoint return?+
A conversion record plus an attribution verdict. The twitter_attribution node is always present and is null when X claims nothing. When X does claim the conversion, the node carries country_code, engagement_time, engagement_type of CLICK or VIEW, attribution_type, a promoted_properties object with campaign_id, line_item_id, line_item_objective, publisher_app_id and account_id, and the post id. A separate tpn_attribution node appears for X Audience Platform attribution, and the overview page X links for it no longer resolves.
Does the X Ads API have mobile conversion metrics at account level?+
No. The entity and metric-group matrix gives MOBILE_CONVERSION and LIFE_TIME_VALUE_MOBILE_CONVERSION three rows only: CAMPAIGN, LINE_ITEM and PROMOTED_TWEET. ACCOUNT gets ENGAGEMENT alone and FUNDING_INSTRUMENT adds BILLING. Install totals for an advertiser have to be summed from campaigns yourself.
- X developer docs, 'Mobile Conversions': the MACT overview and its statement that the page is for mobile measurement partners, POST conversion_event on ads-api.x.com/12 with its 20-value conversion_type enum, the required hashed_device_id as an HMAC_SHA-256 IDFA or AdID, the click_window and view_through_window values and defaults, the example twitter_attribution and tpn_attribution response, and the two read-only app_event_tags endpoints with post_engagement_attribution_window and post_view_attribution_window (accessed 17 November 2026)
- X developer docs, 'Conversion API for App Events': the POST /12/accounts/:account_id/measurement/app_conversions route, the X-App-Conversion-Token header shown once, the 500-conversion cap, the identifier rules for device_id, hashed_email, hashed_phone_number and ip_address with user_agent, the Events Manager setup steps, the 14-day post-engagement and 1-day post-view windows created with the Install event, and the conversions_processed and debug_id response (accessed 17 November 2026)
- X developer docs, 'Analytics': the entity and metric-group matrix, the 23 MOBILE_CONVERSION metrics and 15 LIFE_TIME_VALUE_MOBILE_CONVERSION metrics, the statement that both are available only to advertiser accounts enabled for MACT, the note that MOBILE_CONVERSION data should be requested separately, and the footnote limiting CONVERSION_TAGS segmentation to WEB_CONVERSION (accessed 17 November 2026)
- X API changelog, 'Conversion API for App Events' (29 October 2026): the dated launch of the direct app route, the header name, the 500-events-per-request limit, and the renaming of the website endpoint to Conversion API for Web
- X developer docs, Ads API index 'llms.txt': the Measurement section listing AB Testing, the GTM server-side guide, Mobile Conversions and Web conversions, with no entry for the Conversion API for App Events page (accessed 17 November 2026)
- X developer docs, Ads API 'Error codes and responses': MACT_APP_NOT_FOUND as the single MACT-specific constant in the Ads API error table, returned with HTTP 404 (accessed 17 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 →