Query Target CPA Recommendations

Retrieve target cost-per-acquisition recommendations for campaigns using a Maximize Conversions bid strategy.

URL

POST https://api.ads.apple.com/v1/recommendations/target-cpas/query

Header Parameters

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

Response Codes

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

Discussion

Each TargetCpaRecommendation result includes:

recommendedTargetCPA: the suggested new target CPA
bidStrategy: the campaign’s current bid strategy context
Historical metrics: installs, spend, taps, averageCPA, averageCPT, impression, ttr
Expected metrics: projected expectedInstalls, expectedSpend, expectedTaps, expectedCPA

Only campaigns using a Maximize Conversions bid strategy will receive recommendations.

See FilterOperator for the full set of supported comparison operators.

Filterable Fields

Field	Type	Operators	Description
`promotedObjectId`	string	`EQUALS`	Required. The ID of the promoted object. For `APPSTORE_APP`, this is the app Adam ID. For `BUSINESS_BRAND`, this is the brand ID. Accepts exactly one value.
`promotedObjectType`	string (enum)	`EQUALS`	Required. The type of promoted object. Accepts exactly one value.
`id`	string	`EQUALS`, `IN`	Optional. The recommendation’s unique identifier.
`state`	string (enum)	`EQUALS`, `IN`	Optional. `AVAILABLE`, `APPLIED`, `DISMISSED`, or `DELETE`.
`status`	string (enum)	`EQUALS`, `IN`	Optional. `ENABLED`, `DISABLED`, or `DELETED`.
`recommendationType`	string (enum)	`EQUALS`, `IN`	Optional. The recommendation category, for example `TCPA` or `STCPA`. See Recommendationcategory.
`campaignId`	integer	`EQUALS`, `IN`	Optional. Filter by a specific campaign.
`campaignName`	string	`EQUALS`, `CONTAINS_ANY`, `STARTS_WITH`	Optional. The campaign’s display name.
`bidStrategy`	object	`EQUALS`, `IN`	Optional. The campaign’s current bid strategy.
`creationTime`	string (date-time)	`EQUALS`, `GREATER_THAN`, `LESS_THAN`	Optional. When the recommendation was created.
`modificationTime`	string (date-time)	`EQUALS`, `GREATER_THAN`, `LESS_THAN`	Optional. When the recommendation was last modified.
`expirationTime`	string (date-time)	`EQUALS`, `GREATER_THAN`, `LESS_THAN`	Optional. When the recommendation expires.
`averageCPT`	money	`EQUALS`, `GREATER_THAN`, `LESS_THAN`, `BETWEEN`	Optional. Historical average cost-per-tap.
`averageCPA`	money	`EQUALS`, `GREATER_THAN`, `LESS_THAN`, `BETWEEN`	Optional. Historical average cost-per-acquisition.
`expectedTaps`	integer	`EQUALS`, `GREATER_THAN`, `LESS_THAN`, `BETWEEN`	Optional. Projected tap count if the recommendation is applied.
`expectedCPA`	money	`EQUALS`, `GREATER_THAN`, `LESS_THAN`, `BETWEEN`	Optional. Projected cost-per-acquisition if the recommendation is applied.
`expectedInstalls`	integer	`EQUALS`, `GREATER_THAN`, `LESS_THAN`, `BETWEEN`	Optional. Projected install count if the recommendation is applied.
`expectedSpend`	money	`EQUALS`, `GREATER_THAN`, `LESS_THAN`, `BETWEEN`	Optional. Projected spend if the recommendation is applied.
`impression`	integer	`EQUALS`, `IN`, `GREATER_THAN`, `LESS_THAN`, `BETWEEN`	Optional. Historical impression count.
`installs`	integer	`EQUALS`, `IN`, `GREATER_THAN`, `LESS_THAN`, `BETWEEN`	Optional. Historical install count.
`spend`	money	`EQUALS`, `GREATER_THAN`, `LESS_THAN`, `BETWEEN`	Optional. Historical spend.
`recommendedTargetCPA`	money	`EQUALS`, `GREATER_THAN`, `LESS_THAN`, `BETWEEN`	Optional. The suggested new target CPA.
`taps`	integer	`EQUALS`, `IN`, `GREATER_THAN`, `LESS_THAN`, `BETWEEN`	Optional. Historical tap count.
`ttr`	number	`EQUALS`, `GREATER_THAN`, `LESS_THAN`, `BETWEEN`	Optional. Historical tap-through rate.

Payload Examples

This example queries available target CPA recommendations for an app, sorted by creation time. The response includes the recommended CPA alongside historical performance metrics and projected results if the recommendation is applied.

HTTP Body

See RecommendationQueryRequest.