> ## Documentation Index > Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt > Use this file to discover all available pages before exploring further. # 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 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. *** ## OpenAPI ````yaml POST /notifications/count-unsaved openapi: 3.1.0 info: title: api.onesignal.com version: '11.6' servers: - url: https://api.onesignal.com security: - {} paths: /notifications/count-unsaved: post: summary: Estimate notification recipients description: >- Returns the estimated number of recipients for a notification's targeting, without creating or sending anything. operationId: count-unsaved parameters: - name: Authorization in: header description: >- Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids). required: true schema: type: string default: Key YOUR_APP_API_KEY requestBody: required: true content: application/json: schema: type: object required: - app_id - included_segments properties: app_id: type: string description: >- The OneSignal App ID for your app. See [Keys & IDs](/docs/en/keys-and-ids). example: YOUR_APP_ID included_segments: type: array description: >- 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. items: type: string example: - Active Users excluded_segments: type: array description: >- 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"]`. items: type: string example: - Inactive Users filters: type: array nullable: true description: >- Filter expressions that further narrow the audience to count. Each element is either a filter condition or an `AND`/`OR` operator. items: type: object include_aliases: type: object nullable: true description: >- 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. additionalProperties: type: array items: type: string example: external_id: - YOUR_USER_EXTERNAL_ID target_channel: type: string enum: - push - email - sms description: >- 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: push responses: '200': description: >- Estimated recipient counts for the supplied targeting. No notification is created or sent. content: application/json: schema: type: object properties: count: type: integer description: >- The estimated audience size after applying the request's targeting and platform selection. uncapped_count: type: integer nullable: true description: >- 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: type: boolean description: >- 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: type: boolean description: >- 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: type: integer description: >- How many mobile push recipients the `count` excludes due to the plan's mobile push subscriber cap. `0` when `mobile_suppressed` is `false`. example: count: 15420 uncapped_count: null cap_applied: false mobile_suppressed: false mobile_excluded_count: 0 '400': description: >- Bad request. The payload was rejected. Common causes include a missing `app_id` or `included_segments`. content: application/json: schema: $ref: '#/components/schemas/BasicErrorResponse' '429': description: >- Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying. headers: Retry-After: description: >- Number of seconds to wait before retrying the request. Always emitted on 429 responses. schema: type: integer minimum: 0 content: application/json: schema: $ref: '#/components/schemas/BasicErrorResponse' deprecated: false x-codeSamples: - lang: curl label: cURL source: >- curl -X POST --url 'https://api.onesignal.com/notifications/count-unsaved' \ --header 'content-type: application/json; charset=utf-8' \ --header 'authorization: Key YOUR_APP_API_KEY' \ --data '{ "app_id": "YOUR_APP_ID", "included_segments": ["Active Users"], "target_channel": "push" }' - lang: typescript label: Node.js source: >- const response = await fetch('https://api.onesignal.com/notifications/count-unsaved', { method: 'POST', headers: { 'Content-Type': 'application/json; charset=utf-8', Authorization: 'Key YOUR_APP_API_KEY', }, body: JSON.stringify({ app_id: 'YOUR_APP_ID', included_segments: ['Active Users'], target_channel: 'push', }), }); const data = await response.json(); console.log(data); - lang: python label: Python source: |- import json import urllib.request payload = { "app_id": "YOUR_APP_ID", "included_segments": ["Active Users"], "target_channel": "push", } request = urllib.request.Request( "https://api.onesignal.com/notifications/count-unsaved", data=json.dumps(payload).encode("utf-8"), headers={ "Content-Type": "application/json; charset=utf-8", "Authorization": "Key YOUR_APP_API_KEY", }, method="POST", ) with urllib.request.urlopen(request) as response: print(response.read().decode("utf-8")) components: schemas: BasicErrorResponse: type: object properties: errors: type: array items: type: string description: One or more human-readable error messages. success: type: boolean description: >- Present (and `false`) on some endpoints (notifications, templates, segments). Not emitted by every endpoint. reference: type: array items: type: string description: >- Documentation URL fragments related to the error. Only emitted by the API-key auth error helpers. ````