Skip to main content
POST
cURL

Overview

The Estimated recipients API allows you to check recipient counts based on the message’s targeting settings, without creating or sending anything. The returned count reflects the same audience-size estimate you would see when composing a message in the OneSignal dashboard.

How to Use this API

This API is most commonly used for checking how large a draft message’s audience is going to be, before creating or sending it. When making a request to this API, use a targeting-specific subset of message fields. included_segments is required. excluded_segments, filters, include_aliases, and target_channel narrow that segment-based audience further when present. Use target_channel to select which platforms to count. Other notification targeting fields (include_subscription_ids and the other raw subscription id/token fields, and the individual isIos / isAndroid / etc. platform flags) are not read by this API. All non-targeting notification fields (content, delivery options, and so on) are accepted, but ignored.

Headers

Authorization
string
default:Key YOUR_APP_API_KEY
required

Your App API key with prefix Key. See Keys & IDs.

Body

application/json
app_id
string
required

The OneSignal App ID for your app. See Keys & IDs.

Example:

"YOUR_APP_ID"

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.

Example:
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"].

Example:
filters
object[] | null

Filter expressions that further narrow the audience to count. Each element is either a filter condition or an AND/OR operator.

include_aliases
object | null

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.

Example:
target_channel
enum<string>

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.

Available options:
push,
email,
sms
Example:

"push"

Response

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

count
integer

The estimated audience size after applying the request's targeting and platform selection.

uncapped_count
integer | null

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.