Change History

Spotify Ads API — Change History

Retrieve a paginated timeline of changes made to campaigns, ad sets, creatives, and other entities within an ad account. Useful for auditing who changed what, tracking budget modifications, reviewing status changes, and understanding campaign activity over time.

Setup

Set the plugin root and define the request wrapper:

PLUGIN_ROOT="${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}"
api() { "$PLUGIN_ROOT/scripts/api-request.sh" change-history "$@"; }

Before the first Ads API v3 call, read and follow $PLUGIN_ROOT/skills/api-reference/references/live-openapi.md.

To retrieve settings values (TOKEN, AD_ACCOUNT_ID, AUTO_EXECUTE, BASE_URL, SDK_HEADER, SKILL_HEADER, PLUGIN_VERSION) for use outside API calls, run api --env. The output is eval-safe, so eval $(api --env) assigns them all.

Endpoint

GET /ad_accounts/{ad_account_id}/change_history

Results are constrained to a rolling 180-day retention window.

Query Parameters

Operations

Interpret the user's natural language request to determine the right query. Build query parameters from their intent.

list (default if no argument)

Show recent changes for the configured ad account.

api GET "ad_accounts/{ad_account_id}/change_history?limit=20&sort_direction=DESC"

Format the output as a table: Timestamp | Entity Type | Entity Name | Operation | Category | Actor

Filtered queries

Map the user's request to query parameters:

• "what changed today" → created_gte set to today at 00:00:00 UTC
• "budget changes last week" → change_category=BUDGET + created_gte set to 7 days ago
• "who changed campaign X" → entity_type=CAMPAIGN + entity_name=X
• "changes by user@example.com" → actor_ids with the user's principal ID
• "status changes this month" → change_category=STATUS + created_gte set to start of month
• "show me ad set changes" → entity_type=AD_SET
• "what did the API change" → principal_type=SERVICE

Build the query string from the mapped parameters:

api GET "ad_accounts/{ad_account_id}/change_history?entity_type=CAMPAIGN&change_category=BUDGET&created_gte=2026-07-01T00:00:00Z&limit=50&sort_direction=DESC"

Pagination

If total_results exceeds the page size, offer to fetch the next page:

api GET "ad_accounts/{ad_account_id}/change_history?offset=50&limit=50&sort_direction=DESC"

Detail view

When the user asks about a specific change, fetch it by ID:

api GET "ad_accounts/{ad_account_id}/change_history?change_ids=$CHANGE_ID"

Display the full change record including before/after values for each changed field.

Response Format

Each change record contains:

• change_id — Unique identifier for the change event
• timestamp — When the change was made
• entity_type — What was changed (CAMPAIGN, AD_SET, etc.)
• entity_id — ID of the changed entity
• entity_name — Name of the changed entity
• operation — Type of change: CREATED, CHANGED, REMOVED
• actor — Who made the change:
  • name — Display name
  • principal_type — USER or SERVICE
  • category — ADVERTISER_USER, SUPPORT, API_INTEGRATION, SYSTEM, UNKNOWN
• changes — Array of field-level changes:
  • field_type — Internal field identifier
  • display_label — Human-readable field name
  • change_category — Category of the change
  • before — Previous value (null for CREATED operations)
  • after — New value (null for REMOVED operations)

Display Guidelines

• Format timestamps in the user's local timezone when possible, otherwise show UTC with a note
• Show before → after values for CHANGED operations, highlighting what specifically changed
• For CREATED operations, show the initial values set
• Group changes by entity when showing a timeline view
• Summarize large result sets: "42 changes found — showing the 20 most recent"
• When the user asks "how many," return a count from total_results without listing every record

Execution Behavior

• If auto_execute is true, execute the curl command directly.
• If auto_execute is false, present the curl command to the user and ask for confirmation before executing.
• Always display the API response in a readable format.
• Always check the HTTP_STATUS: line from curl output to determine success or failure before interpreting the response body.
• On error (non-2xx response), show the error message from the response body. Never automatically retry requests.