Estimated recipients
Returns the estimated number of recipients for a notification’s targeting, without creating or sending anything.
Overview
The Estimated recipients API allows you to check recipient counts based on the message’s targeting settings, without creating or sending anything. The returnedcount 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
Your App API key with prefix Key. See Keys & IDs.
Body
The OneSignal App ID for your app. See Keys & IDs.
"YOUR_APP_ID"
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.
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"].
Filter expressions that further narrow the audience to count. Each element is either a filter condition or an AND/OR operator.
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.
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.
push, email, sms "push"
Response
Estimated recipient counts for the supplied targeting. No notification is created or sent.
The estimated audience size after applying the request's targeting and platform selection.
The estimated audience size before the plan's web push subscriber cap is applied. Present only when cap_applied is true; null otherwise.
Whether count was reduced because the app is on a plan that caps the number of web push subscribers it can send to.
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.
How many mobile push recipients the count excludes due to the plan's mobile push subscriber cap. 0 when mobile_suppressed is false.