> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Auto-tagged links

> The four UTM tags Apostra adds to the landing page of each creative it sends to a seller, so Google Analytics and other site analytics can tell which buy and creative a visit came from, who wins when you set your own, and how to turn them off.

When a visitor clicks one of your ads and lands on your site, your site analytics
can only tell you which buy and which creative sent them if the landing page
carries campaign tags. Apostra adds four standard UTM tags to the landing page of
each creative it sends to a seller for one of your media buys, so Google
Analytics and other tools that read UTM tags can show where each visit came from.

> [!NOTE]
>
> Auto-tagged links are in beta and are switched on per organization. Ask your
> Apostra contact to turn them on for your organization. Until they are on, your
> click URLs are exactly as you wrote them.

## The four tags

| Tag | Value | Why |
| - | - | - |
| `utm_source` | The channel the seller sells on. `chatgpt` for OpenAI Ads, `meta` for Meta, `google`, `linkedin`, `pinterest`, `reddit`, `snapchat`, `spotify`, `tiktok` and `amazon` for those platforms; for any other seller, the seller's platform id | Tells your analytics which channel sent the visit. |
| `utm_medium` | `paid` | Marks the visit as paid media. |
| `utm_campaign` | The media buy's `mb_` id, for example `mb_h3JSQJcL8L` | Ties a visit to one buy. It is the id Apostra shows you for the buy. |
| `utm_content` | The creative's id | Ties a visit to one creative. |

The tags carry Apostra ids and the seller's channel name. A creative's id can
include words from the creative's name, and visitors and anyone who sees the link
can read it, so name creatives accordingly. Apostra does not set `utm_term`, which
is yours to use, and does not add a seller's own click id (OpenAI's `oppref`, for
example).

## What you set always wins

Apostra's tags are the lowest layer. For each key, in this order, the first one
that names the key decides it:

1. A key already written into your landing page URL stays as you wrote it.
2. A click-URL parameter you set on the creative, the campaign or the advertiser
   replaces Apostra's tag with the same key. A `null` value for a key also keeps
   Apostra from adding that tag.
3. Apostra's own tag, for any of the four keys nothing above names.

So if you set your own `utm_source=newsletter`, you keep it and still get
`utm_medium`, `utm_campaign` and `utm_content` from Apostra. If you set your own
`utm_campaign`, Apostra cannot tie visits back to the buy by that tag.

## Turn the tags off

* **For one campaign:** set `autoUtm` to `false`. In V3 it is `tracking.autoUtm`
  on `save_campaign`, returned by `get` with `include: ["tracking"]`. In v2 it is
  `auto_utm` on `PUT /api/v2/buyer/campaigns/{campaignId}/tracking-config`. It is
  `true` unless you set it. `false` removes only Apostra's tags and leaves your own
  parameters alone.
* **For one tag:** set that key to `null` in the click-URL parameters of the
  advertiser, campaign or creative (V3 `tracking.macroAdditions` or `macroAdditions`
  on a creative). Setting all four to `null` turns every tag off.

For how click-URL parameters work in general, including the macros you can use in
their values, see [Click-URL parameters](https://docs.apostra.com/v2/object-guides/advertiser.md#click-url-parameters).

## When the tags are added

Apostra adds the tags when it sends a creative to a seller for a media buy. That
means a new buy, a re-sync, or a change to your click-URL parameters that re-sends
a creative.

* **A creative sent with no media buy is not tagged**, because the tags need a buy
  to name. A seller that creates the ad when the buy is placed carries the tags; a
  seller that already holds the creative from an earlier send does not until the
  creative is sent again for the buy.
* **A running ad keeps its URL.** Some sellers, OpenAI Ads among them, do not
  change a live ad when a creative is sent again. There is no backfill: a buy that
  was already live when your organization was switched on stays as it is until a
  creative for it is sent again.
* **A paired-redirect display tag is not tagged.**
* **Changing `autoUtm` does not re-send creatives** a seller already holds. It
  applies the next time a creative is sent.

## What the tags do to your link

If the creative runs through Apostra's click tracker, the tags go on your landing
page inside the tracker's destination, and the click redirect forwards the
destination unchanged. If you turned the click tracker off, the tags go on your
landing page URL directly. The click tracker counts clicks and your analytics
counts visits, so the two numbers can differ, for example when a visitor clicks
and leaves before the page loads.

The tags are added when a creative is sent, so the click-URL parameters you read
back, and a creative's `clickUrlTemplate`, show only what you set. They do not
list Apostra's tags.

## Which sellers carry the tags

Apostra sends the tagged landing page to every seller, direct integrations and
sales agents alike. Whether a seller's live ad keeps that exact URL is the
seller's behavior, and Apostra has not yet confirmed it seller by seller. To check
a live ad, click it and look at the landing page address, or look for the tags in
your analytics. OpenAI Ads accepts a landing page of up to 2,048 characters,
counting the click tracker and the tags; a longer one is refused with a clear
error on the creative.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.