# 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](https://clitrail.com/docs/domain-verification).

> Warning
> 
> X’s Conversions API has no test events: every conversion it processes counts. A wrong pixel or event ID, or missing Ads API access for the pixel’s account, shows up only when the first install is sent. Read the prepared requests under **Install events** while in test mode.

## Settings

| Field | Format |
| --- | --- |
| Pixel ID | 2 to 16 letters and digits, the ID of your X Pixel event source. |
| Event ID (install completed) | The event’s ID, alone or as `tw-<pixel id>-<event id>`. An event of another pixel is refused (`x_event_pixel_mismatch`). |
| Event ID (first run) | Optional: a second event of the same pixel, so first runs never count as installs. Without it, first runs are not sent to X. |
| Click attribution window | 1, 7, 14 (X’s default), 30, 60 or 90 days. Installs later than this after the X ad click are not sent. |
| API key, API key secret, access token, access token secret | As X shows them. |
| Value and currency | Optional. A value and a 3-letter currency code. |

## What is sent

```json
{
  "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](https://clitrail.com/docs/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 says | What to check |
| --- | --- |
| `401`, code `89` or `UNAUTHORIZED_ACCESS` | The keys or tokens are wrong or revoked, or the tokens were generated before Ads API approval. Generate new ones and paste them. |
| `403` `UNAUTHORIZED_CLIENT_APPLICATION` | The app has no Ads API access yet. |
| `403` `READONLY_CLIENT_APPLICATION` | Give the app Read and write permission, then generate a new access token and secret. |
| `403` `ACTION_NOT_ALLOWED` | The token’s account needs Ad Manager or Account Administrator access to the pixel’s ads account. |
| `404` | Check the pixel ID and event ID in Events Manager. |
| Code `135` | X judged the request’s signing time too far from its clock. It is retried. |

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