Skip to main content
GET
View segment

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:

Include segment details

To retrieve full segment details including metadata and filters, set include-segment-detail=true:
This returns the subscriber count along with a payload object containing segment details:

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: Operator object - combines filters:
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


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.