Apple Search Ads ROAS Workflow - Appeeky REST API & MCP Server

Apple Search Ads shows what you spend and how users respond at install time. RevenueCat shows what those users earn afterward. Appeeky connects both sides so you can see which keywords and campaigns are actually profitable — and whether your App Store presence is strong enough to scale spend in each country. This workflow is available through REST, the web dashboard, and MCP tools.

What This Covers

Capability	Endpoint	Best for
Integration readiness	`GET /v1/connect/apple-ads/playbook/status`	Confirm RevenueCat, Apple Search Ads, and attribution are wired up before trusting ROAS numbers
Optimization recommendations	`GET /v1/connect/apple-ads/playbook/recommendations`	Scale winners, cut wasteful spend, and review country-level rating risks in one call
Review country gate	`GET /v1/connect/apple-ads/review-country-gate`	Compare active campaign countries against App Store ratings
Profitability by country	`GET /v1/connect/apple-ads/profitability?country=US`	ROAS filtered to campaigns targeting a specific country

For the core spend × revenue join and insight buckets, see Apple Search Ads Profitability. For per-customer attribution dimensions from RevenueCat, see RevenueCat Attribution.

Prerequisites

An Appeeky API key.
Apple Search Ads connected in Appeeky (or per-request ASA headers).
A RevenueCat secret API key (X-RC-Key), saved in Appeeky Settings or passed per request.
Apple AdServices enabled in RevenueCat under Integrations. This is what populates Apple Search Ads attribution in RevenueCat charts and customer attributes.

Without Apple AdServices in RevenueCat, Appeeky can still return Apple Search Ads spend and installs, but revenue, profit, and ROAS will be incomplete. The readiness endpoint flags this before you act on recommendations.

Integration Readiness

Check whether your stack is ready for ROAS analysis.

GET /v1/connect/apple-ads/playbook/status

Headers

Header	Required	Description
`X-API-Key`	Yes	Your Appeeky API key
`X-RC-Key`	No	RevenueCat secret key. If omitted, Appeeky uses credentials saved in your account when available.
`X-RC-Project`	No	RevenueCat project ID when your key has multiple projects

Example

curl

curl "https://api.appeeky.com/v1/connect/apple-ads/playbook/status" \
  -H "X-API-Key: YOUR_APPEEKY_KEY" \
  -H "X-RC-Key: sk_YOUR_REVENUECAT_SECRET_KEY"

Response

{
  "data": {
    "ready": false,
    "appleSearchAdsConnected": true,
    "revenueCatConnected": true,
    "appleAdsAttributionEnabled": false,
    "profitabilityAvailable": false,
    "steps": [
      {
        "id": "revenuecat",
        "title": "Connect RevenueCat",
        "status": "complete",
        "detail": "RevenueCat secret key is saved in Appeeky."
      },
      {
        "id": "apple_adservices",
        "title": "Enable Apple AdServices in RevenueCat",
        "status": "warning",
        "detail": "No Apple Search Ads attribution detected yet. Enable Apple AdServices in RevenueCat Integrations and wait for installs."
      },
      {
        "id": "apple_search_ads",
        "title": "Connect Apple Search Ads",
        "status": "complete",
        "detail": "Apple Search Ads API credentials are connected."
      },
      {
        "id": "profitability",
        "title": "ROAS analysis ready",
        "status": "warning",
        "detail": "Connect both integrations and enable Apple AdServices attribution to unlock ROAS."
      }
    ]
  }
}

Step statuses

Status	Meaning
`complete`	Requirement met
`warning`	Connected but data not flowing yet (e.g. attribution pending)
`incomplete`	Not configured

When ready is true, all steps are complete and profitability analysis is fully available.

Optimization Recommendations

Returns a bundled analysis: integration gaps, ROAS-based scale and pause candidates, a RevenueCat attribution sample, and optional review-rating warnings by country.

GET /v1/connect/apple-ads/playbook/recommendations

Query parameters

Parameter	Default	Description
`level`	`keyword`	Rollup for profitability: `keyword`, `campaign`, or `adgroup`
`days`	`14`	Trailing date window
`minSpend`	`20`	Minimum spend for insight buckets
`minRating`	`4.5`	App Store rating threshold for review country gate
`country`	—	Optional ISO country code (e.g. `US`) to scope profitability
`appId`	—	Apple App Store numeric app ID. Required for review country gate section

Headers

Same as Profitability: X-API-Key, X-RC-Key, optional X-RC-Project, and optional per-request ASA headers.

Example

curl

curl \
  "https://api.appeeky.com/v1/connect/apple-ads/playbook/recommendations?level=keyword&days=14&appId=123456789&country=US" \
  -H "X-API-Key: YOUR_APPEEKY_KEY" \
  -H "X-RC-Key: sk_YOUR_REVENUECAT_SECRET_KEY"

Response shape

{
  "data": {
    "playbook": { "...": "same as /playbook/status" },
    "profitability": { "...": "same as /profitability" },
    "attribution": {
      "sampleSize": 50,
      "customersWithAttribution": 12,
      "appleSearchAdsAttributed": 8,
      "attributionEnabled": true,
      "rows": [
        {
          "mediaSource": "Apple Search Ads",
          "campaign": "US Brand",
          "adGroup": null,
          "keyword": "competitor name",
          "country": "US",
          "customerCount": 3,
          "totalRevenue": 47.97
        }
      ]
    },
    "reviewGate": {
      "appId": "123456789",
      "minRating": 4.5,
      "rows": [],
      "warnings": []
    },
    "recommendations": [
      {
        "type": "scale",
        "priority": "high",
        "title": "Scale: competitor name",
        "detail": "ROAS 2.10x with $82 spend and 19 installs.",
        "keyword": "competitor name",
        "roas": 2.1,
        "spend": 82
      }
    ]
  }
}

Recommendation types

Type	Meaning
`setup`	Missing integration or attribution step
`scale`	Strong ROAS with enough spend — candidate to increase budget or bids
`kill`	Meaningful spend with weak ROAS or zero installs — candidate to pause or bid down
`attribution`	Top rows from RevenueCat customer attribution sample
`review_gate`	Country with active campaigns but App Store rating below threshold

Review Country Gate

Low App Store ratings in a country can hurt conversion on paid traffic. This endpoint compares active Apple Search Ads campaign targeting against the app’s App Store rating in each country.

GET /v1/connect/apple-ads/review-country-gate?appId=123456789

Query parameters

Parameter	Required	Default	Description
`appId`	Yes	—	Apple App Store numeric app ID
`minRating`	No	`4.5`	Flag countries at or below this average rating

Example

curl

curl \
  "https://api.appeeky.com/v1/connect/apple-ads/review-country-gate?appId=123456789&minRating=4.5" \
  -H "X-API-Key: YOUR_APPEEKY_KEY"

Response

{
  "data": {
    "appId": "123456789",
    "minRating": 4.5,
    "rows": [
      {
        "country": "TH",
        "countryCode": "TH",
        "rating": 3.8,
        "reviewCount": 42,
        "campaignCount": 1,
        "campaignNames": ["SEA Tier 3"],
        "status": "critical",
        "recommendation": "Rating 3.8 is below 4.5. Pause or remove this country from campaigns to avoid burning budget on low-trust listings."
      }
    ],
    "warnings": []
  }
}

Row status

Status	Meaning
`ok`	Rating meets threshold
`warning`	Rating could not be fetched — verify manually
`critical`	Rating below threshold while campaigns still target this country

Ratings are sourced from the public App Store catalog per country. They reflect the listing users see when your ad appears in that storefront.

Country-Scoped Profitability

Filter ROAS analysis to campaigns that target a single country. Useful when you run separate campaigns per region.

GET /v1/connect/apple-ads/profitability?level=keyword&days=14&country=US

Appeeky filters using each campaign’s countriesOrRegions metadata from Apple Search Ads. Revenue attribution remains at the keyword, ad group, or campaign level from RevenueCat charts — country filtering applies to spend and campaign scope, not a second revenue dimension. See Apple Search Ads Profitability for full parameters, response fields, and insight types.

Typical Workflow

Check readiness — GET /playbook/status until ready is true.
Review recommendations — GET /playbook/recommendations?appId=… for scale, pause, and country warnings.
Drill into keywords — GET /profitability?level=keyword&country=US for a focused table.
Validate attribution — RevenueCat Attribution for customer-level keyword × campaign × country rows.
Act — pause campaigns, adjust bids, or add negatives via Campaigns and Keywords, or ask your assistant via MCP.

MCP Tools

Tool	Description
`asa_playbook_status`	Integration readiness checklist
`asa_admaxxing_recommendations`	Full optimization bundle (setup + ROAS + attribution + review gate)
`asa_review_country_gate`	Country rating vs active campaign targeting
`asa_profitability`	ROAS join; supports `country` filter

See Apple Search Ads MCP Tools for parameters and example prompts.

​What This Covers

​Prerequisites

​Integration Readiness

​Headers

​Example

​Response

​Step statuses

​Optimization Recommendations

​Query parameters

​Headers

​Example

​Response shape

​Recommendation types

​Review Country Gate

​Query parameters

​Example

​Response

​Row status

​Country-Scoped Profitability

​Typical Workflow

​MCP Tools

​Related Docs

What This Covers

Prerequisites

Integration Readiness

Headers

Example

Response

Step statuses

Optimization Recommendations

Query parameters

Headers

Example

Response shape

Recommendation types

Review Country Gate

Query parameters

Example

Response

Row status

Country-Scoped Profitability

Typical Workflow

MCP Tools

Related Docs