Spotify Ads API — Measurement Debug
Find the failing layer before recommending a change. Read troubleshooting.md before diagnosing.
Setup
PLUGIN_ROOT="${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}"
api() { "$PLUGIN_ROOT/scripts/api-request.sh" measurement-debug "$@"; }
Before the first Ads API v3 call, read and follow $PLUGIN_ROOT/skills/api-reference/references/live-openapi.md.
Measurement paths use business_id. Discover it with GET businesses when absent.
Triage
Capture:
- expected event, expected volume, first/last known good time, timezone, and affected environment
- Pixel, CAPI, or both; direct code, web GTM, server GTM, or another owner
- business, dataset, integration, connection, and ad-account IDs
- whether the problem is receipt, deduplication, sharing/selection, or attributed reporting
- a sanitized failing request/response and trace ID when available
Do not ask for CAPI tokens, raw email/phone, cookies, device IDs, IP addresses, or production payloads. Ask for redacted field names and error metadata instead.
Read-only audit
1. Resolve topology
api GET "businesses/<business_id>/pixels?include_events=true"
api GET "businesses/<business_id>/capi/<capi_connection_id>"
api GET "businesses/<business_id>/datasets"
api GET "businesses/<business_id>/datasets/<dataset_id>"
api GET "businesses/<business_id>/ad_accounts/<ad_account_id>/datasets"
The GET datasets endpoint does not accept limit or offset parameters. The GET pixels endpoint may return 403 for some businesses; if so, check the pixel field on individual dataset responses instead.
Only call GET businesses/<business_id>/capi/<capi_connection_id>/tokens when the incident specifically requires token inventory. The response includes active token values, not just IDs: treat the entire raw response as secret, never show it in a command result or transcript, and expose only redacted token IDs/counts in the final audit.
Verify that:
- the expected integration is in the expected dataset
- the dataset is shared to the intended ad account
- each integration's
dataset_id field points to the correct dataset (a null value means events are ingested but not routed — see isolation table)
- Pixel domain and CAPI connection ID match the intended environment/business
- when authentication is in scope, the token ID exists on the same CAPI connection; never display token values
- dataset flags such as
is_receiving_events and is_receiving_lead_events fit the symptom
2. Inspect event receipt
api GET "businesses/<business_id>/datasets/<dataset_id>/diagnostics?granularities=HOURLY"
api GET "businesses/<business_id>/datasets/<dataset_id>/diagnostics?granularities=DAILY"
api GET "businesses/<business_id>/datasets/<dataset_id>/diagnostics?granularities=HOURLY&datasource_ids=<datasource_id>"
Compare each datasource's event names, counts, timestamps, and last_activity_ms. Convert timestamps explicitly and state the timezone. Use hourly data for recent incidents and daily data for trend comparison.
Receipt diagnostics answer “did Spotify receive events?” They do not prove trigger correctness, identifiers, deduplication, campaign data-source selection, or attribution.
3. Isolate the layer
| Observation |
Likely layer |
Next check |
| No source receives events |
implementation/network |
base code or server request, auth, CSP, container, endpoint |
| Pixel absent, CAPI present |
browser |
base code, trigger, duplicate install, CSP, redirects |
| CAPI absent, Pixel present |
server |
token/connection pair, payload, 4xx/5xx logs, server GTM container |
| Both present, total inflated |
deduplication |
same real event uses same event_id on both sources |
| Diagnostics present, campaign metrics absent |
selection/attribution |
dataset shared and selected; date/window/privacy/report fields |
| Wrong site/account receives data |
topology/config |
domain, business, dataset membership, connection ID |
| Events stopped suddenly |
deployment/credential |
release time, GTM publish, token revocation, CSP/infrastructure change |
Integration in dataset but dataset_id null |
dataset routing |
integration was moved via POST datasets with multiple integration_ids; events are ingested but not routed — fix by removing the integration and re-adding it to a properly-linked dataset |
4. Inspect implementation evidence
If the user supplies a public page, browser access, GTM export, or sanitized CAPI example, inspect it read-only:
- Pixel: compare pixel key and base/event code with Ads Manager; search direct installs for
spdt; inspect console/network/CSP; verify event fires only at the intended action.
- Do not conclude Pixel is absent merely because source HTML lacks
spdt; tag managers can inject it at runtime.
- Confirm the site is not using both direct and GTM installs.
- Verify redirects preserve Spotify's
spclid query parameter.
- Web GTM is for Pixel; CAPI GTM requires a server container.
- CAPI: validate envelope, event enum, unique stable event ID, ISO 8601 time, at least one identifier, SHA-256 normalization, optional source URL/action source, and revenue fields.
Never expose secrets or personal data in findings.
Mutating tests and fixes
Default to a remediation plan. Ask for explicit confirmation immediately before:
- submitting any CAPI event, including a test event
- creating/revoking a token
- changing Pixel/CAPI/dataset metadata
- sharing/unsharing a dataset
- moving an integration between datasets
A test event changes measurement data. Prefer replaying a legitimate known event in a non-production integration with a stable unique event_id, and label/document it. Never blindly replay a production POST after a timeout or 5xx.
For source-code or GTM changes, provide the smallest isolated change and an acceptance test; do not claim the Ads API can deploy website or GTM code.
Attribution boundary
If receipt is healthy but reporting is not:
- verify the dataset is shared to and selected by the relevant campaign/ad set
- verify the report date range, entity, and conversion field
- distinguish total received event activity from attributed conversions
- account for attribution windows and privacy thresholding
- route reporting extraction to the
report skill
Do not “fix” healthy ingestion to force attributed numbers to match internal analytics.
Incident report
Return:
- symptom and affected scope
- topology diagram in one line: business → dataset → source(s) → ad account
- evidence table with check, result, timestamp/timezone, and confidence
- most likely failing layer and alternatives
- exact remediation by owner
- safe verification steps and wait period
- redacted trace IDs/errors for escalation
Label facts, inferences, and unverified assumptions separately. If the issue remains unresolved, recommend Spotify Ads API support with client ID, endpoint, sanitized request/response, timestamp, and sp_trace_id.
Guardrails
- Begin read-only.
- Wait at least 20 minutes after new event activity before diagnosing empty Ads Manager diagnostics.
- Never request, echo, or store CAPI secrets or personal identifiers.
- Never automatically retry POST, PATCH, or DELETE.
- On 4xx, preserve the sanitized error and stop; on ambiguous POST failure, check receipt/resource state before any retry.
1---2name: measurement-debug3description: Diagnose existing Spotify Ads Pixel, Conversions API (CAPI), and dataset implementations when events are missing, stale, duplicated, unexpectedly high or low, not deduplicated, attached to the wrong account, or present in diagnostics but absent from campaign reporting. Use for Pixel/CAPI troubleshooting, event-delivery audits, token/connection mismatches, source comparison, or measurement incident triage. Prefer read-only checks and never create test conversions without explicit confirmation.4---56# Spotify Ads API — Measurement Debug78Find the failing layer before recommending a change. Read [troubleshooting.md](references/troubleshooting.md) before diagnosing.910## Setup1112```bash13PLUGIN_ROOT="${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}"14api() { "$PLUGIN_ROOT/scripts/api-request.sh" measurement-debug "$@"; }15```1617Before the first Ads API v3 call, read and follow `$PLUGIN_ROOT/skills/api-reference/references/live-openapi.md`.1819Measurement paths use `business_id`. Discover it with `GET businesses` when absent.2021## Triage2223Capture:2425- expected event, expected volume, first/last known good time, timezone, and affected environment26- Pixel, CAPI, or both; direct code, web GTM, server GTM, or another owner27- business, dataset, integration, connection, and ad-account IDs28- whether the problem is **receipt**, **deduplication**, **sharing/selection**, or **attributed reporting**29- a sanitized failing request/response and trace ID when available3031Do not ask for CAPI tokens, raw email/phone, cookies, device IDs, IP addresses, or production payloads. Ask for redacted field names and error metadata instead.3233## Read-only audit3435### 1. Resolve topology3637```bash38api GET "businesses/<business_id>/pixels?include_events=true"39api GET "businesses/<business_id>/capi/<capi_connection_id>"40api GET "businesses/<business_id>/datasets"41api GET "businesses/<business_id>/datasets/<dataset_id>"42api GET "businesses/<business_id>/ad_accounts/<ad_account_id>/datasets"43```4445The `GET datasets` endpoint does not accept `limit` or `offset` parameters. The `GET pixels` endpoint may return 403 for some businesses; if so, check the `pixel` field on individual dataset responses instead.4647Only call `GET businesses/<business_id>/capi/<capi_connection_id>/tokens` when the incident specifically requires token inventory. The response includes active token values, not just IDs: treat the entire raw response as secret, never show it in a command result or transcript, and expose only redacted token IDs/counts in the final audit.4849Verify that:5051- the expected integration is in the expected dataset52- the dataset is shared to the intended ad account53- each integration's `dataset_id` field points to the correct dataset (a `null` value means events are ingested but not routed — see isolation table)54- Pixel domain and CAPI connection ID match the intended environment/business55- when authentication is in scope, the token ID exists on the same CAPI connection; never display token values56- dataset flags such as `is_receiving_events` and `is_receiving_lead_events` fit the symptom5758### 2. Inspect event receipt5960```bash61api GET "businesses/<business_id>/datasets/<dataset_id>/diagnostics?granularities=HOURLY"62api GET "businesses/<business_id>/datasets/<dataset_id>/diagnostics?granularities=DAILY"63api GET "businesses/<business_id>/datasets/<dataset_id>/diagnostics?granularities=HOURLY&datasource_ids=<datasource_id>"64```6566Compare each datasource's event names, counts, timestamps, and `last_activity_ms`. Convert timestamps explicitly and state the timezone. Use hourly data for recent incidents and daily data for trend comparison.6768Receipt diagnostics answer “did Spotify receive events?” They do not prove trigger correctness, identifiers, deduplication, campaign data-source selection, or attribution.6970### 3. Isolate the layer7172| Observation | Likely layer | Next check |73|---|---|---|74| No source receives events | implementation/network | base code or server request, auth, CSP, container, endpoint |75| Pixel absent, CAPI present | browser | base code, trigger, duplicate install, CSP, redirects |76| CAPI absent, Pixel present | server | token/connection pair, payload, 4xx/5xx logs, server GTM container |77| Both present, total inflated | deduplication | same real event uses same `event_id` on both sources |78| Diagnostics present, campaign metrics absent | selection/attribution | dataset shared and selected; date/window/privacy/report fields |79| Wrong site/account receives data | topology/config | domain, business, dataset membership, connection ID |80| Events stopped suddenly | deployment/credential | release time, GTM publish, token revocation, CSP/infrastructure change |81| Integration in dataset but `dataset_id` null | dataset routing | integration was moved via `POST datasets` with multiple `integration_ids`; events are ingested but not routed — fix by removing the integration and re-adding it to a properly-linked dataset |8283### 4. Inspect implementation evidence8485If the user supplies a public page, browser access, GTM export, or sanitized CAPI example, inspect it read-only:8687- Pixel: compare pixel key and base/event code with Ads Manager; search direct installs for `spdt`; inspect console/network/CSP; verify event fires only at the intended action.88- Do not conclude Pixel is absent merely because source HTML lacks `spdt`; tag managers can inject it at runtime.89- Confirm the site is not using both direct and GTM installs.90- Verify redirects preserve Spotify's `spclid` query parameter.91- Web GTM is for Pixel; CAPI GTM requires a server container.92- CAPI: validate envelope, event enum, unique stable event ID, ISO 8601 time, at least one identifier, SHA-256 normalization, optional source URL/action source, and revenue fields.9394Never expose secrets or personal data in findings.9596## Mutating tests and fixes9798Default to a remediation plan. Ask for explicit confirmation immediately before:99100- submitting any CAPI event, including a test event101- creating/revoking a token102- changing Pixel/CAPI/dataset metadata103- sharing/unsharing a dataset104- moving an integration between datasets105106A test event changes measurement data. Prefer replaying a legitimate known event in a non-production integration with a stable unique `event_id`, and label/document it. Never blindly replay a production POST after a timeout or 5xx.107108For source-code or GTM changes, provide the smallest isolated change and an acceptance test; do not claim the Ads API can deploy website or GTM code.109110## Attribution boundary111112If receipt is healthy but reporting is not:1131141. verify the dataset is shared to and selected by the relevant campaign/ad set1152. verify the report date range, entity, and conversion field1163. distinguish total received event activity from attributed conversions1174. account for attribution windows and privacy thresholding1185. route reporting extraction to the `report` skill119120Do not “fix” healthy ingestion to force attributed numbers to match internal analytics.121122## Incident report123124Return:125126- symptom and affected scope127- topology diagram in one line: business → dataset → source(s) → ad account128- evidence table with check, result, timestamp/timezone, and confidence129- most likely failing layer and alternatives130- exact remediation by owner131- safe verification steps and wait period132- redacted trace IDs/errors for escalation133134Label facts, inferences, and unverified assumptions separately. If the issue remains unresolved, recommend Spotify Ads API support with client ID, endpoint, sanitized request/response, timestamp, and `sp_trace_id`.135136## Guardrails137138- Begin read-only.139- Wait at least 20 minutes after new event activity before diagnosing empty Ads Manager diagnostics.140- Never request, echo, or store CAPI secrets or personal identifiers.141- Never automatically retry POST, PATCH, or DELETE.142- On 4xx, preserve the sanitized error and stop; on ambiguous POST failure, check receipt/resource state before any retry.
spotify