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

Get Change History

Returns a paged list of change-history rows visible to the calling user within the specified ad account. Each row aggregates the field-level audits of one logical save into a single event with resolved entity name, classified actor, and translated field labels.

Access control:

Requires a qualifying role on the ad account (admin, contributor, or viewer).
actor.email is null for non-admin callers.
Rows whose change_category is BILLING are excluded for non-admin callers.

Retention: results are constrained to a rolling 180-day window. The created_gte parameter is clamped up to the floor when older.

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 admin-only and silently ignored for non-admin callers.
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). 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 the change history rows.
Default: sort_field=TIMESTAMPAllowed values: "TIMESTAMP", "ENTITY_TYPE", "PRINCIPAL_TYPE"

Response

A paged list of change-history rows.

- page_sizeinteger [int32]
- total_resultsinteger [int32]
- offsetinteger [int32]
- current_pageinteger [int32]
One logical change event: an actor's save, possibly spanning multiple field changes, on a single entity.
- 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. Anchored to the earliest field-level audit log within the change. ISO 8601 / UTC.
  Example: "2026-04-23T04:56:07Z"
- entity_typestring
  Required
  Customer-visible subset of entity types that emit change history events.
  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 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
  Type of principal (USER or SERVICE).
  Example: "USER"
  namestring
  Display name for the actor. For SUPPORT actors a generic label is shown.
  Example: "Jane Doe"
  emailstring
  Nullable
  Email address of the actor. Populated only for admin callers (ad-account-admin, business-admin); 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 (role memberships, access groups). Spotify employees acting on behalf of the advertiser resolve to SUPPORT and their identity is never exposed. Not used for filtering; use PrincipalType to filter by actor type.
  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
  Coarse change-category bucket. BILLING events are excluded entirely for non-admin callers.
  Allowed values: "STATUS", "BUDGET", "TARGETING", "CREATIVE", "SCHEDULING", "SETTINGS", "BILLING"Example: "BUDGET"
  JSON object representing the field state before the change.
  supports free form additional properties
  JSON object representing the field state after the change.
  supports free form additional properties

Response sample

{  "paging": {    "page_size": 50,    "total_results": 2,    "offset": 0  },  "change_history": [    {      "change_id": "d936ecbb-3a93-4cfa-b756-c61811c6cdc3",      "timestamp": "2026-04-23T14:32:07Z",      "entity_type": "CAMPAIGN",      "entity_id": "5bbc4fec-c9a5-4fc6-98f4-e950f40b74c7",      "entity_name": "Summer Promo Campaign",      "operation": "CHANGED",      "actor": {        "principal_id": "user123",        "principal_type": "USER",        "name": "Jane Doe",        "email": "jane@example.com",        "category": "ADVERTISER_USER"      },      "changes": [        {          "field_type": "name",          "display_label": "Campaign Name",          "change_category": "SETTINGS",          "before": {            "value": "Summer Promo"          },          "after": {            "value": "Summer Promo Campaign"          }        },        {          "field_type": "status",          "display_label": "Status",          "change_category": "STATUS",          "before": {            "value": "PAUSED"          },          "after": {            "value": "ACTIVE"          }        }      ]    },    {      "change_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",      "timestamp": "2026-04-22T09:15:43Z",      "entity_type": "AD_SET",      "entity_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",      "entity_name": "Audio - US 18-35",      "operation": "CHANGED",      "actor": {        "principal_id": "api-client-456",        "principal_type": "SERVICE",        "name": "Ad Platform API",        "email": null,        "category": "API_INTEGRATION"      },      "changes": [        {          "field_type": "budget",          "display_label": "Budget",          "change_category": "BUDGET",          "before": {            "micro_amount": 500000000,            "currency": "USD",            "type": "DAILY"          },          "after": {            "micro_amount": 750000000,            "currency": "USD",            "type": "DAILY"          }        }      ]    }  ]}