Apple Search Ads is the primary channel for app discovery in the App Store, reaching users with high intent at the exact moment they search for apps. Understanding the full set of dimensions and metrics available through the Apple Search Ads API is essential for building effective dashboards, optimizing keyword bids, and making data-driven decisions about your app marketing budget.
This guide provides a complete reference of every dimension and metric available in Apple Search Ads as of 2026. We've organized them by category, included the API field names for developers, and added practical context on when and how to use each one — from campaign structure to keyword attribution.
How Apple Search Ads Data Is Structured
Apple Search Ads follows a three-level hierarchy: Campaign > Ad Group > Keyword. Campaigns define the budget, storefront (country), and app being promoted. Ad groups control targeting criteria, bid settings, audience selection, and Creative Sets. Keywords (or Search Match auto-targeting) determine which search queries trigger your ad. Metrics can be queried at any level and support daily granularity.
The Apple Search Ads API returns dimensions as entity fields and metrics through reporting endpoints. Reports support breakdowns by time period, age, gender, device class, and geographic location. The API distinguishes between Search results ads (top of search) and Search tab ads (Suggested section), each with separate metrics.
Campaign-Level Dimensions
Campaign-level dimensions define the top-level structure of your Apple Search Ads account. These fields identify the campaign, its budget, the target storefront, and the app being promoted.
| Dimension | API Field | Description |
|---|---|---|
| Campaign ID | campaignId | Unique identifier for the campaign |
| Campaign Name | campaignName | Name of the campaign as defined by the advertiser |
| Campaign Status | campaignStatus | Status: ENABLED, PAUSED, or REMOVED |
| Display Status | displayStatus | Computed status: RUNNING, ON_HOLD, PAUSED, or various error states |
| App ID | adamId | App Store ID (adam ID) of the promoted app |
| App Name | appName | Name of the promoted app as it appears on the App Store |
| Budget Amount | budgetAmount | Total campaign budget in the campaign's currency |
| Daily Budget | dailyBudgetAmount | Maximum daily spend for the campaign |
| Budget Orders | budgetOrders | Budget order references for invoiced accounts |
| Storefront | countriesOrRegions | App Store country or region where ads appear (US, GB, JP, etc.) |
| Supply Sources | supplySources | Ad placement type: APPSTORE_SEARCH_RESULTS, APPSTORE_SEARCH_TAB, APPSTORE_TODAY_TAB |
| Ad Channel Type | adChannelType | Channel: SEARCH (keyword-based) or DISPLAY (Today tab, Search tab) |
| Start Time | startTime | Campaign start date in ISO 8601 format |
| End Time | endTime | Campaign end date (null if no end date) |
| Org ID | orgId | Organization identifier the campaign belongs to |
| Modified Time | modificationTime | Timestamp of the last modification |
Ad Group-Level Dimensions
Ad group dimensions control targeting, bidding, audience selection, and Creative Set assignments. This is where you define who sees your ads, what bid you're willing to pay, and how the ad creative appears to users.
| Dimension | API Field | Description |
|---|---|---|
| Ad Group ID | adGroupId | Unique identifier for the ad group |
| Ad Group Name | adGroupName | Name of the ad group as defined by the advertiser |
| Ad Group Status | status | Status: ENABLED, PAUSED, or REMOVED |
| Display Status | displayStatus | Computed status accounting for parent campaign state |
| Default Bid | defaultBidAmount | Default CPT (cost per tap) bid for all keywords in the group |
| CPA Goal | cpaGoal | Target CPA (cost per acquisition) for the ad group |
| Automated Keywords | automatedKeywordsOptIn | Whether Search Match (automatic keyword matching) is enabled |
| Start Time | startTime | Ad group start date |
| End Time | endTime | Ad group end date (null if no end date) |
| Target Age Min | targetingDimensions.age.minAge | Minimum target age (18+) |
| Target Age Max | targetingDimensions.age.maxAge | Maximum target age |
| Target Gender | targetingDimensions.gender | Gender targeting: MALE, FEMALE, or ALL |
| Target Device Class | targetingDimensions.deviceClass | Device type: IPHONE, IPAD, or both |
| Target Localities | targetingDimensions.locality | Geographic targeting within the storefront country |
| Customer Type | targetingDimensions.appDownloaders | Target: ALL_USERS, NEW_USERS (never installed), RETURNING_USERS (reinstalls), or USERS_OF_MY_OTHER_APPS |
| Daypart | targetingDimensions.daypart | Day and time scheduling for ad delivery |
Keyword-Level Dimensions
Keyword dimensions identify the search terms you're bidding on and how they match to actual user queries. This is the most granular level in Apple Search Ads and where most optimization decisions happen — adjusting bids, pausing underperforming keywords, and discovering new opportunities.
| Dimension | API Field | Description |
|---|---|---|
| Keyword ID | keywordId | Unique identifier for the keyword |
| Keyword Text | text | The actual keyword text being bid on |
| Keyword Status | status | Status: ACTIVE, PAUSED, or REMOVED |
| Match Type | matchType | How the keyword matches queries: EXACT (precise match) or BROAD (related terms) |
| Bid Amount | bidAmount | CPT bid for this specific keyword (overrides ad group default) |
| Keyword Display Status | displayStatus | Computed status including relevance flags and parent states |
| Modified Time | modificationTime | When the keyword was last modified |
Search Match and Search Term Dimensions
Search Match is Apple Search Ads' automatic targeting feature that matches your ad to relevant queries based on your app's metadata. Search term reports reveal the actual queries users typed before seeing and tapping your ad — essential for keyword discovery and negative keyword optimization.
| Dimension | API Field | Description |
|---|---|---|
| Search Term Text | searchTermText | The actual query the user typed in the App Store search |
| Search Term Source | searchTermSource | How the term was matched: TARGETED (from keyword bid) or AUTO (from Search Match) |
| Keyword | keyword | The keyword that matched this search term (null for Search Match auto terms) |
| Match Type | matchType | Match type used: EXACT, BROAD, or SEARCH_MATCH |
Creative Set Dimensions
Creative Sets let you customize which App Store screenshots and app previews appear in your ad. Instead of showing the default set, you can create variations that highlight different features, themes, or value propositions to test which visuals resonate best with each audience segment.
| Dimension | API Field | Description |
|---|---|---|
| Creative Set ID | adId | Unique identifier for the Creative Set (ad variation) |
| Creative Set Name | name | Name of the Creative Set as defined by the advertiser |
| Creative Set Status | status | Status: ENABLED, PAUSED, or REMOVED |
| Creative Type | creativeType | Type of creative: CUSTOM_PRODUCT_PAGE or DEFAULT |
| Product Page ID | productPageId | App Store Custom Product Page linked to this Creative Set |
Core Performance Metrics
These are the fundamental metrics that measure how your Apple Search Ads are delivered and interacted with. They form the basis of all campaign analysis and bid optimization decisions.
| Metric | API Field | Description | Formula / Notes |
|---|---|---|---|
| Impressions | impressions | Number of times your ad was shown in search results | Counts each time the ad appeared on screen |
| Taps | taps | Number of times users tapped on your ad | Taps on the ad unit, not the app icon — directs to App Store page |
| TTR (Tap-Through Rate) | ttr | Percentage of impressions that resulted in a tap | (Taps ÷ Impressions) × 100 |
| Installs | installs | New first-time downloads of your app | Users who have never downloaded the app before |
| New Downloads | newDownloads | Total new app downloads from the ad | Includes first-time installs only |
| Redownloads | redownloads | Downloads by users who previously had the app | Users who deleted and re-installed the app |
| Total Conversions | totalInstalls | Installs + Redownloads combined | All app acquisitions attributed to the ad |
| Conversion Rate | conversionRate | Percentage of taps that resulted in a conversion | (Total Conversions ÷ Taps) × 100 |
| Spend | localSpend | Total amount spent in the campaign's currency | Actual billed amount based on auction results |
| Average CPA | avgCPA | Average cost per acquisition | Spend ÷ Total Conversions |
| Average CPT | avgCPT | Average cost per tap | Spend ÷ Taps |
| Average CPM | avgCPM | Average cost per 1,000 impressions | (Spend ÷ Impressions) × 1,000 |
Conversion Metrics (Installs and Redownloads)
Apple Search Ads provides detailed conversion tracking that distinguishes between new installs and redownloads, with further segmentation by LAT (Limit Ad Tracking) status. Understanding these distinctions is critical for accurate user acquisition cost analysis.
| Metric | API Field | Description |
|---|---|---|
| LAT On Installs | latOnInstalls | Installs from users with Limit Ad Tracking enabled |
| LAT Off Installs | latOffInstalls | Installs from users with Limit Ad Tracking disabled (full attribution available) |
| LAT On Redownloads | latOnRedownloads | Redownloads from LAT-on users |
| LAT Off Redownloads | latOffRedownloads | Redownloads from LAT-off users (full attribution) |
| Total New Downloads | totalNewDownloads | Sum of LAT-on and LAT-off new installs |
| Total Redownloads | totalRedownloads | Sum of LAT-on and LAT-off redownloads |
| Cost Per Install | costPerInstall | Spend ÷ New Installs |
| Cost Per Redownload | costPerRedownload | Spend ÷ Redownloads |
| Install Rate | installRate | Percentage of taps that resulted in an install |
| Redownload Rate | redownloadRate | Percentage of taps that resulted in a redownload |
Audience Breakdown Dimensions
Apple Search Ads provides several breakdown dimensions to segment your metrics by user characteristics. These are essential for understanding which demographics and device types drive the best conversion rates and for optimizing your targeting within ad groups.
Demographic Breakdowns
| Breakdown | API Field | Description |
|---|---|---|
| Age Range | ageRange | Age bracket: 18-24, 25-34, 35-44, 45-54, 55-64, 65+ |
| Gender | gender | MALE, FEMALE, or UNKNOWN |
| Country or Region | countryOrRegion | Storefront country code (US, GB, JP, etc.) |
| Admin Area | adminArea | State, province, or administrative region within the country |
| Locality | locality | City or local area within the administrative region |
Device and Platform Breakdowns
| Breakdown | API Field | Description |
|---|---|---|
| Device Class | deviceClass | IPHONE or IPAD |
| Customer Type | customerType | NEW_USERS, RETURNING_USERS, or ALL_USERS |
Attribution and Tracking
Apple Search Ads uses deterministic, first-party attribution through the Apple Ads Attribution API. Unlike probabilistic models used by third-party MMPs, Apple's attribution is exact because it uses Apple ID-level data. Understanding how attribution works is critical for accurate performance measurement and for integrating with your broader marketing analytics stack.
| Dimension | API Field | Description |
|---|---|---|
| Attribution | attribution | Whether the install was attributed to Apple Search Ads (true/false) |
| Campaign ID (Attribution) | campaignId | Campaign that drove the install (from Attribution API response) |
| Ad Group ID (Attribution) | adGroupId | Ad group that drove the install |
| Keyword (Attribution) | keyword | Keyword that triggered the ad (from Attribution API) |
| Ad ID (Attribution) | adId | Creative Set ID that was displayed when the user tapped |
| Click Date | clickDate | Date the user tapped the ad (used for attribution window calculation) |
| Conversion Date | conversionDate | Date the app was downloaded/installed |
| Attribution Window | attributionWindow | Default 30-day window from tap to install |
| AdServices Token | token | iOS 14.5+ AdServices framework attribution token for privacy-compliant tracking |
Optimization Tips for Apple Search Ads
Apple Search Ads operates differently from social and display advertising because users have explicit search intent. Here's a framework for using the right metrics at each stage of your optimization process.
For keyword discovery and expansion
Run Search Match in dedicated ad groups with moderate bids to discover new keywords. Review the search term report weekly to find high-performing queries. Graduate terms with strong conversion rates to exact match keyword ad groups with optimized bids. Add poor-performing or irrelevant search terms as negative keywords to prevent wasted spend.
For bid optimization
Focus on CPA (cost per acquisition) as your primary efficiency metric. Compare CPA against your target by keyword — increase bids on keywords with CPA below target and strong volume, decrease bids on keywords above target. Use TTR to assess ad relevance — low TTR on high-volume keywords suggests your app listing doesn't match user intent for those terms. Track CPT trends to understand competitive dynamics for your keywords.
For audience optimization
Break down metrics by age, gender, and device class to identify your most efficient segments. If iPhone users convert at 2x the rate of iPad users, consider creating separate ad groups with device-specific Creative Sets and bid adjustments. Use the customer type dimension to compare new user acquisition costs versus redownload costs — target returning users separately when win-back campaigns are more cost-effective.
For Creative Set testing
Create multiple Creative Sets per ad group to A/B test which App Store screenshots and app previews drive the highest conversion rate. Focus on screenshots that highlight your app's primary value proposition for the keywords in each ad group. A fitness app might show workout screenshots for "workout app" keywords and nutrition features for "calorie tracker" keywords. Track TTR and conversion rate by Creative Set to identify winners.
For geographic optimization
Use admin area (state/province) and locality (city) breakdowns to identify geographic performance variations. CPA can vary 3-5x between regions due to different competitive landscapes and user behavior. Consider creating separate campaigns for high-volume storefronts (US, UK, Japan) with localized Creative Sets and bid strategies tailored to each market's competitive dynamics.
What Changed in 2024-2026: Updates and New Features
Apple has significantly expanded Search Ads capabilities over the past two years. Understanding these changes is important for anyone working with historical data or building new campaign strategies.
Today tab and Search tab ads
Apple expanded beyond search results to include Today tab ads and Search tab ads (previously called Suggested section). These placements have separate metrics and different performance characteristics. Today tab ads drive awareness with larger creative formats, while Search tab ads capture intent before users type a specific query. Track these through the supplySources campaign dimension.
Custom Product Pages integration
Creative Sets now support Custom Product Pages — distinct App Store landing pages that can be linked to specific ad groups. This enables keyword-to-page alignment: users searching for "meditation app" see meditation-focused screenshots and description, while "sleep sounds app" searchers see sleep-focused content. Track performance through the productPageId dimension.
AdServices framework changes
The AdServices framework (iOS 14.5+) replaced the older iAd Attribution API for privacy-compliant attribution. The new framework provides an attribution token that must be sent to Apple's server for validation. This token-based approach supports aggregate attribution without exposing individual user identifiers. Third-party MMPs have updated their SDKs to work with AdServices.
API version updates
Apple Search Ads API v5 introduced improved reporting endpoints with faster response times, new breakdown dimensions, and expanded Creative Set metrics. The older v4 endpoints are deprecated as of early 2026. Ensure your integration uses the latest API version for full metric availability.
Common Mistakes When Analyzing Apple Search Ads Data
These common errors can lead to flawed analyses and suboptimal bid decisions. Avoid them for more accurate Apple Search Ads management.
1. Treating installs and redownloads the same
New installs and redownloads represent fundamentally different user types. New installs expand your user base at typically higher CPA. Redownloads bring back lapsed users at lower cost but with potentially lower engagement. Evaluate them separately and consider different CPA targets for each.
2. Ignoring Search Match search terms
Search Match can waste significant budget on irrelevant queries if not monitored. Review search term reports at least weekly. Add negative keywords for irrelevant terms and promote high-performing terms to targeted keyword ad groups. Without this discipline, Search Match spend can exceed 40% of budget on low-converting queries.
3. Using TTR as the primary optimization metric
A high tap-through rate means your ad is compelling, but it doesn't mean users are installing. Focus on conversion rate (taps to installs) and CPA as your primary metrics. Some keywords have high TTR but low conversion rate because the search intent doesn't match the app's functionality.
4. Not accounting for LAT-on users in attribution
LAT-on installs are real conversions but lack individual attribution details. If you rely solely on attributed (LAT-off) installs, you're undercounting your actual conversions by 30-40%. Include LAT-on aggregate data in your total conversion and CPA calculations for accurate performance measurement.
5. Bidding the same CPT across all keywords
Different keywords have vastly different conversion rates and competitive dynamics. A branded keyword might convert at 50% while a generic category keyword converts at 5%. Setting one default bid means you overpay for easy conversions and underbid on competitive terms. Customize bids per keyword based on individual CPA performance.
6. Ignoring competitive seasonality
CPT and CPA fluctuate significantly during peak seasons (holiday shopping, back to school, New Year resolutions). Monitor CPT trends to detect rising competition and adjust budgets and bids accordingly. Set up alerts for CPA exceeding your threshold so you can respond quickly to market shifts.
