Ads API •References / change-history / Get Change History

Get Change History

Returns a paginated list of change-history rows within the specified ad account. Each row represents a single logical change event — an actor's save on one entity — with resolved entity name, classified actor identity, and translated field labels.

Results are constrained to a rolling 180-day retention window. The created_gte parameter defaults to 30 days ago and is clamped to the retention floor when older.

Use the filtering parameters to narrow results by entity type, entity name, actor, change category, or date range. The entity_name filter requires entity_type to also be specified.

Request

ad_account_idstring [uuid]
Required
A unique identifier for an Ad Account.
Example: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a
entity_typestring
Filter change history rows by entity type.
Allowed values: "CAMPAIGN", "AD_SET", "AD_ACCOUNT", "BUSINESS", "CREATIVE"Example: entity_type=CAMPAIGN
entity_idsarray of strings
Filter to a specific set of entity IDs within the requested ad account.
A unique identifier for the entity.
Example: entity_ids=ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a
entity_namestring
Case-insensitive substring match on entity name. Must be used together with entity_type. Resolves matching entities to IDs before querying the audit log, so the result set contains only changes for entities whose name contains this value.
Length between 2 and 255Example: entity_name=Summer%20Promo
change_idsarray of strings
A list of change IDs to fetch only the requested subset of changes.
A unique identifier for the entity.
Example: change_ids=ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a
actor_idsarray of strings
Filter to changes performed by these principal IDs.
principal_typestring
Filter to changes performed by actors of this principal type.
Allowed values: "USER", "SERVICE"Example: principal_type=USER
change_categorystring
Filter to a single change category. BILLING is only visible to admin callers (ad-account-admin or business-admin roles).
Allowed values: "STATUS", "BUDGET", "TARGETING", "CREATIVE", "SCHEDULING", "SETTINGS", "BILLING"Example: change_category=BUDGET
created_ltestring [date-time]
Return changes created on or before this timestamp (inclusive).
Example: created_lte=2026-12-31T23%3A59%3A59Z
created_gtestring [date-time]
Return changes created on or after this timestamp (inclusive). Defaults to 30 days ago. Clamped to the 180-day retention floor; values older than the floor are coerced to the floor.
Example: created_gte=2026-01-01T00%3A00%3A00Z
limitinteger
Limit or page size for a given response.
Default: limit=50Range: 1 - 50Example: limit=50
offsetinteger
Starting position of the next record to assist in data pagination.
Default: offset=0Example: offset=0
sort_directionstring
Field by which to order the results of the query.
Default: sort_direction=DESCAllowed values: "ASC", "DESC"Example: sort_direction=ASC
sort_fieldstring
Field by which to sort change history rows.
Default: sort_field=TIMESTAMPAllowed values: "TIMESTAMP", "ENTITY_TYPE", "PRINCIPAL_TYPE"

Response

A paginated list of change-history rows.

Required
- page_sizeinteger [int32]
- total_resultsinteger [int32]
- offsetinteger [int32]
- current_pageinteger [int32]
Required
One logical change event: an actor's save on a single entity, possibly spanning multiple field changes.
- change_idstring [uuid]
  Required
  A unique identifier for the entity.
  Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
- timestampstring [date-time]
  Required
  When the change was made (ISO 8601 / UTC). Anchored to the earliest field-level audit log within the change.
  Example: "2026-07-15T14:30:00Z"
- entity_typestring
  Required
  Entity types that emit change history events. BUSINESS returns business-level changes that affect the specified ad account.
  Allowed values: "CAMPAIGN", "AD_SET", "AD_ACCOUNT", "BUSINESS", "CREATIVE"Example: "CAMPAIGN"
- entity_idstring [uuid]
  Required
  A unique identifier for the entity.
  Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
- entity_namestring
  Required
  Display name for the entity at read time. Falls back to "Unnamed ENTITY_TYPE" when the name cannot be resolved.
  Example: "Summer Promo Campaign"
- operationstring
  Required
  Type of operation performed on the entity.
  Allowed values: "CREATED", "CHANGED", "REMOVED"Example: "CHANGED"
- Required
  Resolved actor identity for a change event.
  principal_idstring
  Required
  Identifier of the principal that performed the change.
  Example: "user123"
  principal_typestring
  Required
  Coarse actor classification used for filtering. USER represents advertiser-side actors (team members who log in). SERVICE represents Spotify-side actors (support staff, API integrations, automated systems).
  Allowed values: "USER", "SERVICE"Example: "USER"
  namestring
  Display name for the actor.
  Example: "Jane Doe"
  emailstring
  Nullable
  Email address of the actor. Populated only for admin callers (ad-account-admin or business-admin roles); null for all other roles.
  Example: "jane@example.com"
  categorystring
  Required
  Resolved actor classification returned on each change history row for display purposes. Derived from the principal type plus additional context.
  Allowed values: "ADVERTISER_USER", "SUPPORT", "API_INTEGRATION", "SYSTEM", "UNKNOWN"Example: "ADVERTISER_USER"
- Required
  One entry per field changed within this logical save.
  A single field change within a logical save event.
  field_typestring
  Required
  Internal field identifier as emitted by the audit layer.
  Example: "bidAmount"
  display_labelstring
  Required
  Human-readable label for the field. Falls back to the raw field_type for fields without an explicit translation.
  Example: "Bid Amount"
  change_categorystring
  Required
  Category of the change. BILLING events are only visible to admin callers (ad-account-admin or business-admin roles).
  Allowed values: "STATUS", "BUDGET", "TARGETING", "CREATIVE", "SCHEDULING", "SETTINGS", "BILLING"Example: "BUDGET"
  Nullable
  Field state before the change.
  supports free form additional properties
  Nullable
  Field state after the change.
  supports free form additional properties

Response sample

{  "paging": {    "page_size": 50,    "total_results": 1,    "offset": 0,    "current_page": 0  },  "change_history": [    {      "change_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",      "timestamp": "2026-07-15T14:30:00Z",      "entity_type": "CAMPAIGN",      "entity_id": "709076fe-2570-4dd9-94db-acc163e60fd8",      "entity_name": "Summer Promo Campaign",      "operation": "CHANGED",      "actor": {        "principal_id": "user123",        "principal_type": "USER",        "name": "Jane Doe",        "email": null,        "category": "ADVERTISER_USER"      },      "changes": [        {          "field_type": "name",          "display_label": "Name",          "change_category": "SETTINGS",          "before": {            "value": "Spring Promo Campaign"          },          "after": {            "value": "Summer Promo Campaign"          }        },        {          "field_type": "status",          "display_label": "Status",          "change_category": "STATUS",          "before": {            "value": "PAUSED"          },          "after": {            "value": "ACTIVE"          }        }      ]    }  ]}