Query Ad Groups
Query ad groups using filters, sorting, and pagination.
URL
POST https://api.ads.apple.com/v1/adgroups/queryHeader Parameters
| Name | Type | Description |
|---|---|---|
X-Ap-Context Required | string |
Response Codes
| Status | Reason | Type | Description |
|---|---|---|---|
| 200 | OK Content-Type: application/json | AdGroupQueryResponse | |
| 400 | Bad Request Content-Type: application/json | ErrorResponse | |
| 401 | Unauthorized Content-Type: application/json | ErrorResponse | |
| 403 | Forbidden Content-Type: application/json | ErrorResponse | |
| 404 | Not Found Content-Type: application/json | ErrorResponse | |
| 429 | Too Many Requests Content-Type: application/json | ErrorResponse | |
| 500 | Internal Server Error Content-Type: application/json | ErrorResponse |
Discussion
This endpoint queries ad groups using a standard QueryRequest body. Filter by campaignId to scope results to a specific campaign. An empty request body returns all non-deleted ad groups across all campaigns in the ad account with default pagination.
Each result in the response includes the full targeting and bidStrategy nested objects, making this the primary endpoint for auditing ad group configuration at scale.
See QueryFilterOperator for the full set of supported comparison operators.
Filterable Fields
Field | Type | Operators | Sortable | Description |
|---|---|---|---|---|
| integer |
| Yes (default) | The unique identifier for the ad group. |
| integer |
| Yes | The campaign this ad group belongs to. |
| string |
| Yes | The advertiser-given name of the ad group. |
| string (enum) |
| Yes | Advertiser-configurable status. See Adgroupstatus. |
| string (ISO 8601) |
| Yes | Ad group schedule start time. |
| string (ISO 8601) |
| Yes | Ad group schedule end time. |
| boolean |
| Yes | Whether the ad group has been deleted. |
The request body is a QueryRequest composed of QueryFilter conditions and QuerySort directives (QuerySortOrder), controlled by QueryPagination.