> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.qonversion.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Apple Ads

> Read Apple Ads reports, daily series, and connection status through REST API v4.

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](/reference/v4/authentication) as a Bearer token. Available to accounts with Apple Ads enabled; other accounts receive `404`. Contact support to enable Apple Ads.

| Method | Endpoint | Returns |
| - | - | - |
| GET | `/analytics/apple-ads/report` | Performance by campaign, ad group, or keyword |
| GET | `/analytics/apple-ads/report/series` | One metric per UTC day |
| GET | `/integrations/apple-ads/connection` | Connection status for reporting and campaign management |

All paths are relative to `https://api.qonversion.io/v4`. Through [MCP](/docs/mcp-apple-ads), 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.

```bash theme={null}
curl --get 'https://api.qonversion.io/v4/analytics/apple-ads/report' \
  --header 'Authorization: Bearer sk_YOUR_SECRET_KEY' \
  --data-urlencode 'from=1788220800' \
  --data-urlencode 'to=1789426799' \
  --data-urlencode 'level=campaigns' \
  --data-urlencode 'windows=d7,d30' \
  --data-urlencode 'windows_mode=mature' \
  --data-urlencode 'filter[country][]=US'
```

`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](/docs/mcp-apple-ads) 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`.

```bash theme={null}
curl --get 'https://api.qonversion.io/v4/analytics/apple-ads/report/series' \
  --header 'Authorization: Bearer sk_YOUR_SECRET_KEY' \
  --data-urlencode 'from=1788220800' \
  --data-urlencode 'to=1789426799' \
  --data-urlencode 'metric=revenue'
```

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](/docs/mcp-apple-ads#changing-campaigns) 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](/reference/v4/handling-api-errors). `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.