<!--
{
  "availability" : [
    "Apple Ads Platform API: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Apple-Ads-Platform-API",
  "identifier" : "/documentation/Apple-Ads-Platform-API/POST-ads-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:ads-query"
  },
  "title" : "Query Ads"
}
-->

# Query Ads

Searches and filters ads using structured query criteria including field filters, sorting, and pagination.

## Discussion

This endpoint queries ads using a standard `QueryRequest` body. Filter by `adGroupId` to scope results to a specific ad group, or by `campaignId` to retrieve all ads across an entire campaign. An empty request body returns all ads for the ad account with default pagination.

The system excludes deleted ads from results by default. To retrieve deleted ads, include a `deleted EQUALS true` filter.

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.                                                                                        |
|`campaignId`|integer      |`EQUALS`      |Yes          |The campaign this ad belongs to.                                                                                         |
|`adGroupId` |integer      |`EQUALS`      |Yes          |The ad group this ad belongs to.                                                                                         |
|`creativeId`|integer      |`EQUALS`      |Yes          |The ad creative this ad was created from.                                                                                |
|`status`    |string (enum)|`EQUALS`, `IN`|Yes          |Advertiser-configured status. See <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/AdStatus>.|
|`deleted`   |boolean      |`EQUALS`      |Yes          |Whether the ad 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 Ad Group:**

Retrieve all active ads in a specific ad group, sorted by creation time descending.

### Request

```json
POST /v1/ads/query

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

### Response

```json
{
 "result": [
   {
     "id": 777888999,
     "adAccountId": 123456789,
     "campaignId": 444555666,
     "adGroupId": 555666777,
     "creativeId": 666777888,
     "name": "AwayFinder - Default Product Page",
     "status": "ENABLED",
     "systemStatus": "RUNNING",
     "systemStatusReasons": [],
     "systemStatusLimitingReasons": [],
     "deleted": false,
     "creationTime": "2025-09-01T08:00:00.000",
     "modificationTime": "2025-09-01T08:00:00.000"
   },
   {
     "id": 777888998,
     "adAccountId": 123456789,
     "campaignId": 444555666,
     "adGroupId": 555666777,
     "creativeId": 666777889,
     "name": "AwayFinder - Holiday Product Page",
     "status": "ENABLED",
     "systemStatus": "RUNNING",
     "systemStatusReasons": [],
     "systemStatusLimitingReasons": [],
     "deleted": false,
     "creationTime": "2025-10-01T08:00:00.000",
     "modificationTime": "2025-10-01T08:00:00.000"
   }
 ],
 "pagination": {
   "totalCount": 2,
   "offset": 0,
   "pageSize": 20
 }
}
```

**Filter by Status:**

Retrieve only paused ads within a campaign to identify ads that may need to be re-enabled.

### Request

```json
POST /v1/ads/query

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

### Response

```json
{
 "result": [
   {
     "id": 777888998,
     "adAccountId": 123456789,
     "campaignId": 444555666,
     "adGroupId": 555666777,
     "creativeId": 666777888,
     "name": "AwayFinder - Maps Creative",
     "status": "PAUSED",
     "systemStatus": "NOT_RUNNING",
     "systemStatusReasons": [
       "PAUSED_BY_USER"
     ],
     "systemStatusLimitingReasons": [],
     "deleted": false,
     "creationTime": "2025-09-01T09:00:00.000",
     "modificationTime": "2025-10-01T10: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)