Pixel & Analytics
Install the X Pixel, send conversion events and read ad analytics.
X Pixel
Create and read an ad account's X Pixel, manage its conversion events through the platform-neutral tracking tags API on your xads account, check whether each event is tracking, and install the pixel on a connected Shopify store or WordPress site.
The X Pixel is the ad account's universal website tag, and X allows one per ad account, so:
| Field | Value |
|---|---|
tagId | The X ad account id (for example 18ce54d4x5t) |
siteTagId | The pixel id (the universal website tag's id), what twq('config') loads |
events | The account's conversion events (web event tags; the ones X auto-creates with the pixel are left out), each with type (PURCHASE, ADD_TO_CART, ...), status, clickWindowDays, viewWindowDays and siteEventId = tw-<pixel>-<event>, the id twq('event') and the Conversions API send |
const { data } = await zernio.trackingtags.getTrackingTag({
path: { accountId: '66b2e19d8c3f5a7e9d0b1c2d', tagId: '18ce54d4x5t' }
});Response (200):
{
"platform": "xads",
"tag": {
"id": "18ce54d4x5t",
"siteTagId": "o8z1q",
"name": "X Pixel o8z1q",
"platform": "xads",
"kind": "pixel",
"status": "active",
"code": "<!-- X conversion tracking base code -->\n<script>...twq('config','o8z1q');</script>",
"lastFiredTime": 1804150800,
"installed": true,
"ownerAdAccountId": "18ce54d4x5t",
"events": [
{ "id": "14cgjq", "siteEventId": "tw-o8z1q-rg1cq", "name": "Purchase", "type": "PURCHASE", "status": "TRACKING", "siteEvent": "purchase", "clickWindowDays": 30, "viewWindowDays": 1 }
]
}
}status is active when any of the account's web event tags is TRACKING, and lastFiredTime is the most recent last_tracked_at across them. A per-tag call on an ad account without a pixel answers 400: create one first.
| Operation | Behavior |
|---|---|
| List | One pixel per ad account on the connection; adAccountId scopes it to one. |
Stats (GET .../stats) | One row per web event tag with eventId, name, type, autoCreated, status and lastTrackedTime. X exposes no per-pixel or per-event counts, only campaign WEB_CONVERSION metrics. |
Create (POST .../tracking-tags) | Creates the ad account's pixel (adAccountId = the X ad account id) with first-party cookies on. name is not stored, since X pixels have no name. An account that already has a pixel answers 409 without writing: X allows one and cannot delete it. |
Update (PATCH .../tracking-tags/{tagId}) | firstPartyCookieStatus only, first_party_cookie_enabled or first_party_cookie_disabled (the pixel's allow_1p_cookie). |
Conversion events (.../events) | List, create, update and delete. Fields: name, type (X's event type, such as PURCHASE, SIGN_UP, CUSTOM) or siteEvent, clickWindowDays (1, 7, 14, 30, 60 or 90) and viewWindowDays (0, 1, 7, 14, 30, 60 or 90, no longer than the click window). A create defaults to 30 and 1 days with retargeting on, as Events Manager does, and is not idempotent. Delete is permanent. The events X auto-created with the pixel cannot be changed or deleted (400). |
| Share | 501: an X Pixel belongs to exactly one ad account, and X has no share endpoint. |
| Diagnostics, users and partners | 501. |
| Delete | Not offered: DELETE on a website tag answers 405 at X. |
| Install | Shopify and WordPress. WordPress gets X's uwt.js base code, whose twq('config') is the page view. Shopify sends the page view and each event that has a matching conversion event (the most recently tracked one of a type wins) to analytics.twitter.com/1/i/adsct in uwt.js's own request shape (reverse-engineered: X documents only the legacy image pixel), with conversion_id = the event id so X deduplicates against the Conversions API, and the twclid click id kept first-party. |
Analytics
Call GET /v1/ads/{adId}/analytics with the ad's _id for spend, impressions, clicks, CTR, CPC and CPM over a date range (Get ad analytics).
curl "https://zernio.com/api/v1/ads/66f0a1b2c3d4e5f6a7b8c9d0/analytics?fromDate=2027-01-04&toDate=2027-01-11" \
-H "Authorization: Bearer $ZERNIO_API_KEY"Response (200), trimmed:
{
"ad": { "id": "66f0a1b2c3d4e5f6a7b8c9d0", "name": "Q2 product awareness", "platform": "twitter", "status": "active", "currency": "USD" },
"analytics": {
"summary": { "spend": 421.7, "impressions": 203800, "clicks": 3140, "ctr": 1.54, "cpc": 0.13, "cpm": 2.07, "engagement": 5820 },
"daily": [ { "date": "2027-01-04", "spend": 59.8, "impressions": 29100, "clicks": 448 } ]
}
}X reports reach as 0, because Zernio does not sync it, and the demographic breakdowns parameter is Meta and TikTok only. GET /v1/ads/tree rolls the same metrics up per campaign and line item (Get campaign tree).