<!--
{
  "availability" : [
    "Apple Ads Platform API: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Apple-Ads-Platform-API",
  "identifier" : "/documentation/Apple-Ads-Platform-API/RecommendationQueryRequest",
  "metadataVersion" : "0.1.0",
  "role" : "Object",
  "symbol" : {
    "kind" : "Object",
    "modules" : [
      "Apple Ads Platform API"
    ],
    "preciseIdentifier" : "data:apple-ads-platform-api:RecommendationQueryRequest"
  },
  "title" : "RecommendationQueryRequest"
}
-->

# RecommendationQueryRequest

The structured request body for all recommendation query endpoints.

```
object RecommendationQueryRequest
```

## Discussion

The `QueryRequest` object is the request body for all `POST .../query` endpoints in the Recommendations API. Two filter conditions are mandatory on every request:

```json
[
  {
    "field": "promotedObjectId",
    "operator": "EQUALS",
    "value": [
      "123456"
    ]
  },
  {
    "field": "promotedObjectType",
    "operator": "EQUALS",
    "value": [
      "APPSTORE_APP"
    ]
  }
]
```

Omitting either required filter returns a 400 error with a `MISSING_REQUIRED_FILTER` detail in the response. Additional optional filters narrow the result set. For example, `state` or `campaignId`. The API combines all filter conditions with AND logic.

### Example

```json
{
  "filters": [
    {
      "field": "promotedObjectId",
      "operator": "EQUALS",
      "value": [
        "123456789"
      ]
    },
    {
      "field": "promotedObjectType",
      "operator": "EQUALS",
      "value": [
        "APPSTORE_APP"
      ]
    },
    {
      "field": "state",
      "operator": "EQUALS",
      "value": [
        "AVAILABLE"
      ],
      "ignoreCase": false
    }
  ],
  "sorting": [
    {
      "field": "creationTime",
      "order": "DESC"
    }
  ],
  "pagination": {
    "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)