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

# Query Assets

Retrieve a paginated list of creative assets using filters and sorting.

## Discussion

This endpoint queries assets using a standard `QueryRequest` body. Filter by `promotedObjectId` to retrieve all assets for a specific brand. An empty request body returns all assets with default pagination.

After uploading an asset, use this endpoint to check `eligibility` status in bulk rather than polling each asset individually.

See [`QueryFilterOperator`](/documentation/Apple-Ads-Platform-API/QueryFilterOperator) for the full set of supported comparison operators.

### Filterable Fields

|Field               |Type              |Operators                                                                                                          |Sortable|Description                                                                                                              |
|--------------------|:----------------:|:-----------------------------------------------------------------------------------------------------------------:|:------:|-------------------------------------------------------------------------------------------------------------------------|
|`id`                |string (UUID)     |`EQUALS`, `NOT_EQUALS`, `IN`, `LIKE`, `STARTS_WITH`                                                                |Yes     |Internal asset identifier.                                                                                               |
|`name`              |string            |`EQUALS`, `NOT_EQUALS`, `IN`, `LIKE`, `STARTS_WITH`, `ENDS_WITH`                                                   |Yes     |User-facing asset name or description.                                                                                   |
|`assetType`         |string (enum)     |`EQUALS`, `NOT_EQUALS`, `IN`                                                                                       |Yes     |The media type of the asset. See <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/AssetType>.|
|`providerAssetId`   |string            |`EQUALS`, `NOT_EQUALS`, `IN`                                                                                       |No      |Asset identifier assigned by the provider system.                                                                        |
|`promotedObjectId`  |string            |`EQUALS`, `NOT_EQUALS`, `IN`                                                                                       |No      |Identifier of the promoted object. Scope to a specific brand or app.                                                     |
|`promotedObjectType`|string (enum)     |`EQUALS`, `NOT_EQUALS`, `IN`                                                                                       |No      |The type of the promoted object: `BUSINESS_BRAND` or `APPSTORE_APP`.                                                     |
|`deleted`           |boolean           |`EQUALS`, `NOT_EQUALS`, `IN`                                                                                       |No      |Whether the asset has been deleted. Excluded by default unless explicitly filtered.                                      |
|`parentAssetId`     |string (UUID)     |`EQUALS`, `IS_NULL`, `IS_NOT_NULL`                                                                                 |No      |Identifier of the parent asset for a variant crop. `null` for original assets.                                           |
|`creationTime`      |string (date-time)|`EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `LESS_THAN`, `LESS_THAN_OR_EQUAL_TO`, `BETWEEN`|Yes     |Timestamp when the asset was created.                                                                                    |
|`modificationTime`  |string (date-time)|`EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `LESS_THAN`, `LESS_THAN_OR_EQUAL_TO`, `BETWEEN`|Yes     |Timestamp of the last modification to the asset.                                                                         |

`providerAssetMetadata`, `assetDetails`, `eligibility`, and `eligibility.status` aren’t filterable.

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).

## Request Body

See [`QueryRequest`](/documentation/Apple-Ads-Platform-API/QueryRequest).

Querying assets carries a couple of caveats around scope and variants:

|Constraint                               |Detail                                                                                                       |
|-----------------------------------------|-------------------------------------------------------------------------------------------------------------|
|Always filter by `promotedObjectId`      |Omitting this returns assets across all brands, which may be a large result set.                             |
|Asset crops not included in query results|Variant assets (crops) are omitted from query responses. To retrieve a specific variant, use Get Asset by ID.|

## Payload Examples

**Query by Brand:**

Retrieve all assets for a specific brand.

### Request

```json
{
 "filters": [
   {
     "field": "promotedObjectId",
     "operator": "EQUALS",
     "value": "9151314442816847872"
   },
   {
     "field": "promotedObjectType",
     "operator": "EQUALS",
     "value": "BUSINESS_BRAND"
   }
 ],
 "pagination": {
   "offset": 0,
   "pageSize": 20,
   "fetchTotalCount": true
 }
}
```

### Response

```json
{
 "result": [
   {
     "id": "770e8400-e29b-41d4-a716-446655440002",
     "name": "awayfinder_hero.png",
     "assetType": "IMAGE",
     "providerAssetId": "abc123-provider-id",
     "promotedObjectId": "9151314442816847872",
     "promotedObjectType": "BUSINESS_BRAND",
     "providerAssetMetadata": {},
     "assetDetails": {
       "width": 1920,
       "height": 1080,
       "format": "PNG",
       "sizeBytes": 2097152,
       "orientation": "LANDSCAPE"
     },
     "parentAssetId": null,
     "variantIds": [],
     "creationTime": "2026-01-10T08:00:00.000",
     "modificationTime": "2026-01-10T08:00:00.000",
     "eligibility": {
       "status": "ELIGIBLE",
       "blockedGroups": [],
       "allowedGroups": []
     }
   }
 ],
 "pagination": {
   "totalCount": 1,
   "offset": 0,
   "pageSize": 20
 }
}
```

**Query App Ads Assets:**

Retrieve assets for a specific App Store app by its Adam ID.

### Request

```json
{
 "filters": [
   {
     "field": "promotedObjectId",
     "operator": "EQUALS",
     "value": "123456789"
   },
   {
     "field": "promotedObjectType",
     "operator": "EQUALS",
     "value": "APPSTORE_APP"
   }
 ],
 "pagination": {
   "offset": 0,
   "pageSize": 20,
   "fetchTotalCount": true
 }
}
```

### Response

```json
{
 "result": [
   {
     "id": "990e8400-e29b-41d4-a716-446655440004",
     "name": "AwayFinder Screenshot 1",
     "assetType": "IMAGE",
     "providerAssetId": "987654321-screenshot-1",
     "promotedObjectId": "123456789",
     "promotedObjectType": "APPSTORE_APP",
     "providerAssetMetadata": {
       "appPreviewDevice": "iphone_6_7",
       "assetGenId": "123456789;en-US;iphone_6_7;1;abc123def"
     },
     "assetDetails": {
       "width": 1284,
       "height": 2778,
       "format": "PNG",
       "sizeBytes": 2456789,
       "orientation": "PORTRAIT"
     },
     "parentAssetId": null,
     "variantIds": [],
     "creationTime": "2026-03-01T08:00:00.000",
     "modificationTime": "2026-03-01T08:00:00.000",
     "eligibility": {
       "status": "ELIGIBLE",
       "blockedGroups": [],
       "allowedGroups": []
     }
   }
 ],
 "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)