Skip to main content
Use the Apple Ads read endpoints to combine Apple advertising data with Qonversion cohort outcomes and to check the status of your Apple Ads connection. Requests use your project’s Secret Key as a Bearer token. Available to accounts with Apple Ads enabled; other accounts receive 404. Contact support to enable Apple Ads. All paths are relative to https://api.qonversion.io/v4. Through MCP, these reads require the analytics:read scope.

​
Read a report

GET /analytics/apple-ads/report requires from and to as Unix timestamps in seconds. They bound the cohort’s install dates; cohort revenue keeps accumulating after those dates.
level is campaigns (default), groups, or keywords. Optional environment defaults to 1 (production); 0 selects sandbox. revenue_type is gross (default) or net, and currency is an uppercase three-letter currency code (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. The response has object: "analytics_apple_ads_report", rows, whole-report total, unallocated where applicable, pagination, partial_sources, and meta. A row contains entity identity, qonversion cohort metrics, apple advertising metrics, and derived ratios. roas is a ratio, not a percentage. Apple’s avg_cpa is cost per tap-through install; it is different from the cost of acquiring a paying user (windows.<code>.cac).

​
Filters and pagination

Use filter[country][], filter[campaign_name][], filter[ad_set_name][], and filter[media_source_name][] to include values. filter[media_source_name][] narrows the Qonversion cohort only; Apple spend is not split by media source. filter[status] accepts active, paused, or archived; filter[delivery] accepts delivering or not_delivering. filter_not[media_source_name][] is the only supported exclusion; filter_not on the other filters above returns 400. meta.request.filters_applied lists the filters applied to the response. q searches entity names and IDs. min_spend keeps rows whose Apple spend, in the response currency, is at least the given value; min_spend_scope evaluates it at the requested level or a coarser one. These row filters and pagination do not change total, which always covers the whole report. The report uses limit/offset, not cursors. limit defaults to 100 and accepts 1–500; with export=true it accepts up to 5000, and the response stays JSON. Use sort and sort_dir (asc or desc) to order rows. A window sort such as window_roas_d7 requires the same d7 window in windows.

​
Cohort window modes

Request a comma-separated subset of d0,d3,d7,d14,d30,d60,d90,d180,d365,lifetime in windows. Set windows_mode explicitly when the reading matters:
  • mature includes only fully matured install dates and uses spend_closed, the spend of the closed dates. A window can cover a closed subrange of the selected dates.
  • growing includes all installs in the selected period, counts outcomes observed so far up to each window’s boundary, and uses the row’s Apple spend for that period. Its window block uses spend instead of spend_closed.
If you omit windows_mode, check meta.windows.mode for the reading served. If meta.windows.mode is absent, the response uses the mature reading. d0 ends at the end of the install UTC day, and lifetime never closes. Revenue of closed install dates can still change with later refunds or revenue corrections. The mature reading also applies maturation_buffer_days (0–30, default 4). meta.windows.spend_snapshot.rewrite_days_effective is the number of recent days whose spend Apple can still restate; these dates are not treated as closed. 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. meta.is_partial_period is true when the period includes a UTC day that has not ended. A missing value means no value is available, not zero. See Apple Ads via MCP for metric interpretation shared by both interfaces.

​
Read a daily series

GET /analytics/apple-ads/report/series requires from and to. It accepts environment, revenue_type, currency, the filters above, and one metric: spend, installs, taps, users, trials, trials_converted, paying, revenue, arpu, arppu, roas, or cost_per_subscription. The default is spend.
The response has object: "analytics_apple_ads_series", metric, unit: "day", currency, revenue_type, semantics, is_cohort_metric, points: [{date, value}], and filters_ignored. Spend-based metrics also report coverage. A series returns at most 366 daily points; for a longer period, the oldest days are omitted and truncated is true. Use this endpoint rather than requesting one report per day. For a cohort metric, a point represents the cohort acquired on that date, measured to date; it does not represent revenue collected on that date. A null point means no value is available for that day; it is not zero. Filters that do not apply to the requested metric, including filter[status] and filter[delivery], are listed in filters_ignored. The series takes one metric and returns daily points. Report level, sorting, pagination, and window parameters do not apply to this request.

​
Check the connection

GET /integrations/apple-ads/connection takes no query parameters. It returns object: "apple_ads_connection", the connection state, separate reporting and campaign_management readiness, the Apple Ads organizations in orgs, next_action, and dashboard_url. connected does not imply campaign-management access; check campaign_management.can_write and the organization of the campaign. legacy_credentials is a working connection with an API key. verifying means the connection is awaiting confirmation from Apple. A campaign-management state of unknown means campaign-management permissions are not confirmed yet; check again later. This endpoint returns status only and does not start or complete Apple authorization. Use dashboard_url to connect or reconnect Apple Ads in the dashboard. No private key or OAuth token is returned.

​
Campaign changes through MCP

Campaign changes are available only through the Qonversion MCP server, for a signed-in dashboard user with permission to manage campaigns and the apple_ads:write scope; they cannot be made with a project Secret Key. Use the Apple Ads MCP tools to pause or enable campaigns, ad groups, and keywords, update bids, or change daily budgets.

​
Errors and rate limits

Read endpoints use the standard v4 error envelope. 400 identifies invalid parameters and 401 invalid credentials; 404 is also returned to accounts without Apple Ads enabled. A report with a non-empty partial_sources is still a successful response, so check the fields above as well as the HTTP status. The report and series endpoints are rate limited. A 429 response includes Retry-After; wait that long before retrying.