X Ads

CLItrail sends each attributed install to the X Ads Conversions API as a conversion of your X pixel event, with the twclid of the ad click, so X can attribute installs to your campaigns and optimise for them.

#What you need

• Ads API access for your X developer app. Apply with X’s Ads API access form; the “Conversion only” tier is enough. The app needs Read and write permission.
• The app’s API key and secret (the consumer key and secret).
• An access token and secret for an X account with Ad Manager or Account Administrator access to the ads account that owns the pixel.
• The pixel ID and an event ID from X Events Manager.
• A Standard or Enterprise plan.

#Set it up

1. #Get Ads API access

   In the X Developer Console, open your app and apply for Ads API access. Wait for the approval before you generate tokens: tokens generated earlier don’t work with the Ads API.

2. #Copy the keys and tokens

   Open Apps → your app → Keys and tokens. Copy the API Key and Secret, then generate the Access Token and Secret for the X account that owns the app. An access token starts with that account’s numeric ID and a hyphen.

3. #Find the pixel and event IDs

   In X Ads (ads.x.com), open Tools → Events Manager. The ID of your X Pixel event source is the pixel ID, such as o8z6j. In that event source choose Add events, set up an install event with the Conversion API, and copy its event ID, such as o87ne or tw-o8z6j-o87ne.

4. #Add the destination

   In CLItrail, open Destinations → Add destination → X Ads and paste the pixel ID, the event ID and the four credentials. Set the click attribution window to the one your event uses in Events Manager. There is no “Connect with X”: the values are pasted, sealed and never shown again.

5. #Test, then go live

   Send test sends X a signed request with an empty list of conversions: X checks the credentials, and nothing can be recorded. Going live needs the confirmation of X’s conversion tracking policies and a verified domain.

#Settings

#What is sent

{
  "conversions": [{
    "conversion_time": "2026-09-23T14:02:11.000Z",
    "event_id": "o87ne",
    "identifiers": [{ "twclid": "26l6412g5p4iyj65a2oic2ayg2" }],
    "conversion_id": "clt_f399d6357f61bcf15f9370c69a41662457de8a05",
    "value": 1,
    "price_currency": "USD"
  }]
}

• Authentication. Every request is signed with OAuth 1.0a (HMAC-SHA1) from the four credentials, as X’s Ads API requires. The Authorization header appears as [redacted] in Logs.
• Click ID. The website tag reads twclid from the landing URL, or from the _twclid cookie X’s pixel sets, and dates it by when it landed. It is sent exactly as captured, never hashed. Your attribution policy picks the most recent or earliest click. An install needs a twclid on a touch within the click window; otherwise nothing is queued for X.
• No other identifiers. X accepts an IP address or user agent only beside another identifier, and CLItrail keeps no email address, phone number or raw IP address, so twclid is the only one sent.
• Deduplication. conversion_id is stable for each install. X deduplicates a Conversion API conversion against your X pixel’s event with the same event and conversion_id received within 48 hours. X does not document deduplication between two API sends, so CLItrail resends only requests that X answered with an error or never answered, and stops at 48 hours.
• Version. CLItrail calls version 12 of the Ads API. When X announces another current version or a deprecation, the delivery notes it.

#Delivery

• Up to 500 conversions go in one request. X allows 60,000 events per ad account every 15 minutes; CLItrail keeps each account under that and waits when X’s x-rate-limit-* or x-account-rate-limit-* headers say the budget is spent.
• Timeouts, network failures, 408, 423, 429 and 5xx answers are retried with the same conversion_id, up to 8 attempts, and only within 48 hours of the first send. A timeout can hide a request X did process, so a resend after one may count twice; a request X answered with success is never resent.
• A refused credential (401, 403) keeps the queue, tried about once an hour, until you paste new values. A 400 refuses the whole request, so each conversion is then sent on its own to find the one X refuses.
• A success answer says how many conversions X processed, and gives a debug_id for X support. When X processes fewer than it received without saying which, those deliveries are marked uncertain and never resent.
• Queued conversions expire after 90 days, the longest attribution window X offers.

#Common errors

X shows a new event as tracking in Events Manager within 12 to 24 hours of its first conversions.