<!--
{
  "availability" : [
    "Apple Ads Platform API: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Apple-Ads-Platform-API",
  "identifier" : "/documentation/Apple-Ads-Platform-API/POST-adgroups-query",
  "metadataVersion" : "0.1.0",
  "role" : "Web Service Endpoint",
  "symbol" : {
    "kind" : "Web Service Endpoint",
    "modules" : [
      "Apple Ads Platform API"
    ],
    "preciseIdentifier" : "rest:apple-ads-platform-api:post:adgroups-query"
  },
  "title" : "Query Ad Groups"
}
-->

# Query Ad Groups

Query ad groups using filters, sorting, and pagination.

## 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`](/documentation/Apple-Ads-Platform-API/QueryFilterOperator) for the full set of supported comparison operators.

### Filterable Fields

|Field       |Type             |Operators                  |Sortable     |Description                                                                                                                     |
|------------|:---------------:|:-------------------------:|:-----------:|--------------------------------------------------------------------------------------------------------------------------------|
|`id`        |integer          |`EQUALS`, `IN`             |Yes (default)|The unique identifier for the ad group.                                                                                         |
|`campaignId`|integer          |`EQUALS`                   |Yes          |The campaign this ad group belongs to.                                                                                          |
|`name`      |string           |`EQUALS`, `STARTS_WITH`    |Yes          |The advertiser-given name of the ad group.                                                                                      |
|`status`    |string (enum)    |`EQUALS`, `IN`             |Yes          |Advertiser-configurable status. See <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/AdGroupStatus>.|
|`startTime` |string (ISO 8601)|`LESS_THAN`, `GREATER_THAN`|Yes          |Ad group schedule start time.                                                                                                   |
|`endTime`   |string (ISO 8601)|`LESS_THAN`, `GREATER_THAN`|Yes          |Ad group schedule end time.                                                                                                     |
|`deleted`   |boolean          |`EQUALS`                   |Yes          |Whether the ad group has been deleted.                                                                                          |

The request body is a [`QueryRequest`](/documentation/Apple-Ads-Platform-API/QueryRequest) composed of [`QueryFilter`](/documentation/Apple-Ads-Platform-API/QueryFilter) conditions and [`QuerySort`](/documentation/Apple-Ads-Platform-API/QuerySort) directives ([`QuerySortOrder`](/documentation/Apple-Ads-Platform-API/QuerySortOrder)), controlled by [`QueryPagination`](/documentation/Apple-Ads-Platform-API/QueryPagination).

## Payload Examples

**Query by Campaign:**

Query all ad groups for a specific campaign, sorted by creation time descending.

### Request

```json
POST /v1/adgroups/query

{
 "filters": [
   {
     "field": "campaignId",
     "operator": "EQUALS",
     "value": 444555666
   }
 ],
 "sorting": [
   {
     "field": "creationTime",
     "order": "DESC"
   }
 ],
 "pagination": {
   "offset": 0,
   "pageSize": 20,
   "fetchTotalCount": true
 }
}
```

### Response

```json
{
 "result": [
   {
     "id": 555666777,
     "name": "AwayFinder iOS — New Users 18-34",
     "adAccountId": 123456789,
     "campaignId": 444555666,
     "pricingModel": "CPT",
     "status": "ENABLED",
     "systemStatus": "RUNNING",
     "startTime": "2025-09-01T00:00:00.000",
     "endTime": "2025-12-31T23:59:59.000",
     "targeting": {
       "deviceClass": {
         "include": [
           "IPHONE"
         ]
       },
       "minAge": {
         "include": [
           "18"
         ]
       },
       "maxAge": {
         "include": [
           "34"
         ]
       },
       "appDownloader": {
         "include": [
           "123456789"
         ]
       }
     },
     "automatedKeywordsOptIn": false,
     "deleted": false,
     "creationTime": "2025-01-10T08:00:00.000",
     "modificationTime": "2025-01-10T08:00:00.000"
   }
 ],
 "pagination": {
   "totalCount": 1,
   "offset": 0,
   "pageSize": 20
 }
}
```

**Filter by Status:**

Return only enabled ad groups for a specific campaign.

### Request

```json
POST /v1/adgroups/query

{
 "filters": [
   {
     "field": "campaignId",
     "operator": "EQUALS",
     "value": 444555668
   },
   {
     "field": "status",
     "operator": "EQUALS",
     "value": "ENABLED"
   }
 ],
 "pagination": {
   "offset": 0,
   "pageSize": 20,
   "fetchTotalCount": true
 }
}
```

### Response

```json
{
 "result": [
   {
     "id": 555666779,
     "name": "AwayFinder Maps — Nearby Search",
     "adAccountId": 123456789,
     "campaignId": 444555668,
     "pricingModel": "CPT",
     "status": "ENABLED",
     "systemStatus": "RUNNING",
     "startTime": "2025-09-01T00:00:00.000",
     "endTime": "2025-12-31T23:59:59.000",
     "bidStrategy": {
       "bidStrategyType": "MANUAL_CPT",
       "bidStrategyGoal": "TAP",
       "bid": {
         "amount": "5.00",
         "currency": "USD"
       }
     },
     "targeting": {
       "radius": {
         "include": [
           "MEDIUM"
         ]
       }
     },
     "automatedKeywordsOptIn": false,
     "deleted": false,
     "creationTime": "2025-01-10T08:00:00.000",
     "modificationTime": "2025-01-10T08:00:00.000"
   },
   {
     "id": 555666780,
     "name": "AwayFinder Maps — SF Bay Area",
     "adAccountId": 123456789,
     "campaignId": 444555668,
     "pricingModel": "CPT",
     "status": "ENABLED",
     "systemStatus": "RUNNING",
     "startTime": "2025-09-01T00:00:00.000",
     "endTime": "2025-12-31T23:59:59.000",
     "bidStrategy": {
       "bidStrategyType": "MANUAL_CPT",
       "bidStrategyGoal": "TAP",
       "bid": {
         "amount": "4.00",
         "currency": "USD"
       }
     },
     "targeting": {
       "locality": {
         "include": [
           "902134",
           "830123"
         ]
       },
       "daypart": {
         "include": [
           "1",
           "5",
           "10",
           "18"
         ]
       }
     },
     "automatedKeywordsOptIn": false,
     "deleted": false,
     "creationTime": "2025-01-10T09:00:00.000",
     "modificationTime": "2025-01-10T09:00:00.000"
   }
 ],
 "pagination": {
   "totalCount": 2,
   "offset": 0,
   "pageSize": 20
 }
}
```

**Query Deleted:**

Retrieve soft-deleted ad groups for a campaign to confirm deletion or audit history.

### Request

```json
POST /v1/adgroups/query

{
 "filters": [
   {
     "field": "campaignId",
     "operator": "EQUALS",
     "value": 444555666
   },
   {
     "field": "deleted",
     "operator": "EQUALS",
     "value": true
   }
 ],
 "pagination": {
   "offset": 0,
   "pageSize": 20,
   "fetchTotalCount": true
 }
}
```

### Response

```json
{
 "result": [
   {
     "id": 555666777,
     "name": "AwayFinder iOS — New Users 18-34",
     "adAccountId": 123456789,
     "campaignId": 444555666,
     "pricingModel": "CPT",
     "status": "ENABLED",
     "systemStatus": "NOT_RUNNING",
     "deleted": true,
     "creationTime": "2025-01-10T08:00:00.000",
     "modificationTime": "2025-06-15T14:00:00.000"
   }
 ],
 "pagination": {
   "totalCount": 1,
   "offset": 0,
   "pageSize": 20
 }
}
```

---

Copyright &copy; 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)