> ## 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 in REST API v4

> REST API v4 has four Apple Ads endpoints: the report, the daily series and the connection status, read with the project Secret Key, and a campaign-change endpoint that works only with Qonversion MCP authorization — a plain Secret Key gets 403 control_forbidden. Parameters, limits, errors and rate limits.

This page documents the Apple Ads endpoints of the Qonversion REST API v4. Three read endpoints — the Apple Ads report, the daily series and the connection status — are called with your project [Secret Key](https://documentation.qonversion.io/reference/v4/authentication.md). Campaign changes cannot be made over the plain REST API with a project Secret Key: `POST /v4/analytics/apple-ads/entity/update` without Qonversion MCP authorization returns 403 `control_forbidden`. Programmatically, campaign changes are available only through the Qonversion MCP server; people can also make them in the dashboard.

> [!NOTE]
>
> For accounts without access to the Apple Ads report, the Apple Ads REST read endpoints and the connection endpoint return 404 `not_found`, indistinguishable from a nonexistent endpoint. The Apple Ads report is available on all accounts; if yours gets this 404, contact support. For such accounts the change endpoint `POST /v4/analytics/apple-ads/entity/update` also answers HTTP 404 — as it does for accounts that have the Apple Ads report without campaign management — after its authorization check: a request without Qonversion MCP authorization gets 403 `control_forbidden` first. On accounts with the report only, the report and series endpoints also answer 404 for a project without per-app scope.

## Which Apple Ads endpoints does REST API v4 have?

The public REST API v4 has four Apple Ads endpoints:

| Method | Path | Returns | `object` | Authorization |
| - | - | - | - | - |
| GET | `/v4/analytics/apple-ads/report` | Apple Ads report table by campaign, ad group or keyword | `analytics_apple_ads_report` | Project Secret Key |
| GET | `/v4/analytics/apple-ads/report/series` | Daily series of up to 4 metrics | `analytics_apple_ads_series` | Project Secret Key |
| GET | `/v4/integrations/apple-ads/connection` | Apple Ads connection and permission status | `apple_ads_connection` | Project Secret Key |
| POST | `/v4/analytics/apple-ads/entity/update` | Result of one campaign change | — | Qonversion MCP authorization required |

REST responses carry an `object` type and a canonical `url`: `analytics_apple_ads_report` (`/v4/analytics/apple-ads/report`), `analytics_apple_ads_series` (`/v4/analytics/apple-ads/report/series`) and `apple_ads_connection` (`/v4/integrations/apple-ads/connection`).

## How do I authenticate Apple Ads requests?

| Operation | REST API v4 | Qonversion MCP server |
| - | - | - |
| Report, series, connection status | Project Secret Key | OAuth scope `analytics:read` (there is no separate `apple_ads:read` scope) |
| Campaign changes (status, keyword bid, campaign daily budget) | Not available with a Secret Key alone: 403 `control_forbidden` | OAuth scope `apple_ads:write` plus an acting dashboard user who holds **Manage Apple Ads campaigns** |

`POST /v4/analytics/apple-ads/entity/update` without Qonversion MCP authorization (an acting dashboard user plus the `apple_ads:write` scope) returns 403 `control_forbidden`. Even with MCP authorization, every change is re-checked at request time: the request must name a dashboard user, carry `apple_ads:write`, and that user must still hold the **Manage Apple Ads campaigns** permission in the account; otherwise it is refused with 403. By default only the Owner and Administrator roles hold that permission; other members need it granted individually. The Apple Ads role of the campaign's organization must also allow changes; see [How do campaign changes work on the change endpoint?](#how-do-campaign-changes-work-on-the-change-endpoint).

## How do I request the Apple Ads report?

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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=keywords' \
  --data-urlencode 'windows=d7,d30' \
  --data-urlencode 'windows_mode=mature' \
  --data-urlencode 'filter[status]=active'
```

`GET /v4/analytics/apple-ads/report` accepts `level`, `from`, `to`, `environment`, `sort`, `sort_dir`, `q`, `min_spend`, `min_spend_scope`, `limit`, `offset`, `export`, `windows`, `maturation_buffer_days`, `windows_mode`, `revenue_type`, `currency`, `filter[...]` / `filter_not[...]` and `metric_filters[...]`.

| Parameter | Values | Default |
| - | - | - |
| `from`, `to` | Unix seconds (UTC); they bound the cohort's install dates | Required |
| `level` | `campaigns`, `groups` or `keywords` | `campaigns` |
| `environment` | `1` (production) or `0` (sandbox) | `1` |
| `sort` | Metric to sort by. `window_roas_<code>` or `window_cac_<code>` is allowed only when the same window code is in `windows`; otherwise the request is an error. | `spend` |
| `sort_dir` | Sort direction | Descending |
| `q` | Case-insensitive substring search over the entity name or id, at most 64 characters | None |
| `min_spend` | Number, 0 or more. Keeps only rows whose Apple spend is at least this amount, in the report's `currency` (USD by default). At the row's own level, rows without Apple spend data never match. | None |
| `min_spend_scope` | `campaigns`, `groups` or `keywords`, not finer than `level`. A coarser level compares the spend summed over the report's rows that share the row's campaign or ad group. No effect without `min_spend`. | The request `level` |
| `limit` | 1–500; up to 5000 with `export=true` | `100` |
| `offset` | ≥ 0 (offset-based pagination) | `0` |
| `export` | `true` (or `1`) lifts the page-size ceiling to 5000 rows for a single-request pull; the response is still JSON, not CSV | Not set |
| `windows` | Cohort windows, any of `d0`, `d3`, `d7`, `d14`, `d30`, `d60`, `d90`, `d180`, `d365`, `lifetime`. REST window codes are case-sensitive lowercase. | None (windows are opt-in) |
| `windows_mode` | `growing` or `mature`: which reading of the requested windows is served. Accepted without `windows`, but has no effect. | Chosen by the server |
| `maturation_buffer_days` | Whole number 0–30; affects only requested windows. Accepted without `windows`, but has no effect. | `4` |
| `revenue_type` | `gross` or `net` | `gross` |
| `currency` | Currency code for money values in the report | `USD` |
| `filter[status]` | `active`, `paused` or `archived` — a single value | None |
| `filter[delivery]` | `delivering` or `not_delivering` — a single value | None |
| `filter[...]` / `filter_not[...]` | Include or exclude cohort values. `filter_not` is refused for `country`, `campaign_name` and `ad_set_name`. | None |
| `metric_filters[<metric>][gte\|lte]` | Numeric row thresholds; see [How do I filter report rows by metric values?](#how-do-i-filter-report-rows-by-metric-values) | None |

* **Spend threshold.** `min_spend` keeps only rows whose Apple spend is at least that amount, in the report's currency (the `currency` parameter, USD by default). `min_spend_scope` chooses what is compared: the row's own spend (the default, the request `level`), or, for a coarser level, the spend summed over the report's rows that share the row's campaign or ad group; a scope finer than `level` is refused. Hidden rows without spend data are counted in `pagination.rows_without_spend_hidden`; `total` and `unallocated` are not affected. `min_spend_scope` has no effect without `min_spend`.

- **Single-value state filters.** `filter[status]` and `filter[delivery]` are single-value report-level filters; passing more than one value is an error. There is no `state` parameter over REST (the MCP report tool has one); use `filter[status]` or `filter[delivery]`.
- **Exclusions.** `filter_not` (exclusion) is refused for `country`, `campaign_name` and `ad_set_name`, because Apple's spend cannot be excluded the same way and ROAS/CAC would be wrong; `status` and `delivery` have no exclusion form either. Use `filter[...]` to narrow by those instead.
- **Media source.** A `media_source_name` filter narrows only the Qonversion users side of the Apple Ads report; Apple spend is not split by media source.
- **Windows.** `windows_mode` and `maturation_buffer_days` sent without `windows` are accepted and have no effect. The default `windows_mode` is chosen by the server and may change, so send `windows_mode` explicitly when it matters; `meta.windows.mode` states the reading actually served.
- **Unknown parameters.** An unknown or unsupported query parameter is refused with 400 `invalid_request` and `error.details[].reason` `unsupported_parameter`, instead of being silently ignored.

### How do I filter report rows by metric values?

The REST report accepts `metric_filters[<metric>][gte|lte]=<number>` on the sort metric vocabulary. `window_roas_<code>` and `window_cac_<code>` are allowed only when that window is requested in `windows`. At most 12 distinct metrics are accepted per request. The MCP report tool does not expose `metric_filters`.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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 'windows=d7' \
  --data-urlencode 'metric_filters[spend][gte]=10' \
  --data-urlencode 'metric_filters[window_roas_d7][gte]=1'
```

### What is in the report response?

A report response has `level`, `currency`, `revenue_type`, `status_data_available`, `rows`, `total`, `unallocated`, `pagination`, `partial_sources` and `meta`. Check these markers before quoting numbers:

| Marker | What it means |
| - | - |
| `partial_sources` is non-empty | Some Apple data is missing; affected rows have `apple: null` |
| `meta.partial_scope` | `{campaigns_total, campaigns_missing}` counts campaigns without spend data |
| `meta.is_partial_period` is `true` | The period includes today |
| `meta.status_data_unavailable` is `true` | A status/delivery filter was requested but no entity state was available |
| `meta.request` | Echoes `from`, `to`, `environment`, `level`, `limit`, `offset`, `filters_applied` and `filters_excluded` after normalization; `filters_applied` lists only filters that were recognized and applied |
| `meta.windows.mode` | The cohort-window reading actually served |

Values for campaign changes in the report rows:

* **Status.** In the report, each entity's status is an object `{state, serving, display, reasons}`; the value to pass as `before_status` is `status.state` (`ENABLED`/`ACTIVE`/`PAUSED`).
* **Keywords.** On the keywords level each row's keyword block carries `id`, `name` (the keyword text), `status`, `match_type`, `bid` and `delivery`.
* **Daily budget.** On the campaigns level the campaign block carries `daily_budget` as `{amount, currency}` or `null`, in the advertising account's currency.
* **Bid.** `bid` is reported as `{amount, currency}` only on the `ad_group` block of groups-level rows and the `keyword` block of keywords-level rows. It is in the advertising account's own currency, never converted, and `amount` is a decimal string. It is not a live read and may not yet reflect a change you just made. `null` means the bid is not available in this response, not a zero bid.

## How do I request a daily Apple Ads series?

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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 'metrics=spend,roas,window_roas_d7'
```

`GET /v4/analytics/apple-ads/report/series` accepts `metric` (one) or `metrics` (1–4 distinct, comma-separated) from this list:

| Group | Metric names |
| - | - |
| Apple delivery and cost | `spend`, `installs`, `impressions`, `taps`, `ttr`, `cpa`, `cpt`, `cpm` |
| Qonversion cohort | `users`, `trials`, `trials_converted`, `paying`, `revenue`, `arpu`, `arppu`, `roas`, `cost_per_trial`, `cost_per_subscription`, `cac` |
| Cohort windows | `window_roas_<code>` and `window_cac_<code>` for `d0`–`d365` |

* `from` and `to` (Unix seconds, UTC) are required. `environment` defaults to `1` (production) when omitted; `0` selects sandbox.
* **Daily only.** The public series is daily only: a `unit` parameter is not accepted (400 `unsupported_parameter`), while the dashboard chart can also group by week or month.
* **At most 366 points.** A series returns at most 366 daily points; for longer periods the oldest days are dropped and `truncated` is `true`.
* **Ignored filters.** On the series, `filter[status]` and `filter[delivery]` (and any filter the metric's source cannot honour) are accepted but not applied, and are listed in `filters_ignored`.
* The MCP tool `get_apple_ads_series` plots one metric per call from a narrower list of 12 metrics.

## How do I check the Apple Ads connection?

`GET /v4/integrations/apple-ads/connection` takes no parameters and returns `state`, `connection_method`, `granted_at`, `last_verified_at`, `reporting`, `campaign_management`, `orgs[]`, `next_action` and `dashboard_url`.

| Field | Values and meaning |
| - | - |
| `state` | `not_connected`, `legacy_credentials`, `verifying`, `connected` or `needs_reauthorization`. It describes the authorization only, not permission to change campaigns: a connected integration can still be reporting-only. |
| `connection_method` | `customer_key`, `service_provider_oauth` or `null` |
| `granted_at`, `last_verified_at`, `campaign_management.checked_at` | RFC 3339 UTC strings (`null` when unknown) |
| `reporting` | `{state, reason_code}`: `connected` → `ready`; `legacy_credentials` → `ready` with reason `legacy_credentials` (working, migration recommended); `verifying` → `verifying` (`acl_not_confirmed`); `needs_reauthorization` → `not_ready` (`authorization_revoked`); `not_connected` → `not_ready` (`not_connected`). On an account with the report only, a project without per-app scope that already has a connection or spend gets `not_ready` (`app_scope_not_ready`) whatever the `state` |
| `campaign_management` | `{state, reason_code, can_write, checked_at, is_stale}`: `ready` (`can_write` `true`) when at least one organization's Apple role allows changes; `read_only` with `no_writable_org` (`can_write` `false`); `unknown` with `permissions_not_checked_yet` or `permission_data_stale` (`can_write` `null` — not a refusal, try later); `not_ready` with `not_connected` or `authorization_revoked` (`can_write` `false`); `not_ready` with `campaign_management_not_enabled` (`can_write` `false`) when campaign management is not enabled for the account — changes answer 404 whatever `orgs[].can_write` says (a missing or revoked connection keeps its own reason) |
| `orgs[]` | Each Apple Ads organization the connection reaches: `org_id` (string), `org_name`, `currency` (the currency bids and budgets must use), `can_write` and `role_names` (Apple's role names verbatim) |
| `next_action` | `connect_apple_ads` (not connected), `reconnect_apple_ads` (needs reauthorization), `wait_for_verification` (verifying), `migrate_to_apple_authorization` (legacy credentials), `grant_campaign_role_in_apple_ads` (connected, but no organization's Apple role allows changes — done in Apple Ads; not used on accounts with the report only), `wait_for_app_scope` (`app_scope_not_ready`: report data for the project is not available yet; reconnecting does not help — contact support) or `null` |
| `dashboard_url` | Always points to the dashboard's Apple Ads settings page (`/project-settings/asa`), where a person connects, reconnects or migrates |

The API and MCP never start or complete Apple sign-in. The connection status never returns credential material (private key, client secret, tokens, authorization code, OAuth state). Read `campaign_management.can_write` before attempting changes.

The dashboard shows an explicit disconnect as **Disconnected**. REST API v4 and MCP continue to report `needs_reauthorization` with reporting reason `authorization_revoked` for that state; use `dashboard_url` to connect again.

## How do campaign changes work on the change endpoint?

`POST /v4/analytics/apple-ads/entity/update` is the endpoint behind the Qonversion MCP change tools (`set_apple_ads_status`, `set_apple_ads_bid`, `set_apple_ads_daily_budget`). Without Qonversion MCP authorization it returns 403 `control_forbidden`; see [Apple Ads via MCP](https://documentation.qonversion.io/docs/mcp-apple-ads.md) for the tools and their confirmation rules.

**Request body.** The endpoint accepts no query parameters (400 `invalid_request`); every field, including `dry_run`, goes in the JSON body (max 64 KB). Accepted keys are `level`, `org_id`, `campaign_id`, `ad_group_id`, `keyword_id`, `keyword_text`, `keyword_match_type`, `idempotency_key`, `dry_run`, `status`, `before_status`, `bid`, `before_bid`, `daily_budget`, `before_daily_budget`. Unknown fields in a change request body (including unknown keys inside a money object) are refused with 400 `invalid_request` (reason `unsupported_parameter`), not 422, before anything is sent to Apple.

**Money fields.** On this endpoint, `bid` and `daily_budget` must be JSON objects `{"amount": "<decimal string>", "currency": "<three-letter code>"}`. A plain number or string in `bid` or `daily_budget` is not recognised as an action, and the request is refused with 422. `before_bid` and `before_daily_budget` are accepted either as the same `{amount, currency}` object or as a plain decimal string. The Qonversion MCP change tools send all four fields to this endpoint as `{amount, currency}` objects.

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "level": "keyword",
  "campaign_id": "123",
  "ad_group_id": "456",
  "keyword_id": "789",
  "keyword_text": "photo editor",
  "keyword_match_type": "EXACT",
  "bid": {"amount": "2.50", "currency": "EUR"},
  "before_bid": {"amount": "2.00", "currency": "EUR"},
  "idempotency_key": "bid-789-2026-10-16-1"
}
```

| Rule | Detail |
| - | - |
| One action per request | Each change request carries exactly one action — `status`, `bid` or `daily_budget` — with its matching `before_*` value |
| Levels | Status: `campaign`, `ad_group` or `keyword`. Bids can be changed only for keywords; ad-group bids cannot be changed through MCP or the API. Daily budgets can be changed only for campaigns. |
| Ids | Every change needs `campaign_id` (Apple ids as strings); `ad_group` and `keyword` levels also need `ad_group_id`; keyword changes also need `keyword_id`, `keyword_text` and `keyword_match_type`. Ids below the chosen level are ignored. Ids must be canonical positive 64-bit integers. |
| Organization | The organization is always derived from the campaign; an `org_id` that disagrees is refused with 422. A campaign that does not belong to the project's Apple Ads data returns 404 `campaign_not_found`. |
| Money | Amounts are positive decimal strings with at most 9 integer digits and 2 fraction digits (for example `"2.50"`); no sign, exponent or currency symbol, and zero is refused. The currency is the advertising account's (organization's) own currency, never the report's display currency; amounts are never converted, and a different currency is refused with 422. |
| `before_*` value | `before_status` / `before_bid` / `before_daily_budget` is mandatory. If it disagrees with a value Qonversion recently saw Apple confirm for that entity, the change is refused with 409 `value_changed` and the response states the current confirmed value; decide again from that value instead of resending the same request. |
| ×3 ceiling | A single bid or daily-budget change may not exceed 3× the last amount Qonversion saw Apple confirm for that entity (422; raise in steps). With no confirmed history, the ceiling is not applied, the change counts as an increase, and the success response includes `baseline_unverified: true`. |
| `idempotency_key` | Required on the REST change endpoint (in the body, or via the `Idempotency-Key` header); a request without it is refused with 422. Max 64 characters. An `Idempotency-Key` header is copied into `idempotency_key` when the body has none; a key in the body wins. |
| `dry_run` | `true` simulates the change: nothing is sent to Apple and the response includes `would_send`, the exact payload Apple would have received. Must be a JSON boolean. A dry run goes through the same checks as a real change and can be refused by them, but it is never counted toward the limits. |
| Apple role | A read-only Apple Ads role returns 403 `read_only_credential` (naming the role); an organization the connection cannot reach returns 403 `org_not_permitted`. |

**Retries.** Resending the same change with the same `idempotency_key` returns the original result with `replayed: true` instead of changing anything twice. Reusing a key for a different change returns 409 `idempotency_key_reuse`; a still-running attempt returns 409 `in_progress`.

**Success response.** A successful change returns 200 with `confirmed` (the value Apple confirmed, or `null`), `applied`, `dry_run` and `action_id` (identifier of the change — quote it to support), plus `baseline_unverified` and, for dry runs, `would_send` when applicable. Verify a change from this response, not by re-reading the report.

### What limits apply to campaign changes?

| Limit (per project) | Value | Code (HTTP 429) | `Retry-After` |
| - | - | - | - |
| Changes per rolling minute | 10 | `per_minute` | 60 |
| Changes per rolling hour | 60 | `per_hour` | 3600 |
| Enables per rolling 24 hours | 20 | `enables_per_day` | 86400 |
| Bid increases per rolling 24 hours | 20 | `bid_raises_per_day` | 86400 |
| Daily-budget increases per rolling 24 hours | 10 | `budget_raises_per_day` | 86400 |

Limits are counted per Qonversion project, not per user, and changes made in the dashboard and through the Qonversion MCP server count toward the same limits. Pauses and bid/budget decreases do not count toward the daily increase caps (they still count toward the per-minute and per-hour limits); a bid or budget change on an entity Qonversion has never changed before is always counted as an increase. Dry runs, validation refusals and changes Apple rejected do not count toward any campaign-change limit.

## How does the REST API differ from MCP and from the dashboard?

**REST API v4 compared with the Qonversion MCP server:**

| Topic | REST API v4 | MCP |
| - | - | - |
| Read authorization | Project Secret Key | OAuth scope `analytics:read` |
| Report metric filters | `metric_filters` supported | Not exposed |
| Report state shorthand | No `state` parameter; use `filter[status]` or `filter[delivery]` | `state` shorthand (`all`, `active`, `delivering`, `not_delivering`, `paused`, `archived`) |
| Window codes | Case-sensitive lowercase | Case-insensitive, list or comma-separated string |
| `windows_mode` / `maturation_buffer_days` without `windows` | Accepted, no effect | Refused by the tool |
| Series | Up to 4 metrics per call, including window metrics | One metric per call, 12 metrics, no impressions/ttr/cpa/cpt/cpm/cost\_per\_trial/cac or window metrics |
| Campaign changes | Only with MCP authorization, not with a Secret Key alone | Yes; enabling and every live bid or daily-budget change needs human confirmation |
| `idempotency_key` on changes | Required (422 without) | Optional; the tools generate a new key per attempt when none is given |
| Errors | HTTP status, `error.code`, details and `Retry-After` | Only the error message text; 5xx becomes a generic error |

**REST API v4 compared with the Qonversion dashboard:**

| Feature | REST API v4 | Dashboard |
| - | - | - |
| Daily chart grouping | Daily only | Daily, weekly or monthly |
| Export of the report table | `export=true` returns up to 5000 rows as JSON | CSV export |
| "Update now" (refresh the report) | Not available | Available |
| Importing historical spend from a console export (.xlsx/.csv) | Not available | Available |
| 7-day budget usage per campaign | Not available | Available |
| Connecting, reconnecting, disconnecting or migrating | Not available; `dashboard_url` points to the settings page | Available |
| Bulk bid change by percent | Not available | Available |
| Bids and daily budgets | In the advertising account's own currency, not converted | In the advertising account's own currency, not converted |

## What errors and rate limits do the Apple Ads endpoints return?

Every refusal from `POST /v4/analytics/apple-ads/entity/update` uses the V4 error envelope `{error: {type, code, message}}`. Specific 4xx codes such as `value_changed` and `per_minute` are preserved. Extra details can include `error.class`, `error.fields`, `error.apple` and `confirmed`. Validation uses `invalid_data`, Apple refusals use `apple_refused`, and an unclassified refusal without a specific code uses `upstream_refused` (including a malformed `error.class`).

| HTTP status | Code | Endpoint | Meaning and what to do |
| - | - | - | - |
| 400 | `invalid_request`, `error.details[].reason` `unsupported_parameter` | Report, series | Unknown or unsupported query parameter (for example `unit` on the series). Remove it. |
| 400 | `invalid_request` | Change | A query parameter was sent; put every field in the JSON body |
| 400 | `invalid_request`, reason `unsupported_parameter` | Change | Unknown body field, or unknown key inside a money object |
| 403 | `control_forbidden` | Change | No Qonversion MCP authorization (for example, a Secret Key alone). Use the Qonversion MCP server. |
| 403 | `read_only_credential` | Change | The organization's Apple Ads role cannot make changes; the role is named |
| 403 | `org_not_permitted` | Change | The connection cannot reach the campaign's organization |
| 403 | `control_forbidden` | Change | The dashboard user lacks **Manage Apple Ads campaigns**, or the request lacks `apple_ads:write` |
| 404 | `not_found` | Report, series, connection | The account has no access to the Apple Ads report; on an account with the report only, also report and series for a project without per-app scope |
| 404 | `not_found` | Change | The account has no access to the Apple Ads report, or has the Apple Ads report only (campaign management not enabled). Checked after authorization: without Qonversion MCP authorization the change endpoint answers 403 `control_forbidden` first. |
| 404 | `campaign_not_found` | Change | The campaign does not belong to the project's Apple Ads data |
| 409 | `value_changed` | Change | The `before_*` value is out of date; decide again from the current confirmed value in the response |
| 409 | `idempotency_key_reuse` | Change | The key was used for a different change |
| 409 | `in_progress` | Change | The same attempt is still running |
| 409 | `already_applied` | Change | The same change was already submitted and its result is not available; read the entity's current value before deciding again |
| 413 | `invalid_data` | Change | Body larger than 64 KB; the same V4Error JSON is returned with or without `Idempotency-Key` |
| 422 | `invalid_data` (`error.class` `validation`) | Change | The request cannot be executed; `error.fields` maps each field to what to change only when Qonversion's own validation produced it. A refusal from the later currency or payload check has no `error.fields`. Nothing reaches Apple. |
| 429 | — | Report, series | Rate limited; the response has `Retry-After` rather than a cached answer |
| 429 | `per_minute`, `per_hour`, `enables_per_day`, `bid_raises_per_day`, `budget_raises_per_day` | Change | A campaign-change limit; `Retry-After` is 60, 3600 or 86400 seconds |
| 502 | `storage_error` | Change | Outcome unknown: the change may or may not have reached Apple |
| 504 | `network_error` | Change | Outcome unknown: the change may or may not have reached Apple |
| 503 | `storage_error` (generic body) | Change | For example, Apple's confirmation of the connection's permissions is out of date; check the connection status |

**Server-side errors on the change endpoint.** Every server-side (5xx) response of the change endpoint is returned with its status but a generic body (code `storage_error`, or `network_error` on 504); the specific reason and `action_id` are not included. A 502 or 504 is never retried automatically. Do not resend it with a new `idempotency_key`: retry only with the same `idempotency_key`, which cannot apply the change twice, and check the entity's current value before making any new change. If changes are refused with 503 because Apple's confirmation of the connection's permissions is out of date, the connection status shows `campaign_management.state` `unknown` with `reason_code` `permission_data_stale`. For Apple authorization, an owner or administrator opens Apple Ads settings and presses **Check again**. For a legacy API key, Qonversion re-reads permissions about every 6 hours; if it persists, check the key's role in Apple Ads or contact support. Retry with the same `idempotency_key`.

## Related pages

* [Apple Ads via MCP](https://documentation.qonversion.io/docs/mcp-apple-ads.md) — the six Apple Ads MCP tools, the confirmation flow for campaign changes and how errors look through MCP.
* [Authentication](https://documentation.qonversion.io/reference/v4/authentication.md) — how to send the project Secret Key with REST API v4 requests.
* [Handling errors](https://documentation.qonversion.io/reference/v4/handling-api-errors.md) — the v4 error envelope and HTTP status codes.
* [Manage Apple Ads campaigns](https://documentation.qonversion.io/docs/apple-ads-manage-campaigns.md) — pausing, bids and daily budgets in the Qonversion dashboard, and who can make changes.
* [Apple Ads report](https://documentation.qonversion.io/docs/apple-ads-report.md) — the same report in the Qonversion dashboard, including CSV export and currency.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.