Ad UTM Tagging

Overview

Attribution, channel grouping and the Constraint Finder read the UTMs a paid click arrives with. Campaign joins use utm_id. Ad joins use utm_content and the numeric ad_id, adset_id and campaign_id on the landing URL. Ads launched without them lose that attribution.

Ad UTM tagging checks ads in the campaigns you choose. It finds missing or wrong parameters and sets them.

1. Store a Meta Marketing API token for the client.
2. Pick the ad account. Save the template, overwrite policy and filters.
3. Run a preview. Nothing is written to Meta.
4. Apply selected ads or approve automatic checks.

Base URL

https://mythic-analytics.gulp.workers.dev/client/v1/ad-tagging

The same key system as the rest of /client/v1: an agency key (ak_, which must bind a location on every request with ?location_id= or the X-Location-Id header) or a location secret key (sk_, auto-scoped to its own location). An agency key that binds no location returns 400 location_required; one that names a location it is not linked to returns 403 location_not_linked.

A location secret key (sk_) can read the config and run history. All other operations need an agency key or an mcp_ key with the applicable ad_tagging:read or ad_tagging:write scope. This includes listing ad accounts and running previews.

This surface is sold by tier. If your plan does not include it, every endpoint answers 402 feature_not_in_plan — the key is valid, the tier is what is missing. GET /client/v1/agency/quota lists what your plan includes.

Off switches work on every plan. These are PUT /meta with only enabled: false and/or auto_enabled: false, POST /meta/auto with only enabled: false, DELETE /meta, and cancelling a run.

1. Store a token

Mythic needs a token that can read and edit the client's ads. A Meta destination uses a dataset-scoped Conversions API token. That token cannot read or edit ads.

curl -X PUT "https://mythic-analytics.gulp.workers.dev/client/v1/destinations/credentials/meta_ads?location_id=LOC" \
  -H "Authorization: Bearer ak_..." -H "Content-Type: application/json" \
  -d '{"credential_value": "EAA..."}'

Test it with GET /meta/ad-accounts. An invalid token returns 409 credential_invalid. Missing account access returns 409 insufficient_permission. The message explains the fix. The optional credential_name query uses the saved name, or default if no config exists.

2. Save a config

curl -X PUT "https://mythic-analytics.gulp.workers.dev/client/v1/ad-tagging/meta?location_id=LOC" \
  -H "Authorization: Bearer ak_..." -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "act_1234567890",
    "enabled": true,
    "overwrite": "fill_missing",
    "ad_statuses": ["ACTIVE", "PAUSED", "IN_REVIEW"],
    "short_links": false,
    "resolve_names": true,
    "auto_interval_minutes": 15,
    "rules": {
      "operator": "AND",
      "conditions": [
        { "type": "campaign_name_contains", "value": "XYZ" },
        { "type": "campaign_created_on_or_after", "value": "2026-01-01" }
      ]
    }
  }'

One ad account belongs to one client. A second client claiming it gets 409 ad_account_in_use. When the holder is in your agency, the message names it and error.details.client gives its location_id and name. A holder in another agency is never named. Free the account by removing ad tagging (or its token) from the holder. PUT /meta is partial. Omitted fields keep their saved values. The defaults below apply on creation.

Options and filters reference

Use this reference for API clients and custom settings screens. GET /meta returns data.defaults.utm_template, macros, overwrite_policies, ad_statuses and rule_types. Use those returned enums where available. It also returns auto_interval_minutes: {min: 5, max: 1440, step: 5, default: 15}, resolve_names: true and name_macros in data.defaults. Other enums below are defined by this API reference.

Config fields

auto_enabled is controlled by POST /meta/auto. PUT /meta accepts auto_enabled: false only. It is not a way to approve auto mode. Unknown config fields are rejected.

The fingerprint covers the account, template, overwrite policy, ad statuses, rules, short_links and resolve_names. It excludes enabled, credential_name and auto_interval_minutes.

Changes to fingerprint fields bump revision, void earlier previews, cancel queued or running runs and revoke auto approval. Changes to enabled or credential_name also bump the revision and invalidate earlier previews and runs. They do not themselves change the fingerprint. An unchanged save does not bump the revision.

An interval-only edit preserves the revision, previews, runs and auto approval. If the same save changes another field, that field's normal invalidation rules apply. Turning only auto mode off cancels auto runs without invalidating manual previews.

The config has an immutable generation UUID. Deleting and recreating it creates a new generation. Even identical settings and the same revision cannot reuse a preview from before the reconnect.

Template and macros

The default template is:

utm_source=facebook&utm_medium=paid&utm_campaign={{campaign.name}}{{mythic.bid_suffix}}&utm_id={{campaign.id}}&utm_content={{ad.id}}&utm_term={{adset.name}}&campaign_id={{campaign.id}}&adset_id={{adset.id}}&ad_id={{ad.id}}

facebook and paid classify clicks as Paid Social. Keep utm_id={{campaign.id}} and ad_id={{ad.id}} for campaign and ad attribution.

All nine macros are returned by GET /meta in data.defaults.macros:

Bid structure in utm_campaign

The default template appends {{mythic.bid_suffix}} to the campaign name, so a campaign named HC | Leads on a campaign budget with Highest volume reports as utm_campaign=HC | Leads | cbo.hv.

Mythic always fills this macro, with or without resolve_names, because Meta cannot. Its value is kept current like a name: switching the bid strategy rewrites the campaign's ads, and automatic checks leave delivering ads to a manual apply (names_outdated_delivering). Cap and goal amounts are not included, because they change often and each change would rewrite every ad and start a new utm_campaign value in your reports. Remove the macro from the template to leave the bid structure out.

Overwrite policy

Mythic manages only the template's keys. Unmanaged parameters stay in their existing order.

Keys are compared after percent decoding. A managed key repeated on an ad collapses to its first position during a merge. fill_missing does not swap a creative just to remove duplicates. An ad whose parameters need no change is not written unless its destination still needs shortening.

Ad statuses

GET /meta returns all three selections in data.defaults.ad_statuses. A new config selects all three.

An ad in review has no delivery or learning history yet. Tagging it restarts review. A swapped ad can be IN_PROCESS on the next scan. It is still eligible when IN_REVIEW is selected. Correct tags produce already_correct, so the scan does not swap it again unless a destination still needs shortening.

Campaign rules

rules.version is 1. rules.operator is AND by default. AND requires all conditions to match. OR requires at least one. Empty conditions includes every campaign. The maximum is 20 conditions.

Each condition has type and value. case_sensitive is optional for name rules only. It defaults to false.

Campaign statuses are separate from ad statuses. The status rule uses campaign status, with effective_status as a fallback when status is absent. Unknown rule fields are rejected.

All referenced campaign fields must be readable before either AND or OR is evaluated. Missing or unknown names, dates or statuses fail closed. A matching branch of OR cannot authorize a write if another branch needs unreadable data. Negative name rules also fail closed.

Current names instead of name macros

Meta fills {{campaign.name}}, {{adset.name}} and {{ad.name}} with the name the ad had when it was first published. Renaming a campaign, ad set or ad does not change the URL, and a duplicated ad reports the original's name.

With resolve_names: true (the default), Mythic writes each ad's current names as literal, URL-encoded values instead. utm_campaign={{campaign.name}} becomes utm_campaign=Spring%20Sale on that ad. ID macros and {{placement}}/{{site_source_name}} stay macros because Meta always fills them correctly.

• Kept current. Keys whose template value uses a name macro are refreshed under either overwrite policy. A duplicate that still carries the original's name is rewritten, and so is a name macro typed into Ads Manager. A hand-set value on such a key is replaced too. To keep one, remove the key from the template or set resolve_names: false.
• Renames rewrite the ad. Each rename means a new creative and a swap, which restarts Meta review. Automatic checks fix outdated names only on ads that are not delivering: paused, in review, or scheduled (ACTIVE but the ad set's start time is still ahead). That is where new duplicates are. A delivering ad whose only change is a name is skipped as names_outdated_delivering. A manual apply fixes it.
• Checked before writing. Mythic re-reads the ad's names before each write. If a name changed after the preview, the row becomes stale instead of writing the old name.

With resolve_names: false, name macros are written as macros.

Preview overrides

POST /meta/preview accepts only rules, utm_template, overwrite, ad_statuses, short_links and resolve_names. It does not accept account, enabled, credential or interval overrides. Overrides do not save settings. If the effective fingerprint differs, applies_to_saved_config is false. Save those settings and preview again before applying or approving auto mode.

Short links and link_changes

With short_links: true, Mythic checks main links, call-to-action links, carousel card links and video call-to-action links. Each destination gets its own short link. Readable absolute HTTP or HTTPS URLs without Meta macros can be shortened. Destination URLs must be at most 2048 characters.

Mythic keeps this client's existing short links. Otherwise it reuses the oldest enabled, unexpired link to the same URL with UTM passthrough on. If none exists, it creates one during apply or auto mode. New links appear in the client's Links with a title like Meta ads: <host><path>. Previews never create links.

Existing-post creatives marked link_unverified only get tags. Their links are not shortened. A destination that still needs shortening has action set even when url_tags_after equals url_tags_before.

link_changes is null when there is no link plan. Otherwise it is an array:

For example, a preview can return this plan:

[
  { "from": "https://links.example.com/r/current", "action": "keep", "slug": "current" },
  {
    "from": "https://example.com/landing",
    "action": "reuse",
    "to": "https://links.example.com/r/landing",
    "slug": "landing"
  },
  { "from": "https://example.com/new-page", "action": "create" }
]

Each entry requires from and action. Other fields are optional.

A resolved link does not confirm the ad swap. Before each swap, every short link must still be enabled, unexpired and unchanged. Its redirect must be stored. It must route to this active client. A failed check leaves the ad on its current creative. Link-store failures retry up to three times. A new link can take up to a minute to reach every Cloudflare location.

A key=pk_... parameter selects the client before the hostname does. Without it, the hostname selects the client. Short URLs use https://<active custom hostname>/r/<slug>. Otherwise they use <Mythic origin>/r/<slug>?key=<publishable key>. The client needs an active custom hostname or a publishable key. Any key with ad_tagging:write can create these links. They point only at pages already used by the client's ads.

Decisions and reasons

action is set or skip. A normal set has no reason. All decision reasons are listed below. Later journal rows may carry stale or cancellation reasons instead.

Change statuses

Journal reason also accepts these stale and cancellation reasons. These are not additional discovery decisions.

Run kinds

Run statuses

Query filters and pagination

GET /meta/ad-accounts accepts optional credential_name. It uses the config's credential name when omitted, otherwise default if no config exists.

GET /meta/runs lists runs newest first. Its optional kind filter accepts preview, apply or auto. Omit it for all kinds. limit defaults to 20 and is clamped to 1 through 100.

GET /meta/runs/{id} returns run, changes and next_cursor. The optional status filter accepts any change status above, not a run status. limit defaults to 200 and is clamped to 1 through 500. Send the returned next_cursor as cursor for the next page. Omit it for the first page. Null means the last page. Keep the same status filter while paging. Changes sort by campaign ID, ad ID and row ID. Invalid filters return invalid_kind or invalid_status. An invalid cursor returns invalid_cursor.

Runs expose config_generation, config_revision, config_fingerprint and the read-only config_auto_approval_epoch fence. They also expose journal_ready and snapshots of statuses, rules, template, overwrite and short links. Counters include scanned, planned, applied, failed, uncertain, skipped and stale ads. A published journal is required before a run can be applied or processed. Config responses expose generation, revision, fingerprint, approval, cooldown, last run and last automatic check fields.

run_slot is the read-only reserved timestamp on an auto run. It is not used for other kinds. It replaces run_date. The old last_auto_date config field is removed. No particular absent-value representation is guaranteed for run_slot.

Auto runs journal only set ads. Skipped ads are counted in ads_skipped but have no auto change rows. Use a manual preview to inspect skipped decisions. No-op or failed scans do not create runs.

Last automatic check

The config exposes these read-only fields. They describe the last check, not the final outcome of a queued run.

These fields are read-only. A missing scan timestamp or error detail is not proof that a scan or write succeeded. See the errors tables below for known codes.

Errors

Public route failures use {success: false, error: {code, message, details?}}. Numeric statuses below are HTTP statuses for route responses, not change or run statuses. Graph, credential, storage and setup codes can also appear in Run.error_code, Change.error_code or a failed automatic check. A journal or worker-only code has no HTTP status unless noted. Not every code applies to every endpoint.

Public route errors

Journal and scan codes

last_auto_status is an open set of named scan outcomes and error codes. Known scan errors include credential_required, credential_invalid, insufficient_permission, upstream_throttled, upstream_timeout, upstream_error, upstream_malformed, invalid_request, short_links_unavailable, storage_failed, concurrent_update, run_changed and discovery_failed. Preconditions can also stop or defer work with the cancellation or deferral codes above, config_changed, config_disabled, location_disabled, feature_not_in_plan or writes_disabled. The ErrorCode schema catalogs known source-backed codes, but all error-code fields allow other strings for future or upstream codes. Inspect the accompanying message or last_auto_error rather than assuming an unknown code is success.

3. Preview

curl -X POST "https://mythic-analytics.gulp.workers.dev/client/v1/ad-tagging/meta/preview?location_id=LOC" \
  -H "Authorization: Bearer ak_..."

Mythic reads matching campaigns, ads and creatives. The preview is stored for 24 hours. It writes nothing to Meta.

See Decisions and reasons for every set and skip outcome.

Large accounts and Meta rate-limit warnings can truncate discovery. The preview has status: incomplete and truncated: true. Narrow the rules if needed. A published truncated preview can be applied to listed ads. Auto approval requires a complete preview.

4. Apply

curl -X POST "https://mythic-analytics.gulp.workers.dev/client/v1/ad-tagging/meta/apply?location_id=LOC" \
  -H "Authorization: Bearer ak_..." -H "Content-Type: application/json" \
  -d '{"preview_id": "...", "ad_ids": ["120200000000000001"], "acknowledge_creative_swap": true}'

Meta stores URL parameters on an immutable creative. Mythic creates a copy, then points the ad at it. Ads can share a copy when the original creative, tags and resolved link changes match. Select up to 2000 distinct ad IDs from set items in the preview.

Apply returns 202 with a run ID. Processing starts right away. Ads are processed one at a time, each taking several seconds of Meta calls; what is left continues every five minutes, for up to four minutes at a time. Only one apply or auto run per ad account can run at a time. Another returns 409 run_in_progress.

The preview must be published (journal_ready: true) and under 24 hours old. It must match the config generation, revision and fingerprint. The config must be enabled.

Before creative creation and again before the swap, Mythic reads fresh account, effective ad status, campaign rules and original creative data. Changed or missing eligibility data makes the row stale. Failed reads never authorize writes.

Before swapping, Mythic reads back the copy and compares it with a fresh original. Checks cover full story content, text, media, calls to action, carousel content, links, post identity, creative settings and planned parameters. Shared and recovered copies are checked too. Missing or changed content fails closed with creative_copy_mismatch. No swap follows a failed verification.

Follow the per-ad journal using the change statuses in the reference above.

Retryable reads have a budget of three failures. Backoff is 5 minutes, then 10 minutes before the next attempt. Permanent read failures exhaust the budget immediately. read_failures and next_read_at expose this state. An exhausted unresolved write stays uncertain with read_retry_exhausted. Automatic retries stop, even after next_read_at passes. The run ends partial after other work finishes. Check the ad in Ads Manager. Uncertainty does not mean the write failed. Mythic considers at most one write retry after readback.

Cancel with POST /meta/runs/{id}/cancel. Cancellation prevents later swaps but cannot recall sent writes. Already-tagged ads stay tagged. The account stays reserved until the worker quiesces and releases it, or its lease expires plus a 30-second grace period. A replacement run may still get run_in_progress while waiting.

Meta cooldowns are stored in throttled_until. Eligible work resumes afterward. Delayed or shorter responses cannot shorten an existing cooldown.

Automatic checks

curl -X POST "https://mythic-analytics.gulp.workers.dev/client/v1/ad-tagging/meta/auto?location_id=LOC" \
  -H "Authorization: Bearer ak_..." -H "Content-Type: application/json" \
  -d '{"enabled": true, "preview_id": "...", "acknowledge_creative_swap": true}'

Auto approval needs a complete, published, unexpired preview of the enabled saved config. It binds to generation, revision and fingerprint. Reconnecting cannot reuse old approval. Changes to fingerprint fields revoke approval. An interval-only edit does not.

Choose auto_interval_minutes with PUT /meta. It is an integer from 5 to 1440 in steps of 5. The default is 15 minutes. Cron checks due configs every five minutes. It takes up to 10 configs per tick within a time budget, oldest due first. Busy, skipped and failed checks consume capacity too. Large rosters and Meta cooldowns can stretch the interval.

Follow queued work in run history. Use a manual preview if you need to inspect skipped ads. The run journal fields and last automatic check fields distinguish scans from write runs.

Auto mode skips link_unverified ads and delivering ads whose only change is an outdated name (names_outdated_delivering). It uses the same fresh eligibility and full copy checks as apply. Turn it off with {"enabled": false}. This cancels auto runs only.

Live writes switch

GET /meta returns data.writes_enabled. When false, previews work, apply returns 503 writes_disabled and queued runs are not processed. Auto approval can still be saved. auto_enabled: true then means approval is pending global activation. It does not mean ads are being changed.

Follow a run

Use GET /meta/runs to find recent work, then GET /meta/runs/{id} to read its status and per-ad journal. Keep fetching with next_cursor until it is null. The query filters and pagination, run statuses and errors are defined in the reference above.

Endpoints

Every route is in the Ad Tagging reference group. See the endpoint pages for schemas. The MCP server has matching tools, including preview_meta_ad_tagging and apply_meta_ad_tagging. See MCP tools.

Graph-backed preview and account reads share a limit of 10 requests per minute per client. Other tagging routes allow 120 per minute per client. Rate-limit responses include Retry-After.