Query Change History

Query audit summaries grouped by transaction across a specified time range.

URL

POST https://api.ads.apple.com/v1/change-history/query

Header Parameters

Name	Type	Description
`X-Ap-Context` Required	string

Response Codes

Status	Reason	Type	Description
200	OK Content-Type: application/json	`AuditSummaryResponse`	Successful operation. Returns AuditSummaryResponse (`result`: array of AuditSummary).
400	Bad Request Content-Type: application/json	`Error`	Bad Request. Returns ErrorMessage.
401	Unauthorized Content-Type: application/json	`Error`	Unauthorized.
403	Forbidden Content-Type: application/json	`Error`	Forbidden.
404	Not Found Content-Type: application/json	`Error`	Not Found. Returns ErrorMessage.
429	Too Many Requests Content-Type: application/json	`Error`	Rate Limit Exceeded. Returns ErrorMessage.
500	Internal Server Error Content-Type: application/json	`Error`	Internal Server Error. Returns ErrorMessage.

Discussion

This endpoint returns one AuditSummary row per (userType, modifiedBy, transactionId, eventType, entityType) combination. The count field on each row indicates how many individual field changes that transaction group contains.

To fetch field-level details via GET /v1/change-history/{detailId} (Get Change History Detail), you need a composite detailId in the form EntityType.entityId.txnId. A summary row alone doesn’t include entityId, so set options.metadata to latest or snapshot on the query request: each resulting row’s metas array then includes a ready-to-use detailId you can pass directly to the detail endpoint.

See AuditOperator for the full set of supported comparison operators.

Request Body

Filters

The following fields support filtering. For non-time fields, the API supports only EQUALS and IN. It reserves GREATER_THAN, LESS_THAN, and BETWEEN for eventTime.

Field	Operators	Notes
`eventTime`	`BETWEEN`, `GREATER_THAN`, `LESS_THAN`	Required. ISO 8601 date strings. Maximum lookback is 6 months. `BETWEEN` requires two values. `GREATER_THAN` and `LESS_THAN` take one.
`entityType`	`IN`	Not a closed enum. A string matching the name of the API entity that changed, such as `Campaign`, `AdGroup`, `Keyword`, `NegativeKeyword`, `Ad`, `Creative`, `AdAccount`, `Org`, or `LocationGroup`. See Change History Endpoints for the entity types this endpoint reports on.
`entityId`	`EQUALS`, `IN`	The specific entity that changed.
`eventType`	`IN`	`CREATE`, `UPDATE`, `DELETE`
`userType`	`IN`	`CUSTOMER`, `CUSTOMER_API`, `APPLE_SUPPORT`
`userId`	`EQUALS`, `IN`	The user who made the change.
`txnId`	`EQUALS`, `IN`	Transaction ID. Matches `transactionId` in response rows.
`adAccountId`	`EQUALS`, `IN`	Available when `entityType` is `Campaign` or `AdGroup`.
`campaignId`	`EQUALS`, `IN`	Available when `entityType` is `AdGroup`, `Keyword`, or `NegativeKeyword`.
`adGroupId`	`EQUALS`, `IN`	Available when `entityType` is `Keyword` or `NegativeKeyword`.

Sorting

Sort by any filterable field using field and order (ASC or DESC). Default sort is by eventTime descending.

The options object controls response performance and metadata behavior.

Option	Values	Default	Description
`needTotals`	`"true"`, `"false"`	`"true"`	Include total row count in the response pagination object. Set to `"false"` to skip the COUNT query for faster responses on large datasets.
`timeZone`	`"UTC"`, `"ORTZ"`	`"UTC"`	Timezone for `eventTime` filter values. `ORTZ` converts filter values from the org’s configured timezone to UTC server-side.
`metadata`	`"none"`, `"latest"`, `"snapshot"`	`"none"`	Controls entity metadata in change detail responses. `"none"` returns no metadata. `"latest"` joins current entity metadata. `"snapshot"` uses metadata captured at the time of the event.

Payload Examples

HTTP Body

An AuditQuery object specifying filter fields, sorting, pagination, and options. Every request requires a time-range filter on eventTime. Use BETWEEN for a bounded range or GREATER_THAN or LESS_THAN for an open-ended range.