Apple Ads optimizer

• The user runs Apple Ads for their own app and connected the Apple Ads account in AppGoat (https://dash.appgoat.ai/connections, provider apple_ads, Apple Ads Platform API). An API user with access to several ad accounts connects one ad_account_id per connection; pick the connection whose account runs the app's campaigns.
• Not for organic keyword research (use aso-keywords-metadata-rewrite) or Google Ads.

• campaign (optional): a campaign name or id. Default: every campaign with status ENABLED; ask which ones when there are more than five.
• target_cpa (optional): the most the user wants to pay per install, in the campaign currency. Ask for it if missing; if they don't know, suggest the median CPA of the converting keywords from step 3 and get a yes before using it. Also ask for the daily budget they are comfortable with.

Window: the last 14 full days (end = yesterday, start = end − 13 days, UTC). Limits per run: at most 25 bid changes, 15 new keywords and 25 negatives per campaign.

Costs in AppGoat credits. Without the MCP, use the REST equivalents in the REST calls below.

1. list_connections {provider: "apple_ads"} - 0. Keep status: active; mode: read_only can only dry-run (say so). None: send the user to https://dash.appgoat.ai/connections and stop.
2. read_connection {id, what: "ads", view: "campaigns"} - 1. Campaign ids, status, app (adam id), countries, daily budget. Pick the campaigns.
3. Per campaign:
   • read_connection {id, what: "ads", view: "ad_groups", campaign_id} - 1 (ad group ids, default bids).
   • read_connection {id, what: "ads", view: "report", level: "keywords", campaign_id, start, end} - 1: per keyword impressions, taps, installs, spend, avg CPT, avg CPA, keyword id, ad group id, bid.
   • read_connection {id, what: "ads", view: "report", level: "searchterms", campaign_id, start, end} - 1: the search terms that triggered the ads, with the keyword that matched them.
   • read_connection {id, what: "ads", view: "negatives", campaign_id} - 1 (existing negatives).
   • For ad groups you will add keywords to: read_connection {view: "keywords", campaign_id, ad_group_id} - 1 each.
4. Optional, for search terms you cannot judge: keyword_research {terms: ≤ 25 terms, store: "apple", country: <campaign country>} - 1 per term. Popularity 5–100 shows whether a term has real search volume; include: ["top_apps"] shows which apps win it (relevance check).
5. Apply the decision rules (no calls) and build three lists: bid changes, new exact keywords, negatives.
6. Propose them as dry runs, one action per ad group and type, with playbook: "apple-ads-optimizer" - 0:
   • propose_action {type: "ads.keyword.bid", connection, params: {campaign_id, ad_group_id, keywords: [{id, bid}] or [{id, status: "PAUSED"}], max_increase: 0.3}} (status is ENABLED or PAUSED; ENABLED resumes a paused keyword)
   • propose_action {type: "ads.keyword.add", connection, params: {campaign_id, ad_group_id, keywords: [{text, match_type: "EXACT", bid}]}}
   • propose_action {type: "ads.negative.add", connection, params: {campaign_id, ad_group_id, keywords: [{text, match_type: "EXACT"}]}} The diffs show current → new bid per keyword; warnings flag bid jumps above max_increase and negatives that would block an enabled keyword.
7. Show the user the summary table (see Output format) with each action id and the expected effect, and ask which to apply ("all", "only bids", "all except negatives in ad group X").
8. apply_action {id} for each approved action - 1 per applied action. pending_approval → give the user the approve_url; "needs approval by a person" → hand over the link, don't retry; "account changed" (someone edited bids meanwhile) → show the new diff, re-run step 3 for that ad group rather than forcing. reject_action {id, reason} the declined ones - 0.
9. Report what changed and when to look again (7 days).

Budget: ~5–8 credits per campaign to read + 1 per applied action (dry runs are free).

Let T = target CPA. Only act on rows with enough data: taps ≥ 10 or spend ≥ T.

• Raise bid when installs ≥ 3 and CPA ≤ 0.8 × T: new bid = current × min(1.30, T / CPA × 0.9), rounded to 0.05. Never more than +30% per run; skip keywords already at the user's max CPT.
• Hold when CPA is within 0.8–1.2 × T, or the data threshold is not met.
• Lower bid when installs ≥ 1 and CPA > 1.2 × T: new bid = current × max(0.70, T / CPA), i.e. at most −30% per run.
• Pause (status: "PAUSED") when installs = 0 and spend ≥ 2 × T. Lower by 30% instead when installs = 0 and spend is between T and 2 × T, or when the keyword is the app's brand name.
• Add as EXACT keyword a search term with installs ≥ 2 and CPA ≤ T that is not already a keyword (any match type) in the ad group. Bid = its avg CPT × 1.1 (or the ad group default when the CPT is missing). Put it in the user's exact-match ad group when they have one, else the ad group where it converted. Skip "(low volume terms)" rows: Apple hides those terms.
• Add as negative (EXACT, ad group level) a search term with taps ≥ 10 and installs = 0 and spend ≥ T, or one that is clearly irrelevant (another product, a different meaning, a job or piracy query) regardless of spend. Prefer EXACT negatives; BROAD only for clearly irrelevant words and only with the user's explicit agreement.
• Never negate a term that converts (installs ≥ 1 in the window), that equals an enabled keyword in any ad group of the campaign, or the app's own brand. A guardrail warning about a blocked keyword means: drop that negative.
• Budget: if the proposed raises would push daily spend past the user's budget (estimate: current daily spend × (1 + weighted bid increase)), scale the raises down; never change campaign budgets.
• Changes compound: one run per week, and never re-raise a keyword raised in the last 7 days (check get_action history or ask).

# Apple Ads optimizer: <campaign> (<country>) - <start> → <end>, target CPA <T> <cur>

Spend <s> · installs <i> · CPA <c> · <k> keywords, <n> search terms with data

| Change | Ad group | Item | Now | Proposed | Why (14 d) | Action |
|---|---|---|---|---|---|---|
| Raise bid | Exact | habit tracker [EXACT] | 1.00 | 1.30 (+30%) | 14 installs, CPA 1.80 | act_… |
| Pause | Broad | free planner [BROAD] | 0.90 | paused | 0 installs, spend 11.20 | act_… |
| Add keyword | Exact | streak app [EXACT] | – | 0.85 | search term: 4 installs, CPA 2.10 | act_… |
| Negative | Broad | planner printable [EXACT] | – | negative | 22 taps, 0 installs | act_… |

Guardrail warnings: <none | list>.
Reply "apply all", "only bids", or name rows to skip.

Run report: what was applied, what waits for approval (links), and "Re-run in 7 days; the bid changes need about a week of data." Credits used: <sum>.

Without the AppGoat MCP server, call the API directly. Base URL https://api.appgoat.ai/v1, header x-api-key: $APPGOAT_API_KEY (create a key at https://dash.appgoat.ai). Responses are { "data": …, "meta": { "credits_used", "credits_remaining", … } }; errors are { "error": { "code", "message", "hint", "approve_url"? } } - read hint.

Report rows: { dims, impressions, taps, installs, spend, currency, avg_cpt, avg_cpa, ttr, conversion_rate }; dims holds Apple's row metadata (Apple Ads Platform API: keyword id, text and match type, ad group id and bid for keywords; the search term, its source and the matched keyword for search terms). Keyword status is ENABLED or PAUSED (ACTIVE is accepted as an alias). The connection's account shows the ad_account_id it acts on.

CON=con_… CAMPAIGN=123456
curl -s -G -H "x-api-key: $APPGOAT_API_KEY" "https://api.appgoat.ai/v1/connections/$CON/ads" \
  -d view=report -d level=searchterms -d campaign_id=$CAMPAIGN -d start=2026-10-08 -d end=2026-10-21 \
  | jq -r '.data.rows[] | "\(.dims.searchTerm // .dims.searchTermText)\t\(.taps)\t\(.installs)\t\(.spend)"'

# Bids for one ad group, as a dry run
curl -s -H "x-api-key: $APPGOAT_API_KEY" -H "content-type: application/json" https://api.appgoat.ai/v1/actions \
  -d '{"type":"ads.keyword.bid","connection":"'$CON'","dry_run":true,"source":"playbook:apple-ads-optimizer",
       "params":{"campaign_id":"'$CAMPAIGN'","ad_group_id":"789","max_increase":0.3,
                 "keywords":[{"id":"111","bid":1.3},{"id":"112","status":"PAUSED"}]}}' | jq '.data | {id, diff, guardrail}'