Query Ads
Searches and filters ads using structured query criteria including field filters, sorting, and pagination.
URL
POST https://api.ads.apple.com/v1/ads/queryHeader Parameters
| Name | Type | Description |
|---|---|---|
X-Ap-Context Required | string |
Response Codes
| Status | Reason | Type | Description |
|---|---|---|---|
| 200 | OK Content-Type: application/json | AdQueryResponse | |
| 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 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 for the full set of supported comparison operators.
Filterable Fields
Field | Type | Operators | Sortable | Description |
|---|---|---|---|---|
| integer |
| Yes (default) | The unique identifier for the ad. |
| integer |
| Yes | The campaign this ad belongs to. |
| integer |
| Yes | The ad group this ad belongs to. |
| integer |
| Yes | The ad creative this ad was created from. |
| string (enum) |
| Yes | Advertiser-configured status. See Adstatus. |
| boolean |
| Yes | Whether the ad has been deleted. |
The request body is a QueryRequest composed of QueryFilter conditions and QuerySort directives (QuerySortOrder), controlled by QueryPagination.