Get Apple Ads report
Qonversion cohort metrics joined with Apple Ads report data (spend,
impressions, taps, installs) for one level: campaigns, ad groups, or
keywords. Each row carries a qonversion block (cohort outcomes:
users, trials, revenue, ARPU/ARPPU), an apple block (spend and
delivery metrics, including avg_cpa — Apple’s average cost per
tap-through install), and a derived roas ratio.
CPA is not CAC. apple.avg_cpa is the cost of an install as Apple
reports it. The cost of acquiring a paying user is windows.<code>.cac
(window spend / payers — spend_closed in the mature reading, spend
in the growing one), available only when windows is requested. The
two differ by the whole install-to-payer funnel; never quote one as
the other.
Availability: available to accounts with Apple Ads enabled; other
accounts receive 404. Contact support to enable Apple Ads.
Data markers: apple is null for rows without Apple data;
partial_sources lists Apple data sources not included (empty when
complete); meta.partial_scope counts campaigns without Apple data.
Qonversion metrics are always complete.
Semantics: revenue is cohort revenue cumulative to date (only the
install date is bounded by [from, to]); roas is a ratio, not a
percentage, and not a closed ratio — revenue keeps accruing while
spend is bounded by the period. meta.semantics in every response
defines each metric.
Reporting basis: revenue_type selects the revenue behind the
derived metrics (roas, arpu, arppu, and windows.*.revenue /
windows.*.roas) — gross (store-billed, default) or net
(proceeds after store commission, and after store tax where the store
reports it). Rows always carry both revenue_gross and
revenue_net, so revenue_type never removes a field;
windows.*.cac and windows.*.cost_per_trial depend on spend only.
currency converts every monetary value at one midpoint rate for the
period (see meta.currency_conversion). If no exchange rate is
available for the period, values are in USD: currency is USD and
meta.rate_unavailable_for holds the requested code. Both
currency and revenue_type are echoed at the top level.
Cohort windows (optional, windows=): pass
windows=d7,d30,lifetime and each row also carries a windows block
of per-window cohort metrics (installs, trials, payers, revenue,
roas, cac, cost_per_trial). See the windows parameter and
meta.windows.
Cohort window modes (windows_mode=): growing is the to-date
cohort reading — every install of the period, events up to today, and
the row’s Apple spend for the period as the denominator; its values
change until the period matures. mature covers matured install
dates only — dates past the window length plus
maturation_buffer_days — so its ratios over that closed date range
are comparable across rows and periods of different ages (lifetime
can still change as cumulative revenue accrues). Both modes share
V4AnalyticsAppleAdsWindow; the growing one adds mode, through,
and spend and omits spend_closed. When windows_mode is omitted,
the server applies its default mode; send windows_mode explicitly
when the reading matters. If you omit it, check meta.windows.mode
(or a window’s own mode: growing) for the reading served. If
meta.windows.mode is absent, the response uses the mature reading.
Pagination: this endpoint uses limit/offset pagination with a
pagination block, not cursors. Offsets are stable within a sort
order.
Rate limits: the report and series endpoints are rate limited. A
429 response includes Retry-After; wait that long before
retrying.
Authorizations
Bearer authentication using the project Secret Key (prefixed with sk_), used exactly as shown in the dashboard. Endpoints that support sandbox data take an explicit environment field or parameter. All v4 public endpoints require the Secret Key — see Authentication. Never expose the Secret Key in client-side code.
Query Parameters
Hierarchy level of the report rows.
campaigns, groups, keywords Cohort window start (unix seconds, UTC). Installs attributed to Apple Ads within [from, to] form the cohort.
Cohort window end (unix seconds, UTC).
Environment: 0 = sandbox, 1 = production. Defaults to production when omitted.
0, 1 Revenue basis for the derived metrics: gross (store-billed amount) or net (proceeds — after store commission, and after tax where the store reports it). Affects roas, arpu, arppu, the revenue/refunds sort keys, and windows.*.revenue / windows.*.roas. It does not affect windows.*.cac or windows.*.cost_per_trial (both spend-only), and it never removes a field — qonversion.revenue_gross and qonversion.revenue_net are always both present. Echoed back as the top-level revenue_type.
gross, net ISO 4217 code (uppercase, exactly three letters — eur returns 400) for the monetary values. Values are converted from USD at one midpoint rate for the whole [from, to] period, reported in meta.currency_conversion (rate, rate_date, method: single_midpoint_rate). The rate is the one for the period's midpoint date, or the latest one before it.
If no exchange rate is available for the period, values are in USD: currency is USD and meta.rate_unavailable_for holds the requested code. Read the top-level currency to know which currency the values are in.
min_spend is compared against the converted spend, so it is in this currency too.
^[A-Z]{3}$"EUR"
Sort key — one of the wire metric names: spend, revenue, roas, installs, impressions, taps, ttr, cpa, cpt, cpm, new_downloads, redownloads, users, trials, trials_converted, paying, paying_weekly, paying_monthly, paying_annual, paying_other, in_apps, direct_subscriptions, subscription_starters, cost_per_subscription, cost_per_trial, arpu, arppu, refunds, user_to_trial, user_to_subscription, trial_to_paid. Note the sort keys are the SHORT metric names (cpa/cpt/cpm sort the avg_cpa/avg_cpt/avg_cpm columns; trials sorts trials_started; paying sorts unique_paying_users; subscription_starters sorts unique_subscription_starters; the four paying_ keys sort qonversion.unique_paying_users_by_duration.<bucket>).
A window sort key is also accepted; it additionally depends on the requested windows: window_roas_<code> / window_cac_<code> (e.g. window_roas_d7) orders rows by that window's ratio in the reading served (see windows_mode and meta.windows.mode): in the growing reading the ratio is to-date and not closed; in the mature reading it is the ratio over the closed date range (for lifetime not necessarily final, as cumulative revenue can still accrue). The key is rejected with 400 unless the same <code> is listed in windows. Unknown values are rejected with 400.
spend, revenue, roas, installs, impressions, taps, ttr, cpa, cpt, cpm, new_downloads, redownloads, users, trials, trials_converted, paying, paying_weekly, paying_monthly, paying_annual, paying_other, in_apps, direct_subscriptions, subscription_starters, cost_per_subscription, cost_per_trial, arpu, arppu, refunds, user_to_trial, user_to_subscription, trial_to_paid Sort direction.
asc, desc Case-insensitive substring match over the level entity name and id, applied before pagination. Narrows table rows only — total and unallocated stay whole-report.
64Keep only rows whose Apple spend is at least this threshold, compared against the converted apple.spend in the response currency. Rows without spend data never match and are counted in pagination.rows_without_spend_hidden.
x >= 0Level at which min_spend is evaluated. Must be the request level or a coarser one (e.g. keywords rows thresholded by their campaign's total spend).
campaigns, groups, keywords Maximum rows to return. Default 100; range 1–500, or 1–5000 when export=true.
1 <= x <= 5000Pagination offset.
x >= 0Lifts the limit ceiling to 5000 for one request. The response stays JSON. Accepts true/false or 1/0.
Optional cohort windows: a comma-separated subset of d0,d3,d7,d14,d30,d60,d90,d180,d365,lifetime. When present, every visible row (plus total and unallocated) carries a windows object keyed by the requested codes, and meta.windows describes the windows. Without this parameter no windows block is returned. windows_mode selects the reading (growing — every install of the period, counted to date — or mature). The closure rules below apply to the mature reading (windows_mode=mature); in the growing reading closed_from, closed_through, and is_closed are informational.
In the mature reading a window of nominal length n days (d0 means through the end of the install UTC day — not the first 24 hours from the install moment — so its effective length is 1 day; the same holds in the growing reading) covers only install dates that have fully matured. A date d is closed when both hold: today_utc - d >= length + maturation_buffer_days + 1 and today_utc - d >= meta.windows.spend_snapshot.rewrite_days_effective.
rewrite_days_effective is the number of recent days whose spend Apple can still restate; these dates are not treated as closed, whatever the window length or maturation_buffer_days.
Mature values therefore describe a closed subrange of [from, to] (closed_from to closed_through), not the whole requested window unless is_closed is true. lifetime never reports is_closed: true, because cumulative revenue keeps accruing.
Duplicate codes are ignored, and the codes are returned in canonical order regardless of input order. An unknown code, such as d31, returns 400 naming the invalid token.
"d0,d7,d30,lifetime"
Extra full days a cohort date must age past its window length before it counts as closed in the mature reading. Used with windows and echoed in meta.windows.maturation_buffer_days. meta.windows.spend_snapshot.rewrite_days_effective applies independently of this value.
0 <= x <= 30Which reading of the windows block to compute. Used only together with windows.
growing — the to-date reading: the cohort is every install of the row in [from, to], an event counts while it falls within the window length from its install and no later than today (through, the as-of UTC date), and the denominator is the row's Apple spend for the period (the same number as apple.spend). Values change day to day until the period matures; for a young period d<n> equals lifetime. Each window carries mode: growing, through, and spend (no spend_closed; so_far is null).
mature — only install dates that have fully matured past the window length plus maturation_buffer_days, with the spend of those closed dates (spend_closed) and the provisional so_far reading; windows carry no mode key.
When omitted, the server applies its default mode; send windows_mode explicitly when the reading matters.
If you omit windows_mode, check meta.windows.mode for the reading served (in the growing reading, each window also carries mode: growing). If meta.windows.mode is absent, the response uses the mature reading. Any other value returns 400 naming windows_mode.
growing, mature Narrow the Qonversion cohort (and the Apple report where Apple supports the split) by storefront country. Array-valued — repeat the key for multiple values; the scalar form filter[country]=US returns 400.
Narrow by campaign name. Array-valued — repeat the key for multiple values; the scalar form returns 400.
Narrow by ad group. On the groups and keywords levels it also narrows the Apple metrics; on the campaigns level it narrows the Qonversion cohort only. Array-valued — repeat the key for multiple values; the scalar form returns 400.
Narrows the Qonversion cohort only; Apple spend is not split by media source. Array-valued — repeat the key for multiple values; the scalar form returns 400.
Keep rows whose Apple entity status matches. When Apple entity status is not available for the report, this filter matches no rows and meta.status_data_unavailable is true.
active, paused, archived Keep rows whose delivery state matches. When Apple entity status is not available for the report, this filter matches no rows and meta.status_data_unavailable is true.
delivering, not_delivering Exclude these media sources from the Qonversion cohort — the complement of filter[media_source_name][]. Array-valued: repeat the key for multiple values.
filter_not[media_source_name][] is the only supported exclusion; filter_not on the other filters of this report (country, campaign_name, ad_set_name, status, delivery) returns 400.
Response
Apple Ads report for the requested level.
analytics_apple_ads_report campaigns, groups, keywords Currency of the monetary values — the currency request parameter (default USD). If no exchange rate is available for the period, values are in USD: currency is USD and meta.rate_unavailable_for holds the requested code.
Revenue basis of the derived metrics (roas, arpu, arppu, windows.*.revenue, windows.*.roas) — the echo of the revenue_type request parameter, default gross.
gross, net Apple data sources not included in this response (apple_report — Apple report metrics, apple_status — Apple entity status); empty when complete. Rows without Apple data have apple: null. Qonversion metrics are always complete.
apple_report, apple_status Response metadata — data timestamps (updated_at), is_partial_period, currency_conversion, rate_unavailable_for, status_data_unavailable, partial_scope, the request echo (request), the window details (windows, when requested), and the semantics dictionary that defines every metric (population, revenue bases, trial event counting, roas, filters, status and delivery, timezone).
false when Apple entity status is not available for this report; filter[status] and filter[delivery] then match no rows.
Whole-report totals row (unaffected by q, min_spend, status filters, and pagination). Carries the qonversion and apple blocks and the derived roas, cost_per_subscription, and cost_per_trial (plus windows when requested), with no campaign, ad group, or keyword block. The derived values are computed from the whole-report numerator and denominator, not summed from the rows on the page.
- Option 1
- Option 2
Spend and metrics Apple reports for the period that no row accounts for (for example, Search Match discovery spend without keywords). Carries the qonversion and apple blocks plus the derived ratios (and windows when requested); qonversion is always null here, and so is every cohort-based ratio (roas, cost_per_subscription, cost_per_trial).
- Option 1
- Option 2