Recommendations

When you finish this page you can read the optimization recommendations Google generates for an ad account (budgets, bidding targets, keywords, assets), see what each one is expected to change, apply the ones you want and dismiss the rest. You need a googleads account. Every call takes accountId, plus adAccountId (the customer id) when the connection has several Google customers.

Read recommendations

GET /v1/ads/recommendations lists the account's recommendations. Narrow it with campaignId (Google's numeric campaign id) and types, a comma-separated list of Google RecommendationType values such as CAMPAIGN_BUDGET,KEYWORD,SET_TARGET_CPA. An unknown type returns 400.

curl "https://zernio.com/api/v1/ads/recommendations?accountId=66b2e19d8c3f5a7e9d0b1c2d&adAccountId=1234567890&types=FORECASTING_SET_TARGET_CPA,CAMPAIGN_BUDGET" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"

Response (200), trimmed to one recommendation:

{
  "adAccountId": "1234567890",
  "recommendations": [
    {
      "resourceName": "customers/1234567890/recommendations/NjgzMzAxODc4NS0yNDItMTc5MDQzODQxMDc1NC0rMjQxOTE1ODU2NzEtMA",
      "id": "NjgzMzAxODc4NS0yNDItMTc5MDQzODQxMDc1NC0rMjQxOTE1ODU2NzEtMA",
      "type": "FORECASTING_SET_TARGET_CPA",
      "dismissed": false,
      "campaignId": "21874563210",
      "campaignIds": ["21874563210"],
      "adGroupId": null,
      "campaignBudgetId": null,
      "impact": {
        "base": { "impressions": 2790, "clicks": 87, "cost": 420, "conversions": 3.96, "conversionsValue": 0, "videoViews": 0 },
        "potential": { "impressions": 5909, "clicks": 185, "cost": 889.58, "conversions": 8.39, "conversionsValue": 0, "videoViews": 0 }
      },
      "details": {
        "recommendedTargetCpaMicros": "105420000",
        "campaignBudget": { "currentAmountMicros": "60000000", "recommendedNewAmountMicros": "140000000", "newStartDate": "2026-10-01" }
      }
    }
  ],
  "cachedAt": null,
  "stale": false
}

• resourceName is what you pass to apply or dismiss; the bare id works too.
• campaignId is the campaign the recommendation targets, and campaignIds lists every campaign it touches (several for account-level types). adGroupId and campaignBudgetId are set when the recommendation targets one.
• impact is Google's estimate over its own window: base is what the target does today and potential what Google expects after applying. cost is in account currency units, not micros. impact is null when Google gives no estimate for the type.
• details is the type-specific payload exactly as Google returns it, camelCase and with amounts in micros (divide by 1,000,000). Its fields depend on type, so read them against Google's Recommendation reference.

The list is cached for 10 minutes per customer and filter, and applying or dismissing clears it, so the next read is live. When Google's quota runs out the last successful copy is served with stale: true; check cachedAt before treating it as current.

Apply recommendations

POST /v1/ads/recommendations/apply applies up to 100 recommendations in one call. Without parameters, Google applies its own suggested values. To override them, parameters takes exactly one key named for the recommendation type, in Google's ApplyRecommendationOperation shape (amounts in micros):

curl -X POST "https://zernio.com/api/v1/ads/recommendations/apply" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
    "adAccountId": "1234567890",
    "recommendations": [
      { "resourceName": "customers/1234567890/recommendations/NjgzMzAxODc4NS0yNDEtMTc5MDQ3NTQyNjU5Ni0rMjM1MjA5NjcxNjctMA" },
      {
        "resourceName": "NjgzMzAxODc4NS0yMjgtMTc5MDQyNDE5NjUwNS0rMTU3NjMyNzU3ODk",
        "parameters": { "campaignBudget": { "newBudgetAmountMicros": "150000000" } }
      }
    ]
  }'

Response (200):

{
  "adAccountId": "1234567890",
  "results": [
    { "resourceName": "customers/1234567890/recommendations/NjgzMzAxODc4NS0yNDEtMTc5MDQ3NTQyNjU5Ni0rMjM1MjA5NjcxNjctMA", "status": "applied" },
    { "resourceName": "customers/1234567890/recommendations/NjgzMzAxODc4NS0yMjgtMTc5MDQyNDE5NjUwNS0rMTU3NjMyNzU3ODk", "status": "failed", "error": "The recommendation is no longer valid." }
  ]
}

The accepted parameters keys are campaignBudget, keyword, textAd, targetCpaOptIn, targetRoasOptIn, callAsset, calloutAsset, sitelinkAsset, moveUnusedBudget, responsiveSearchAd, responsiveSearchAdAsset, responsiveSearchAdImproveAdStrength, useBroadMatchKeyword, raiseTargetCpa, lowerTargetRoas, setTargetCpa, setTargetRoas, forecastingSetTargetCpa, forecastingSetTargetRoas, leadFormAsset, raiseTargetCpaBidTooLow, raiseTargetCpaPerformanceBidTooLow, lowerTargetRoasPerformanceBidTooLow, calloutExtension, callExtension and sitelinkExtension. Sending two keys, or one not on this list, returns 400.

Items run in partial-failure mode: each one gets its own status (applied or failed, with Google's message in error), and a stale or invalid recommendation does not block the others. The call answers 200 even when some items fail, so check every result. Every resourceName must belong to the customer in the call; one under another customer returns 400.

Dismiss recommendations

POST /v1/ads/recommendations/dismiss dismisses up to 100 recommendations so Google stops suggesting them. resourceNames takes resource names or bare ids:

curl -X POST "https://zernio.com/api/v1/ads/recommendations/dismiss" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
    "adAccountId": "1234567890",
    "resourceNames": ["NjgzMzAxODc4NS0yNDItMTc5MDQzODQxMDc1NC0rMjQxOTE1ODU2NzEtMA"]
  }'

Response (200): { "adAccountId": "1234567890", "results": [{ "resourceName": "customers/1234567890/recommendations/NjgzMzAxODc4NS0yNDItMTc5MDQzODQxMDc1NC0rMjQxOTE1ODU2NzEtMA", "status": "dismissed" }] }. Dismissing runs in the same partial-failure mode as apply.

If it fails

A failed item inside a 200 is Google refusing that one recommendation, usually because it has expired or the account changed since it was generated. Read the list again and act on the current set.

Related

• Conversions: the goals that bidding recommendations optimize toward.
• Limits and errors: quotas and what the API cannot do.
• List Google Ads recommendations, Apply Google Ads recommendations and Dismiss Google Ads recommendations: every field.