# In-app statistics

Two methods return statistics for [instant in-app campaigns](/product/messaging-channels/in-apps/send-in-apps/send-instant-in-apps/). Use `inapps:totals` for period totals across one or more campaigns, and `inapps:timeline` for a time series of a single campaign. The values match the [in-app statistics screen](/product/statistics-and-analytics/messaging-statistics/in-app-statistics/) in the Control Panel.

<Aside type="note" title="In-apps sent from a Journey">
These methods cover instant in-app campaigns only. In-apps delivered by a Customer Journey element are reported per journey point by [Get Journey stats](/developer/api-reference/customer-journey-api/statistics/).
</Aside>

## Metrics

| Field <div style="width:170px"></div> | Type | Description |
| --- | --- | --- |
| `impressions` | number | How many times the in-app was displayed. Labeled **Impressions** in the Control Panel. |
| `unique_impressions` | number | Number of unique devices the in-app was displayed to. |
| `interactions` | number | Interactions with the in-app content: button clicks, link clicks and form submits. |
| `unique_interactions` | number | Number of unique devices that interacted with the in-app. |
| `skips` | number | How many times users dismissed the in-app without interacting. |
| `audience` | number | Number of unique devices that produced any in-app event in the period. |

<Aside type="note">
Unique metrics and `audience` are approximate because they use a probabilistic distinct count. Platform figures do not sum to the campaign total: a device that appears on two platforms is counted once in each platform breakdown and once in the campaign total.
</Aside>

## inapps:totals

Returns totals for the period. Pass `inapp_codes` to report on specific campaigns, or omit it to walk every in-app of the application page by page. That is the method to use for a scheduled export.

`POST` `https://api.pushwoosh.com/api/v2/statistics/inapps:totals`

##### Headers

| Name <div style="width:200px"></div> | Required <div style="width:100px"></div> | Description |
| --- | --- | --- |
| `Authorization` | Yes | [Server API token](/developer/api-reference/api-access-token/#server-api-token) in the format `Authorization: Api <Server Key>`. |

##### Request body parameters

| Name <div style="width:150px"></div> | Required | Type | Description |
| --- | --- | --- | --- |
| `application` | Yes | String | [Application code](/developer/api-reference/api-identifiers/#application-code). |
| `date_range` | Yes | Object | Reporting period. `date_from` and `date_to` use the `YYYY-MM-DD` format and are inclusive. The period is counted in UTC and must not exceed 366 days. |
| `inapp_codes` | No | Array | [In-app codes](/developer/api-reference/api-identifiers/#in-app-code), up to 100 per request. Omit to report on all in-apps of the application. If any code in the list does not belong to the application, the whole request fails with `404`. |
| `platforms` | No | Array | Restrict the metrics to these platforms. Possible values: `"IOS"`, `"ANDROID"`, `"HUAWEI_ANDROID"`, `"AMAZON"`, `"OSX"`, `"WINDOWS"`, `"SAFARI"`, `"CHROME"`, `"FIREFOX"`, `"WEB"`. |
| `with_platforms` | No | Boolean | Add a per-platform breakdown to every item. |
| `page` | No | Integer | Page number, starting at `0`. Applies when `inapp_codes` is omitted. |
| `per_page` | No | Integer | Items per page, `20` by default, `100` at most. |

##### Example request

```bash
curl -X POST https://api.pushwoosh.com/api/v2/statistics/inapps:totals \
  -H "Authorization: Api YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "application": "XXXXX-XXXXX",
    "date_range": {
      "date_from": "2026-07-01",
      "date_to": "2026-07-31"
    },
    "inapp_codes": ["AAAAA-BBBBB"],
    "with_platforms": true
  }'
```

##### Response fields

`total` is the number of in-apps the request matches. When `inapp_codes` is omitted, that is all in-apps of the application, so pagination can walk it. `items` holds the current page. `page` counts from `0`.

##### Example response

```json
{
  "total": 1,
  "page": 0,
  "per_page": 20,
  "items": [{
    "inapp": {
      "code": "AAAAA-BBBBB",
      "name": "Summer sale",
      "status": "active",
      "rich_media_code": "CCCCC-DDDDD"
    },
    "metrics": {
      "impressions": 15230,
      "unique_impressions": 9120,
      "interactions": 2311,
      "unique_interactions": 1980,
      "skips": 640,
      "audience": 9120
    },
    "platforms": [{
      "platform": "IOS",
      "metrics": {
        "impressions": 8100,
        "unique_impressions": 4900,
        "interactions": 1300,
        "unique_interactions": 1120,
        "skips": 310,
        "audience": 4900
      }
    }],
    "frequency_capping": {
      "suppressions": 45,
      "affected_users": 30,
      "data_available_from": "2026-07-17"
    }
  }]
}
```

## inapps:timeline

Returns period totals and a time series for one in-app campaign.

`POST` `https://api.pushwoosh.com/api/v2/statistics/inapps:timeline`

##### Request body parameters

| Name <div style="width:150px"></div> | Required | Type | Description |
| --- | --- | --- | --- |
| `application` | Yes | String | [Application code](/developer/api-reference/api-identifiers/#application-code). |
| `inapp_code` | Yes | String | [In-app code](/developer/api-reference/api-identifiers/#in-app-code). |
| `date_range` | Yes | Object | Reporting period. `date_from` and `date_to` use the `YYYY-MM-DD` format and are inclusive. The period is counted in UTC and must not exceed 366 days. Optional `interval`: `"HOUR"`, `"DAY"` (default), `"WEEK"` or `"MONTH"`. `"HOUR"` is available for periods up to 31 days. |
| `platforms` | No | Array | Restrict the metrics to these platforms. |
| `with_platforms` | No | Boolean | Add a per-platform breakdown to the totals and to every row. |

##### Example request

```bash
curl -X POST https://api.pushwoosh.com/api/v2/statistics/inapps:timeline \
  -H "Authorization: Api YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "application": "XXXXX-XXXXX",
    "inapp_code": "AAAAA-BBBBB",
    "date_range": {
      "date_from": "2026-07-01",
      "date_to": "2026-07-07",
      "interval": "DAY"
    }
  }'
```

##### Example response

```json
{
  "inapp": {
    "code": "AAAAA-BBBBB",
    "name": "Summer sale",
    "status": "active",
    "rich_media_code": "CCCCC-DDDDD"
  },
  "totals": {
    "impressions": 15230,
    "unique_impressions": 9120,
    "interactions": 2311,
    "unique_interactions": 1980,
    "skips": 640,
    "audience": 9120
  },
  "frequency_capping": {
    "suppressions": 45,
    "affected_users": 30,
    "data_available_from": "2026-07-17"
  },
  "rows": [{
    "timestamp": "2026-07-01T00:00:00Z",
    "metrics": {
      "impressions": 2140,
      "unique_impressions": 1700,
      "interactions": 320,
      "unique_interactions": 290,
      "skips": 95,
      "audience": 1700
    }
  }],
  "impression_duration": [
    { "from_seconds": 0, "to_seconds": 5, "count": 3200 },
    { "from_seconds": 5, "to_seconds": 15, "count": 5400 },
    { "from_seconds": 15, "to_seconds": 30, "count": 4100 },
    { "from_seconds": 30, "to_seconds": 0, "count": 2530 }
  ]
}
```

`impression_duration` buckets how long the in-app stayed on screen. In the last bucket `to_seconds` is `0`, which means "30 seconds and longer".

## Frequency capping

The `frequency_capping` block reports in-app displays that [frequency capping](/product/messaging-channels/global-frequency-capping/) prevented, and the number of unique users affected. Suppressions are not counted in `impressions`.

<Aside type="caution" title="Suppression data starts on 17 July 2026">
Suppressions were not recorded before that date. For a period that ends earlier, the `frequency_capping` block comes back as `null` instead of zeros, so a lack of data is never mistaken for capping that suppressed nothing. `data_available_from` in the response states the first covered day. Frequency capping has no per-platform breakdown.
</Aside>

## Data retention

Statistics are kept for 365 days, so a period that starts earlier returns no data for the uncovered days.

## Response codes

| Code | Meaning |
| --- | --- |
| 200 | Success. |
| 400 | Invalid request: a missing or malformed `date_range`, a period longer than 366 days, an hourly interval over more than 31 days, or more than 100 `inapp_codes`. |
| 401 | Missing or invalid API token. |
| 404 | An in-app code was not found in this application. |