---
title: AuditQuery
framework: Apple Ads Platform API
role: symbol
role_heading: Object
platforms: [apple ads platform api 1.0+]
path: apple-ads-platform-api/auditquery
---

# AuditQuery

Request body for the Query Change History endpoint.

## Declaration

```data
object AuditQuery
```

## Properties

filters: An array of filter conditions applied to the audit log. Every request requires a filter on eventTime. Use BETWEEN for a bounded range or GREATER_THAN or LESS_THAN for an open-ended range. Requests that omit this filter return a 400 Bad Request error. Additional filters on entityType, eventType, and userType narrow results further and can be combined in a single request. Each entry is an AuditFilter object with field, operator, and value keys. See the Filterable Field table below. sorting: An array of sort directives. Each entry is an AuditSorting object specifying a field name and an order of ASC or DESC. When you omit this array, the API sorts results by eventTime descending. pagination: Controls the page offset and page size for the response. See Pagination. Uses offset (zero-based row index) and pageSize (maximum rows per page, must be ≥ 1). options: A flat key-value map of additional query controls. See AuditQuery.Options. All keys and values are strings. See the Option Key table below.

## Overview

Overview The AuditQuery object is the request payload for POST /v1/change-history/query (Query Change History). 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: {   "filters": [     {       "field": "eventTime",       "operator": "BETWEEN",       "value": [         "2025-03-01",         "2025-03-31"       ]     }   ],   "pagination": {     "offset": 0,     "pageSize": 50   } }  |  |   |  |   |  |   |  |   |  |   |  |   |  |   |  |   |  |   |  |   |  |   |  |  |   |  |  |   |  |  |   |  |  |  Discussion Required Filter {   "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: {   "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): {   "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: {   "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

- [AuditQuery.Options](apple-ads-platform-api/auditquery/options-data.dictionary.md)

## See Also

- [AuditFilter](apple-ads-platform-api/auditfilter.md)
- [AuditSorting](apple-ads-platform-api/auditsorting.md)
- [Pagination](apple-ads-platform-api/pagination.md)