---
title: Query Phrase Suggestions
framework: Apple Ads Platform API
role: symbol
role_heading: Web Service Endpoint
platforms: [apple ads platform api 1.0+]
path: apple-ads-platform-api/query-phrase-suggestions
---

# Query Phrase Suggestions

Query phrase suggestions using either a discovery or search route based on the query type.

## URL

POST https://api.ads.apple.com/v1/suggestions/phrases/query

## Header Parameters

X-Ap-Context:

## Response Codes

200 OK: 400 Bad Request: 401 Unauthorized: 403 Forbidden: 404 Not Found: 429 Too Many Requests: 500 Internal Server Error:

## Discussion

Discussion Each result is a PhraseSuggestion object. Sort by popularity DESC and use pagination to page through results. Use SUGGESTION to discover new candidate phrases for an app or brand. It requires promotedObjectId and promotedObjectType, and works well when building a phrase list from scratch. Use SEARCH to look up or match specific phrases you already have in mind, using phrase with IN for an exact popularity lookup or LIKE for a partial match. The SEARCH route doesn’t require promotedObjectId. See FilterOperator for the full set of supported comparison operators. Filterable Fields  |  |  |   |  |  |   |  |  |   |  |  |   |  |  |  Payload Examples These examples discover relevant search phrases for an app or brand using the SUGGESTION route, and look up or search specific phrases using the SEARCH route.

## HTTP Body

See RecommendationQueryRequest. This endpoint supports two query routes selected by the queryType filter: SUGGESTION discovers phrases for an app or Apple Maps brand, and SEARCH looks up or searches specific phrases.

## See Also

- [Query Keyword Suggestions](apple-ads-platform-api/query-keyword-suggestions.md)
- [Query Category Suggestions](apple-ads-platform-api/query-category-suggestions.md)
- [Query Target CPA Suggestion](apple-ads-platform-api/query-target-cpa-suggestion.md)