Retargeting pixels (Business+)

Attach advertising retargeting pixels to your short links so visitors who click can be added to your ad audiences. You register a pixel once (per ad platform), then attach it to any number of links. When a Business+ owner's link has pixels, the redirect serves a short JavaScript interstitial that fires the pixels and then forwards the visitor to the destination.

Managing pixels requires links:write. Pixels are a Business+ feature — requests from lower tiers return 403.

Supported providers

provider	Platform
meta	Meta / Facebook Pixel
google_ads	Google Ads
linkedin	LinkedIn Insight Tag
tiktok	TikTok Pixel
twitter	X / Twitter Pixel

Register a pixel

curl -X POST https://api.short.leonai.io/api/v1/pixels \
  -H "X-API-Key: $LEONAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "meta",
    "pixelId": "1234567890",
    "name": "Main Meta Pixel",
    "enabled": true
  }'

Response (201 Created):

{
  "success": true,
  "data": {
    "id": "pix_...",
    "provider": "meta",
    "pixelId": "1234567890",
    "name": "Main Meta Pixel",
    "enabled": true,
    "createdAt": "2026-07-11T12:00:00.000Z"
  }
}

REST: POST /api/v1/pixels. Manage pixels with GET /api/v1/pixels, PATCH /api/v1/pixels/:id, and DELETE /api/v1/pixels/:id.

Attach pixels to a link

A link can carry up to 20 pixels. Set the full list with PUT:

# See which pixels are attached
curl https://api.short.leonai.io/api/v1/links/<linkId>/pixels \
  -H "X-API-Key: $LEONAI_API_KEY"

# Replace the attached set
curl -X PUT https://api.short.leonai.io/api/v1/links/<linkId>/pixels \
  -H "X-API-Key: $LEONAI_API_KEY" -H "Content-Type: application/json" \
  -d '{ "pixelIds": ["pix_1", "pix_2"] }'

REST: GET /api/v1/links/:linkId/pixels and PUT /api/v1/links/:linkId/pixels.

How the redirect behaves

When a Business+ owner's link has one or more enabled pixels attached, the redirect no longer returns a bare 302. Instead it serves a small GPC-aware JavaScript interstitial that:

1. Checks the visitor's consent signal (see below).
2. If tracking is allowed, fires each attached pixel.
3. Forwards the visitor to the destination URL.

Links without pixels — and links owned by non-Business+ accounts — keep the fast direct redirect.

Consent & Global Privacy Control (Sec-GPC)

Pixel firing is consent-aware. If the request carries the Sec-GPC: 1 header (the Global Privacy Control opt-out signal sent by privacy-respecting browsers), the interstitial skips firing the pixels and forwards the visitor straight through. This keeps retargeting compliant with GDPR/CCPA opt-outs without any extra configuration on your side. Visitors who have not opted out are retargeted normally.

Error codes

Status	When
400	Unknown provider, missing pixelId, or more than 20 pixelIds
403	Account is not on Business+ (feature gated)
404	Pixel or link not found / not owned by you

Related

• Links — the links these pixels attach to
• Billing — Business+ features
• API Reference — the full OpenAPI spec and Swagger UI