Tracking Pixels

Tracking pixels fire on an artist's smart link pages so ad platforms can attribute traffic and build retargeting audiences. Pixels are attached to an artist and apply across that artist's links.

Unlike opt-ins, pixels are fully read/write through the API.

Supported providers

The provider value is validated on insert. These are the accepted values:

provider	Platform
Facebook	Meta (Facebook / Instagram)
TikTok	TikTok
Google	Google
AdWords	Google Ads
Twitter	X / Twitter
Snapchat	Snapchat

Values are case-sensitive. Anything else is rejected with permission-error.

Listing pixels

query Pixels($artist_id: uuid!) {
  pixels(where: { artist_id: { _eq: $artist_id } }) {
    id
    provider
    pixel
    conversion_tag
    artist_id
    agency_id
  }
}

Fields

Field	Type	Description
id	uuid!	Pixel ID.
artist_id	uuid	Artist whose links fire this pixel.
provider	String	One of the supported values above.
pixel	String	The pixel/tag ID from the ad platform.
conversion_tag	String	Conversion label or event tag, where the platform uses one.
access_token	String	API token for server-side conversion reporting, e.g. Meta's Conversions API.
agency_id	uuid	Set when an agency, rather than the artist's own account, owns the pixel.

WARNING

access_token is a live credential for the ad platform. It is readable through this field, so treat any response containing it as a secret: do not log it, do not cache it in a browser, and do not expose it to client-side code.

Adding a pixel

mutation AddPixel($pixel: pixels_insert_input!) {
  insert_pixels_one(object: $pixel) {
    id
    provider
    pixel
    artist_id
  }
}

Variables:

{
  "pixel": {
    "artist_id": "3aad8009-a307-4429-a586-8b3dbe39cdda",
    "provider": "Facebook",
    "pixel": "1234567890123456"
  }
}

Insertable columns: artist_id, agency_id, provider, pixel, conversion_tag, access_token.

Two conditions must hold or the insert is rejected: the artist must be one you manage (or agency_id must be your own user ID), and provider must be a supported value.

With a server-side conversions token

{
  "pixel": {
    "artist_id": "3aad8009-...",
    "provider": "Facebook",
    "pixel": "1234567890123456",
    "access_token": "EAAG...",
    "conversion_tag": "Lead"
  }
}

Updating a pixel

mutation UpdatePixel($id: uuid!, $changes: pixels_set_input!) {
  update_pixels_by_pk(pk_columns: { id: $id }, _set: $changes) {
    id
    provider
    pixel
    conversion_tag
  }
}

Updatable columns: pixel, conversion_tag, access_token.

provider and artist_id cannot be changed after creation — delete the pixel and create a new one instead.

Removing a pixel

mutation DeletePixel($id: uuid!) {
  delete_pixels_by_pk(id: $id) {
    id
    provider
  }
}

The pixel stops firing immediately. Data already collected by the ad platform is unaffected — it lives on the platform side.

Agency pixels

An agency managing several artists can own a pixel directly by setting agency_id to its own user ID. Agency-owned pixels are visible to the agency across every artist it manages:

query AgencyPixels($agency_id: uuid!) {
  pixels(where: { agency_id: { _eq: $agency_id } }) {
    id
    provider
    pixel
    artist { id name }
  }
}

Your visibility rule is: pixels for artists you manage, or pixels whose agency_id is you.

Domain verification

Meta and Google require the domain serving your links to be verified before conversion events are attributed. Set the verification tokens on the domain record first — see Domain verification — then attach the pixel.

Pixels on vibe.to and listen.to work without this, since those domains are already verified by ArtistHub.

Auditing coverage

Find artists with no pixel configured:

query Coverage {
  artists {
    id
    name
    pixels { id provider }
  }
}

An empty pixels array means that artist's links are not reporting to any ad platform.