# AuditQuery Request body for the Query Change History endpoint. ``` object AuditQuery ``` ## Overview The `AuditQuery` object is the request payload for `POST /v1/change-history/query` ([`Query Change History`](/documentation/Apple-Ads-Platform-API/Query-audit-summary-_-grouped-by-transaction)). Every valid request must include at least one `filters` entry targeting `eventTime` using `BETWEEN`, `GREATER_THAN`, or `LESS_THAN`. All other fields are optional and default to reasonable values when omitted. ### Example A minimal valid request looks like this: ```json { "filters": [ { "field": "eventTime", "operator": "BETWEEN", "value": [ "2025-03-01", "2025-03-31" ] } ], "pagination": { "offset": 0, "pageSize": 50 } } ``` |Filterable Field|Supported Operators |Accepted Values | |----------------|--------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |`eventTime` |`BETWEEN`, `GREATER_THAN`, `LESS_THAN`|ISO 8601 date strings, for example, `"2025-03-01"`. 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 for the entity types this endpoint reports on.| |`eventType` |`IN` |`CREATE`, `UPDATE`, `DELETE` | |`userType` |`IN` |`CUSTOMER`, `CUSTOMER_API`, `APPLE_SUPPORT` | |`campaignId` |`EQUALS`, `IN` |Campaign ID string(s). Available when `entityType` is `AdGroup`, `Keyword`, or `NegativeKeyword`. | |`adGroupId` |`EQUALS`, `IN` |Ad group ID string(s). Available when `entityType` is `Keyword` or `NegativeKeyword`. | |`userId` |`EQUALS`, `IN` |User ID string(s) | |`txnId` |`EQUALS`, `IN` |Transaction ID string(s) | |`entityId` |`EQUALS`, `IN` |The specific entity that changed. | |`adAccountId` |`EQUALS`, `IN` |Ad account ID string(s). Available when entityType is Campaign or AdGroup. | |Option Key |Accepted Values |Default |Description | |------------|----------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |`needTotals`|`"true"`, `"false"` |`"true"`|When `"true"`, the response `pagination.totalCount` reflects the full result set size. Set to `"false"` to skip the COUNT query for faster responses on large datasets. `pagination.totalCount` will then be `0`.| |`timeZone` |`"UTC"`, `"ORTZ"` |`"UTC"` |Controls how the API interprets `eventTime` filter values. `"UTC"` treats values as UTC. `"ORTZ"` interprets values in the org’s configured timezone and converts them to UTC server-side before filtering. | |`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. | ## Discussion ### Required Filter ```json { "field": "eventTime", "operator": "BETWEEN", "value": [ "2025-01-01", "2025-01-31" ] } ``` ### Combine filters The API combines multiple `filters` entries with logical AND. For example, to retrieve only `Campaign` `UPDATE` events in a time window: ```json { "filters": [ { "field": "eventTime", "operator": "BETWEEN", "value": [ "2025-03-01", "2025-03-31" ] }, { "field": "entityType", "operator": "IN", "value": [ "Campaign" ] }, { "field": "eventType", "operator": "IN", "value": [ "UPDATE" ] } ] } ``` To retrieve all changes within a specific campaign across any entity type (ad groups, keywords, ads): ```json { "filters": [ { "field": "eventTime", "operator": "BETWEEN", "value": [ "2025-03-01", "2025-03-31" ] }, { "field": "campaignId", "operator": "EQUALS", "value": "789012" } ] } ``` To retrieve changes made by a specific user across multiple ad groups: ```json { "filters": [ { "field": "eventTime", "operator": "BETWEEN", "value": [ "2025-03-01", "2025-03-31" ] }, { "field": "adGroupId", "operator": "IN", "value": [ "345678", "345679" ] }, { "field": "userId", "operator": "EQUALS", "value": "12345678" } ] } ``` ### Handle time zones When `timeZone` is `"ORTZ"`, the server converts the `eventTime` filter values from the org’s configured timezone to UTC before executing the query. The `eventTime` values returned in the response are always in UTC regardless of this setting. ### Performance Tips - Set `needTotals` to `"false"` on high-volume queries where you don’t need an accurate total count. Skipping the COUNT query can substantially reduce response latency. - Apply `entityType` and `eventType` filters to limit result set size before paginating. ## Topics ### Dictionaries [`object AuditQuery.Options`](/documentation/Apple-Ads-Platform-API/AuditQuery/Options-data.dictionary) A flat key-value map of additional query controls. --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)