Skip to main content
GET
/
apps
/
{app_id}
/
segments
/
{segment_id}
View segment
curl --request GET \
  --url https://api.onesignal.com/apps/{app_id}/segments/{segment_id} \
  --header 'Authorization: <authorization>'
{
  "subscriber_count": 12345
}

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.

​
Overview

Retrieve details for a single segment by its ID. By default, this endpoint returns only the subscriber count. Use the optional include-segment-detail parameter to also retrieve segment metadata and filters.
The segment_id can be found using the View segments API or in the URL of the segment when viewing it in the dashboard.
User-based segments not supported: Segments containing message event or custom event filters (user-based segments) are not yet supported via this API. Attempting to fetch these segments will return a 400 error. These segments can only be managed through the dashboard UI.

​
How to use this API

​
Basic usage

By default, this endpoint returns only the subscriber count for the segment: 
{
  "subscriber_count": 12345
}

​
Include segment details

To retrieve full segment details including metadata and filters, set include-segment-detail=true: 
GET /apps/{app_id}/segments/{segment_id}?include-segment-detail=true
This returns the subscriber count along with a payload object containing segment details: 
{
  "subscriber_count": 12345,
  "payload": {
    "id": "4414c404-56a3-11ed-9b6a-0242ac120002",
    "name": "Subscribed Users",
    "description": "YOUR_SEGMENT_DESCRIPTION",
    "created_at": 1658584650,
    "source": "custom",
    "filters": [
      {
        "field": "session_count",
        "relation": ">",
        "value": "5"
      }
    ]
  }
}

​
Filters format

The filters array uses the same format as the Create segment API. This means you can: The array contains filter objects and operator objects: Filter object - defines a condition:
FieldTypeDescription
fieldstringThe filter type: tag, last_session, first_session, session_count, session_time, language, app_version, location, country, email
relationstringThe comparison operator: >, <, =, !=, exists, not_exists, time_elapsed_gt, time_elapsed_lt
valuestringThe filter value (for most filter types)
keystringThe filter key (required for tag filters)
hours_agostringHours ago value (for last_session/first_session filters)
radius, lat, longstringLocation parameters (for location filters)
unsupported_in_apibooleanIf true, this filter cannot be used with Create/Update segment APIs (see note below)
Operator object - combines filters:
FieldTypeDescription
operatorstringEither AND or OR. Filters connected with AND have higher priority than OR.
Some segments created via the dashboard UI may contain filter types not supported by the public API (e.g., message_event, custom_event). These filters will include unsupported_in_api: true. You cannot use these filters when creating or updating segments via the API.

​
Payload fields

FieldTypeDescription
idstringThe unique identifier for the segment (UUID v4).
namestringThe segment name (max 128 characters).
descriptionstring | nullHuman-readable description for the segment (max 255 characters). null when unset.
created_atintegerUnix timestamp when the segment was created.
sourcestringThe source of the segment: default, custom, or quickstart.
filtersarrayArray of filter and operator objects that define the segment criteria.

Headers

​
Authorization
string
default:Key YOUR_APP_API_KEY
required

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

Path Parameters

​
app_id
string
default:YOUR_APP_ID
required

Your OneSignal App ID in UUID v4 format. See Keys & IDs.

​
segment_id
string
default:YOUR_SEGMENT_ID
required

The segment's unique identifier. Can be found using the View segments API or in the dashboard URL.

Query Parameters

​
include-segment-detail
boolean
default:false

Set to true to include segment metadata and filters in the response.

Response

200

​
subscriber_count
integer

The number of subscribers matching this segment.

​
payload
object

Segment details. Only included when include-segment-detail=true.