> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/ppc/apple-search-ads.md).

# Apple Search Ads

Export Apple Search Ads campaigns, keywords, and ad performance to Google Sheets, BigQuery, or Claude via Coupler.io automated reporting.

Apple Search Ads is Apple's advertising platform for promoting apps on the App Store. Connect it to Coupler.io to automatically export your campaign performance, keyword data, demographic insights, and more to Google Sheets, Excel, BigQuery, Looker Studio, or AI destinations like Claude and ChatGPT.

## Why connect Apple Search Ads to Coupler.io?

* **Automated reporting** — Schedule daily, weekly, or monthly exports without manual work
* **Flexible report types** — Pull campaign, ad group, keyword, and search term performance data
* **Demographic insights** — Break down performance by age, gender, location, and device
* **Multi-account support** — Combine data from multiple Apple Search Ads accounts in one data flow
* **AI-powered analysis** — Send reports to Claude or ChatGPT for instant insights

## Prerequisites

* Active Apple Search Ads account with at least one ad account
* **API Account Manager** role (or equivalent) assigned to your Apple Search Ads user — account admin permissions alone are not enough
* Access to Apple Search Ads settings to verify API access

{% hint style="warning" %}
Do NOT use your main admin account if it doesn't have the API Account Manager role. Create a dedicated user with the correct API permissions, or ask your Apple Search Ads account owner to assign the role to your current account.
{% endhint %}

## Quick start

{% hint style="success" %}
Start by selecting your ad account and report type (e.g., Campaign performance), then set your date range. A single data flow can pull multiple report types — just set up each one and run them together.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Log in to Coupler.io** and create a new data flow. Choose **Apple Search Ads** as your source.
{% endstep %}

{% step %}
**Sign in with Apple Search Ads.** Click the OAuth button and you'll be redirected to Apple's login page. Sign in with your Apple Search Ads account (the one with API Account Manager role) and authorize Coupler.io to access your data.
{% endstep %}

{% step %}
**Select your ad account(s).** Choose which Apple Search Ads account(s) you want to pull data from. You can select multiple accounts to combine them in one data flow.
{% endstep %}

{% step %}
**Choose a report type.** Pick from Campaign performance, Ad group performance, Ad performance, Keyword performance, Search term performance, or demographic/geographic insights reports.
{% endstep %}

{% step %}
**Set your date range.** Use the date picker to select your start and end dates. You can also use macros (like `{{30daysago}}`) to make the range dynamic.
{% endstep %}

{% step %}
**Choose how to split data.** Select Daily, Weekly, Monthly, or Totals only to control how your metrics are aggregated in the report.
{% endstep %}

{% step %}
**Select dimensions (if applicable).** For demographic and geographic reports, choose dimensions like Age, Gender, Country, or Device class. You can combine dimensions (e.g., Country and Device class together).
{% endstep %}

{% step %}
**Pick your destination.** Choose where to send the data: Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination like Claude or ChatGPT.
{% endstep %}

{% step %}
**Run the data flow.** Click **Run** to execute the data flow manually. Once it completes successfully, you can schedule it for recurring exports.
{% endstep %}
{% endstepper %}

## Apple Search Ads data overview

Apple Search Ads reports provide detailed performance metrics for your app campaigns. Each report type offers different levels of granularity and dimensions.

## Available report types

| Report Type                        | Description                            | Data Granularity                 |
| ---------------------------------- | -------------------------------------- | -------------------------------- |
| Campaign performance               | Overall campaign metrics               | By campaign                      |
| Ad group performance               | Ad group-level performance             | By ad group                      |
| Ad performance                     | Individual ad creative metrics         | By ad                            |
| Keyword performance                | Keyword bid and performance data       | By keyword                       |
| Search term performance            | Actual search terms that triggered ads | By search term                   |
| Campaign demo & geo insights       | Demographics and geography by campaign | By campaign + selected dimension |
| Ad group demo & geo insights       | Demographics and geography by ad group | By ad group + selected dimension |
| Ad performance by country          | Ad metrics split by country            | By ad + country                  |
| Keyword performance by country     | Keyword metrics split by country       | By keyword + country             |
| Search term performance by country | Search term metrics split by country   | By search term + country         |

## Common metrics available

#### Performance metrics

| Metric           | Definition                                      |
| ---------------- | ----------------------------------------------- |
| Impressions      | Number of times your ads were displayed         |
| Taps             | Number of times users tapped your ad            |
| Installs         | Number of app installs driven by your ads       |
| In-app purchases | Revenue from in-app purchases                   |
| Conversions      | App installs and re-engagements                 |
| Conversion rate  | Percentage of taps that resulted in conversions |
| Cost             | Total spend on ads                              |
| Cost per install | Average cost to acquire one install             |
| Cost per tap     | Average cost per user tap                       |

#### Bidding and campaign metrics

| Metric      | Definition                                           |
| ----------- | ---------------------------------------------------- |
| Bid         | Your current bid amount for that keyword or ad group |
| Status      | Active, paused, or other campaign status             |
| Campaign ID | Unique identifier for the campaign                   |
| Ad group ID | Unique identifier for the ad group                   |

## Available dimensions

#### Geographic dimensions

| Dimension  | Values                                      |
| ---------- | ------------------------------------------- |
| Country    | Two-letter country codes (e.g., US, GB, JP) |
| Admin area | States/provinces (e.g., CA, TX, ON)         |
| Locality   | Cities                                      |

#### Demographic dimensions

| Dimension | Values                                 |
| --------- | -------------------------------------- |
| Age       | 18-24, 25-34, 35-44, 45-54, 55-64, 65+ |
| Gender    | Female, Male, Unknown                  |

#### Device dimensions

| Dimension    | Values       |
| ------------ | ------------ |
| Device class | iPhone, iPad |

## Common metric combinations

* **Campaign + Demographic insights** — Understand which age groups and genders drive the most installs and revenue
* **Keyword performance by country** — Identify which keywords perform best in specific geographic markets
* **Ad performance by device** — Compare iPhone vs. iPad campaign effectiveness
* **Search term performance** — Discover high-intent search terms to bid on or negative keywords to exclude

## Use cases by role

{% tabs %}
{% tab title="App Marketing Managers" %}
Pull weekly campaign and ad group performance reports to track KPIs like install volume, cost per install, and return on ad spend. Combine multiple ad accounts in one data flow using **Append** to consolidate reporting across all your app campaigns.
{% endtab %}

{% tab title="Performance Analysts" %}
Use demographic and geographic reports to identify high-performing audience segments. Export search term data to discover new keyword opportunities and negative keywords. Schedule daily exports to monitor bid performance and adjust strategy in near-real-time.
{% endtab %}

{% tab title="Marketing Finance Teams" %}
Track total spend and cost per install across all campaigns. Use **Aggregate** transformations to calculate monthly spend trends and ROI by campaign. Export to BigQuery for advanced financial modeling.
{% endtab %}

{% tab title="Product & Revenue Teams" %}
Monitor install and in-app purchase metrics by campaign and geography. Identify which markets and demographics drive the highest lifetime value. Use AI destinations (Claude, ChatGPT) to generate insights from raw performance data.
{% endtab %}
{% endtabs %}

## Platform-specific notes

* **Date range flexibility** — You can use dynamic macros in date fields (e.g., `{{30daysago}}`, `{{yesterday}}`) to keep reports current
* **Multiple accounts** — If you manage multiple Apple Search Ads accounts, select all of them in one data flow and use **Append** to combine the data
* **Demographic data availability** — Demographic and geographic reports only work with campaigns that have targeting enabled; some app types may have limited demographic data
* **Search term reports** — Search term performance data includes exact search queries users entered, useful for keyword research and negative keyword identification
* **Data refresh timing** — Apple Search Ads data is typically available within a few hours of the end of the reporting period

## Apple Search Ads common issues

### Connection issues

<details>

<summary>I can't see the OAuth login button or sign-in fails</summary>

Make sure your Apple Search Ads account is active and you have the correct login credentials. If you're seeing a blank page during the OAuth flow:

1. Clear your browser cache and cookies
2. Try a different browser
3. Make sure you're not using a VPN or proxy that might block the OAuth redirect
4. Check that your Apple ID has been added to the Apple Search Ads account

If the issue persists, contact Coupler.io support with your browser console error details.

</details>

<details>

<summary>I see a "Public Key" field missing in Apple Search Ads settings</summary>

The Public Key field only appears for users with the **API Account Manager** role. If you're logged in as an admin but don't see it:

1. Ask your account owner to assign the **API Account Manager** role to your user account
2. Alternatively, have your account owner create a new user with API Account Manager permissions
3. Log out and back in after the role is assigned

This is an Apple requirement and cannot be bypassed.

</details>

### Missing data

<details>

<summary>The data flow runs but returns no data</summary>

Common causes:

1. **Empty date range** — Your selected date range may have no campaign activity. Try expanding the date range to include more recent dates.
2. **No campaigns running** — If you have no active campaigns in the selected date range, the report will be empty. Check Apple Search Ads directly to confirm campaign status.
3. **Wrong ad account selected** — Verify you've selected the correct ad account(s) from the dropdown.
4. **Demographic data not available** — If you're using a demographic/geographic report on a campaign without demographic targeting enabled, there will be no data. Switch to a standard report type instead.

Run a manual test with a wider date range first to confirm data exists.

</details>

<details>

<summary>Some metrics are missing from my report</summary>

Apple Search Ads doesn't report all metrics for all report types. For example:

* **In-app purchase revenue** is only available if your app tracks purchase events
* **Conversion data** requires in-app tracking setup in App Analytics
* **Device class** dimension is only available on certain report types

If you expect a metric but it's not appearing, verify that your app campaign supports tracking for that metric in Apple Search Ads directly.

</details>

### Permission errors

<details>

<summary>I'm getting an "access denied" or permission error</summary>

Your Apple Search Ads user account is missing the required API permissions. To fix:

1. Log in to Apple Search Ads with your account owner credentials
2. Go to **Settings** → **Users**
3. Find your user account and assign the **API Account Manager** role (or **API Analyst** if available)
4. Wait a few minutes for the permissions to sync
5. Log out of Coupler.io and reconnect by creating a new connection

If you're the account owner and still see the error, contact Apple Search Ads support to verify your account status.

</details>

<details>

<summary>The connection works but I can only see one ad account when I should see more</summary>

Your user account may not have access to all ad accounts. In Apple Search Ads:

1. Verify you have the correct role assigned across all accounts you manage
2. Check that you haven't been restricted to specific accounts
3. Ask your account owner to grant access to additional ad accounts if needed

You'll only see ad accounts in Coupler.io that your user has access to in Apple Search Ads.

</details>

### Data discrepancies

<details>

<summary>The numbers in Coupler.io don't match Apple Search Ads directly</summary>

Small discrepancies (usually <1%) can occur due to:

1. **Rounding** — Coupler.io and Apple may round metrics differently
2. **Time zone differences** — Ensure your date range and time zone match Apple's reporting settings
3. **Real-time vs. finalized data** — If you're pulling data for today or yesterday, metrics may still be updating. Wait until the next day for finalized numbers.

To minimize discrepancies, always export data for completed date ranges (at least 1 day in the past).

</details>

<details>

<summary>Search term data is inconsistent or missing some terms</summary>

Apple Search Ads uses privacy safeguards to protect user data:

1. **Low-volume terms** — Search terms with very few impressions may not be reported to protect user privacy
2. **Identical term grouping** — Plurals and similar variations may be grouped as a single term
3. **Data availability delay** — Search term data may lag by a few hours compared to campaign metrics

This is an Apple Search Ads limitation and not a Coupler.io issue.

</details>

### Rate limits

<details>

<summary>I'm getting rate limit errors when running multiple data flows</summary>

Apple Search Ads has API rate limits. If you're running many data flows at once:

1. **Stagger your runs** — Don't run all data flows simultaneously. Spread them across different times.
2. **Reduce frequency** — If you have many flows, consider scheduling them for different hours or days.
3. **Combine reports** — Use a single data flow with multiple report types instead of separate flows.

If you regularly hit rate limits, contact Coupler.io support to discuss your setup.

</details>

## Apple Search Ads FAQ

<details>

<summary>What's the difference between "API Account Manager" and account admin in Apple Search Ads?</summary>

Account admin (the default role) grants access to campaign management and reporting within Apple Search Ads, but does NOT grant API access. The **API Account Manager** role is a separate permission that specifically enables third-party tools like Coupler.io to pull data via the API. You need both the account and the API role to connect successfully. Many users make the mistake of assuming admin access includes API access — it doesn't.

</details>

<details>

<summary>Can I use Coupler.io to manage bids or pause campaigns?</summary>

No. Coupler.io only reads (exports) data from Apple Search Ads. You cannot create campaigns, adjust bids, or pause campaigns through Coupler.io. Use the Apple Search Ads dashboard for campaign management. Coupler.io is purely for reporting and analysis.

</details>

<details>

<summary>How often should I schedule my data flows?</summary>

It depends on your needs:

* **Campaign performance** — Daily (run at 6-8 AM so you capture the previous day's complete data)
* **Keyword performance** — Daily or weekly depending on how quickly you optimize bids
* **Demographic insights** — Weekly (demographic data is slower to finalize)
* **Search term performance** — Weekly (useful for spotting trends and new keywords)

Avoid multiple runs on the same day unless you're testing, to stay within API rate limits.

</details>

<details>

<summary>Can I combine data from multiple Apple Search Ads accounts in one report?</summary>

Yes. In your data flow, select multiple ad accounts from the dropdown. All data will be pulled together. Then use the **Append** transformation to stack the data from different accounts into a single sheet or table. You can add an account name or ID column to distinguish between them.

</details>

<details>

<summary>What's the difference between "Campaign performance" and "Campaign demo &#x26; geo insights"?</summary>

**Campaign performance** gives you standard metrics (impressions, taps, installs, spend) aggregated by campaign.

**Campaign demo & geo insights** breaks down those same metrics by demographic (age, gender) and geographic (country, state, city) dimensions. Use demographics if you want to know which age groups and genders are most valuable; use geography if you want to see which countries/regions drive the best ROI.

</details>

<details>

<summary>Why is there a lag between when data appears in Apple Search Ads and when I can pull it with Coupler.io?</summary>

Apple Search Ads updates metrics in real-time for immediate campaign monitoring, but finalizes data for reporting purposes after a few hours. Coupler.io pulls finalized data to ensure accuracy. This is why we recommend scheduling exports for the previous day rather than the current day.

</details>

<details>

<summary>Can I export data to both Google Sheets and BigQuery at the same time?</summary>

Not in a single data flow. Create two separate data flows: one for Google Sheets and one for BigQuery. Both will pull the same data from Apple Search Ads. Alternatively, export to BigQuery first, then use a separate tool to sync that data to Sheets if needed.

</details>

<details>

<summary>What if I'm getting a "Public Key" error?</summary>

The Public Key field in Apple Search Ads is only visible to users with the **API Account Manager** role. If you don't see this field:

1. Ask your account owner to assign the API Account Manager role to your user
2. Wait 5-10 minutes for the permission to sync
3. Log out of Apple Search Ads and log back in
4. Return to Settings → API and you should now see the Public Key

If you're the account owner and still don't see it, contact Apple Search Ads support.

</details>

<details>

<summary>Can I use Coupler.io to pull historical data from years ago?</summary>

Yes. Use the date picker to set any start and end date. Apple Search Ads typically keeps 2 years of historical data available. Very old data (beyond 2 years) may no longer be accessible via the API.

</details>

<details>

<summary>How do I find my Apple Search Ads account ID to select in Coupler.io?</summary>

Your account ID appears in the dropdown when you connect. You'll see a list of all Apple Search Ads accounts you have access to. If you only see one account but manage multiple, ask your account owner to confirm you have access to all accounts in Apple Search Ads.

</details>

{% hint style="info" %}
For more details on available metrics and dimensions, see the [Data Overview](#apple-search-ads-data-overview) article. For troubleshooting connection and permission issues, check [Common Issues](#apple-search-ads-common-issues).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/ppc/apple-search-ads.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
