---
title: "Estimate notification recipients"
method: POST
path: "/notifications/count-unsaved"
---

# Estimate notification recipients

`POST /notifications/count-unsaved`

## Request

- Base URL: `https://api.onesignal.com`
- URL: `https://api.onesignal.com/notifications/count-unsaved`
- Auth: none required

Returns the estimated number of recipients for a notification's targeting, without creating or sending anything.

## Headers

- `Authorization` string, required

## Request body

- object
  - `app_id` string, required: The OneSignal App ID for your app. See [Keys & IDs](/docs/en/keys-and-ids).
  - `included_segments` string[], required: Required. Segment names that define the base audience to count. Combine with `excluded_segments`, `filters`, `include_aliases`, and `target_channel` to narrow the estimate. Example: `["Active Users", "Inactive Users"]`. `"All"` is a shorthand for every subscribed user: if the array includes `"All"` and the app has no segment named All, the count includes all subscribers instead of looking up a segment named All.
  - `excluded_segments` string[]: Segment names to exclude from the count. Users in these segments are omitted even if they appear in `included_segments`. Example: `["Active Users", "Inactive Users"]`.
  - `filters` object[], nullable: Filter expressions that further narrow the audience to count. Each element is either a filter condition or an `AND`/`OR` operator.
  - `include_aliases` object, nullable: Narrow the count to users identified by aliases (`external_id`, `onesignal_id`, or a custom alias). Keys are alias labels and values are arrays of alias IDs. Example: `{ "external_id": ["extId1", "extId2"] }`. Limit of 2,000 entries per REST API call.
  - `target_channel` 'push' | 'email' | 'sms': Which platforms to count recipients for. Selects the same default platforms Create notification would use for the channel. Individual platform flags (`isIos`, `isAndroid`, etc.) are not supported by this endpoint.

## Response `200`

Estimated recipient counts for the supplied targeting. No notification is created or sent.

- object
  - `count` integer: The estimated audience size after applying the request's targeting and platform selection.
  - `uncapped_count` integer, nullable: The estimated audience size before the plan's web push subscriber cap is applied. Present only when `cap_applied` is `true`; `null` otherwise.
  - `cap_applied` boolean: Whether `count` was reduced because the app is on a plan that caps the number of web push subscribers it can send to.
  - `mobile_suppressed` boolean: The mobile equivalent of `cap_applied`. `true` when mobile push recipients would be dropped because the org is over its plan's mobile push subscriber cap. `false` when the targeting does not include any mobile push platforms.
  - `mobile_excluded_count` integer: How many mobile push recipients the `count` excludes due to the plan's mobile push subscriber cap. `0` when `mobile_suppressed` is `false`.

## Other responses

- `400`: Bad request. The payload was rejected. Common causes include a missing `app_id` or `included_segments`.
- `429`: Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.

## Changes

- **2026-11-03** `36dfd39b1be3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/onesignal/apis/api-onesignal-com/changes/notifications/count-unsaved/post.md)

---

[API](https://skmtc.dev/onesignal/apis/api-onesignal-com.md) - [All operations](https://skmtc.dev/onesignal/apis/api-onesignal-com/llms.txt) - [OpenAPI document](https://skmtc.dev/onesignal/apis/api-onesignal-com/revisions/36dfd39b1be3?raw)