Query Assets

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

URL

POST https://api.ads.apple.com/v1/assets/query

Header Parameters

Name	Type	Description
`X-Ap-Context` Required	string

Response Codes

Status	Reason	Type
200	OK Content-Type: application/json	`AssetQueryResponse`
400	Bad Request Content-Type: application/json	`AssetQueryResponse`
401	Unauthorized Content-Type: application/json	`Error`
403	Forbidden Content-Type: application/json	`Error`
404	Not Found Content-Type: application/json	`ErrorResponse`
429	Too Many Requests Content-Type: application/json	`Error`
500	Internal Server Error Content-Type: application/json	`Error`

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 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 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 composed of QueryFilter conditions and QuerySort directives (QuerySortOrder), controlled by QueryPagination.

Request Body

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