ONonesignal

Estimate notification recipients

Changed on

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

post/notifications/count-unsaved

Request

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

Headers

Authorizationstring required

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

Request body

app_idstring required

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

included_segmentsstring[] 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_segmentsstring[]

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

filtersobject[] nullable

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

include_aliasesobject 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.

Example request

{
  "app_id": "YOUR_APP_ID",
  "included_segments": [
    "Active Users"
  ],
  "excluded_segments": [
    "Inactive Users"
  ],
  "include_aliases": {
    "external_id": [
      "YOUR_USER_EXTERNAL_ID"
    ]
  },
  "target_channel": "push"
}

Response

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

countinteger

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

uncapped_countinteger 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_appliedboolean

Whether count was reduced because the app is on a plan that caps the number of web push subscribers it can send to.

mobile_suppressedboolean

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_countinteger

How many mobile push recipients the count excludes due to the plan's mobile push subscriber cap. 0 when mobile_suppressed is false.

Changes