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

# ROAS

> Apple Search Ads spend next to the revenue the SDK attributed, by campaign or keyword, with D1, D7 and D30 revenue windows

The ROAS view puts Apple Search Ads spend next to the revenue that Appeeky Analytics attributed to the same campaigns and keywords. The SDK records the Apple Search Ads campaign id and keyword id of each install, so the join is exact: no name matching and no modeled attribution.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/analytics/apps/:appId/roas?range=30d&level=campaign
```

> [!NOTE]
>
> ROAS is only available for **Apple Search Ads** on **iOS apps**. Other ad networks are not attributed per install; see [SKAdNetwork](https://docs.appeeky.com/docs/analytics-skadnetwork.md) for their results.

***

## Prerequisites

1. Analytics turned on for an iOS app, with the SDK's native module (Apple Search Ads attribution needs it).
2. Apple Search Ads connected in Appeeky. See [Apple Search Ads Credentials](https://docs.appeeky.com/docs/apple-search-ads-credentials.md).
3. RevenueCat connected and `identify` called, so purchases reach the installs. See [Revenue](https://docs.appeeky.com/docs/analytics-revenue.md).

Without Apple Search Ads connected, the view still lists the campaigns or keywords the SDK attributed, with their installs and revenue, but no spend.

***

## How It Works

1. Appeeky takes the installs first seen in the selected period that came from Apple Search Ads, grouped by campaign id or keyword id.
2. For each group, it adds up the revenue those installs have made so far, and the revenue they made within 1, 7 and 30 days of install.
3. It reads Apple Search Ads spend and installs for the same dates and the same campaigns or keywords, limited to this app.
4. It joins both sides on the Apple id.

Campaigns or keywords that spent money but brought no SDK installs still show, so wasted spend is visible. Groups with SDK installs but no spend in the report also show, with zero spend. At campaign level this can include campaigns from other sources, such as a smart link campaign. The SDK side covers the top 50 groups by installs.

### Query parameters

| Parameter | Default | Description |
| - | - | - |
| `range` | `30d` | `today`, `7d` or `30d`, in the app's time zone |
| `level` | `campaign` | `campaign` or `keyword` |

***

## Columns

| Field | Description |
| - | - |
| `id` | Apple Search Ads campaign id or keyword id |
| `name` | Campaign or keyword name from Apple Search Ads (the id when there was no spend row) |
| `spend` | Apple Search Ads spend in the period, in the account currency |
| `currency` | Currency of `spend` |
| `adInstalls` | Installs Apple Search Ads reports |
| `sdkInstalls` | Installs the SDK attributed to this row |
| `payers` | SDK installs that made a purchase or converted a trial |
| `revenueUsd` | All revenue from these installs so far, in USD |
| `windows` | Revenue within 1, 7 and 30 days of install. See [Revenue windows](#revenue-windows). |
| `cpi` | `spend / sdkInstalls`, in the spend currency |
| `roas` | `revenueUsd / spend`. `1.0` means the revenue so far equals the spend. |

`totals` adds up spend, revenue, ad installs and SDK installs over all rows, with an overall `roas`.

`adInstalls` and `sdkInstalls` come from different systems and can differ. The SDK only counts an install once the app has been opened with the SDK and Apple has confirmed the attribution.

***

## Revenue Windows

Each row has three windows: D1, D7 and D30.

| Field | Description |
| - | - |
| `days` | `1`, `7` or `30` |
| `matureInstalls` | Installs old enough to have a complete window |
| `revenueUsd` | Revenue those mature installs made within that many days of install |
| `perInstall` | `revenueUsd / matureInstalls`, or `null` when no install is old enough yet |

A window only counts installs that are at least that many days old. For a 30-day range, D30 only includes installs from 30 or more days ago, so it can be empty for recent periods. Compare windows across rows, not with the `revenueUsd` total.

***

## Currency Rule

Revenue is always in USD. ROAS is only computed when the Apple Search Ads spend is in USD too.

* If the Apple Search Ads account reports spend in another currency, `currencyMismatch` is `true` and every `roas` value is `null`. Spend, CPI and revenue still show, each in its own currency.
* If campaigns report in more than one currency, `currency` is `MIXED` and ROAS is not computed.

Appeeky does not convert currencies.

***

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "level": "campaign",
    "range": "30d",
    "since": "2026-09-26T00:00:00.000Z",
    "until": "2026-10-25T14:02:11.000Z",
    "appleAds": { "connected": true },
    "currency": "USD",
    "currencyMismatch": false,
    "rows": [
      {
        "id": "542370539",
        "name": "US Exact",
        "spend": 412.5,
        "currency": "USD",
        "adInstalls": 230,
        "sdkInstalls": 214,
        "payers": 19,
        "revenueUsd": 538.2,
        "windows": [
          { "days": 1, "matureInstalls": 205, "revenueUsd": 310.4, "perInstall": 1.514 },
          { "days": 7, "matureInstalls": 151, "revenueUsd": 402.9, "perInstall": 2.668 },
          { "days": 30, "matureInstalls": 0, "revenueUsd": 0, "perInstall": null }
        ],
        "cpi": 1.93,
        "roas": 1.305
      }
    ],
    "totals": {
      "spend": 412.5,
      "revenueUsd": 538.2,
      "adInstalls": 230,
      "sdkInstalls": 214,
      "roas": 1.305
    }
  }
}
```

If Apple Search Ads is connected but the spend report fails, `appleAds.error` holds the message, the rows show SDK data only and `totals` is `null`.

***

## Related Docs

* [Apple Search Ads Profitability](https://docs.appeeky.com/docs/apple-search-ads-profitability.md)
* [Attribution](https://docs.appeeky.com/docs/analytics-attribution.md#apple-search-ads)
* [Metrics](https://docs.appeeky.com/docs/analytics-metrics.md#ltv)
* [Analytics API](https://docs.appeeky.com/docs/analytics-api.md)


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