> ## 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.
# View segment
> Retrieve details for a single segment by its ID, including subscriber count and optionally segment metadata and filters.
## 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.
To get a `segment_id`, go to **Audience > Segments** in the dashboard, open the segment's options menu, and select **Copy segment ID**. You can also get it from the [View segments](/reference/view-segments) API or the segment's URL in the dashboard.
**Event-based segments not supported**: Segments with message event or custom event filters (event-based segments) are not yet supported by this API. Fetching one returns a `400` error with the message `User-based segments (with message event or custom event filters) are not yet supported via the API`. Manage these segments in the dashboard.
***
## How to use this API
### Basic usage
By default, this endpoint returns only the subscriber count for the segment:
```json theme={null}
{
"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:
```json Simple filter theme={null}
{
"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"
}
]
}
}
```
```json With AND/OR operators theme={null}
{
"subscriber_count": 5678,
"payload": {
"id": "5525d515-67b4-22fe-0c7b-1353bd231113",
"name": "Engaged Users",
"description": "YOUR_SEGMENT_DESCRIPTION",
"created_at": 1658584650,
"source": "custom",
"filters": [
{"field": "session_count", "relation": ">", "value": "2"},
{"operator": "AND"},
{"field": "tag", "key": "level", "relation": "=", "value": "10"},
{"operator": "OR"},
{"field": "last_session", "relation": "<", "hours_ago": "24"}
]
}
}
```
### Filters format
The `filters` array uses the **same format** as the [Create segment](/reference/create-segments) API. This means you can:
* Read filters from this endpoint
* Modify them as needed
* Use them directly with the [Update segment](/reference/update-segment) or [Create segment](/reference/create-segments) APIs
The array contains filter objects and operator objects:
**Filter object** - defines a condition:
| Field | Type | Description |
| - | - | - |
| `field` | string | The filter type: `tag`, `last_session`, `first_session`, `session_count`, `session_time`, `language`, `app_version`, `location`, `country`, `email` |
| `relation` | string | The comparison operator: `>`, `<`, `=`, `!=`, `exists`, `not_exists`, `in_array`, `not_in_array`, `time_elapsed_gt`, `time_elapsed_lt` |
| `value` | string | The filter value (for most filter types) |
| `key` | string | The filter key (required for `tag` filters) |
| `hours_ago` | string | Hours ago value (for `last_session`/`first_session` filters) |
| `radius`, `lat`, `long` | string | Location parameters (for `location` filters) |
| `unsupported_in_api` | boolean | If `true`, this filter cannot be used with Create/Update segment APIs (see note below) |
**Operator object** - combines filters:
| Field | Type | Description |
| - | - | - |
| `operator` | string | Either `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
| Field | Type | Description |
| - | - | - |
| `id` | string | The unique identifier for the segment (UUID v4). |
| `name` | string | The segment name (max 128 characters). |
| `description` | string \| null | Human-readable description for the segment (max 255 characters). `null` when unset. |
| `created_at` | integer | Unix timestamp when the segment was created. |
| `source` | string | The source of the segment: `default`, `custom`, or `quickstart`. |
| `filters` | array | Array of filter and operator objects that define the segment criteria. |
***
## OpenAPI
````yaml GET /apps/{app_id}/segments/{segment_id}
openapi: 3.1.0
info:
title: api.onesignal.com
version: '11.6'
servers:
- url: https://api.onesignal.com
security:
- {}
paths:
/apps/{app_id}/segments/{segment_id}:
get:
summary: View segment
description: >-
Retrieve details for a single segment by its ID, including subscriber
count and optionally segment metadata and filters.
operationId: view-segment
parameters:
- name: app_id
in: path
description: >-
Your OneSignal App ID in UUID v4 format. See [Keys &
IDs](/docs/en/keys-and-ids).
schema:
type: string
default: YOUR_APP_ID
required: true
- name: segment_id
in: path
description: >-
The segment's unique identifier. In the dashboard, go to **Audience
> Segments**, open the segment's options menu, and select **Copy
segment ID**. You can also get it from the View segments API or the
segment's URL in the dashboard.
schema:
type: string
default: YOUR_SEGMENT_ID
required: true
- 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
- name: include-segment-detail
in: query
description: >-
Set to `true` to include segment metadata and filters in the
response.
required: false
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Basic:
value:
subscriber_count: 12345
With Details (simple):
value:
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'
With Details (AND/OR):
value:
subscriber_count: 5678
payload:
id: 5525d515-67b4-22fe-0c7b-1353bd231113
name: Engaged Users
description: YOUR_SEGMENT_DESCRIPTION
created_at: 1658584650
source: custom
filters:
- field: session_count
relation: '>'
value: '2'
- operator: AND
- field: tag
key: level
relation: '='
value: '10'
- operator: OR
- field: last_session
relation: <
hours_ago: '24'
schema:
type: object
properties:
subscriber_count:
type: integer
description: The number of subscribers matching this segment.
payload:
type: object
description: >-
Segment details. Only included when
`include-segment-detail=true`.
properties:
id:
type: string
description: The unique identifier for the segment (UUID v4).
name:
type: string
description: The segment name.
description:
type:
- string
- 'null'
description: >-
Human-readable description for the segment. `null`
when unset. Maximum 255 characters.
created_at:
type: integer
description: Unix timestamp when the segment was created.
source:
type: string
description: The source of the segment.
enum:
- default
- custom
- quickstart
filters:
type: array
description: >-
Array of filter and operator objects defining the
segment criteria. Uses the same format as the Create
segment API, so filters can be directly used to
recreate or update the segment.
items:
oneOf:
- type: object
description: A filter condition.
properties:
field:
type: string
description: The filter type.
relation:
type: string
description: The comparison operator.
enum:
- '>'
- <
- '='
- '!='
- exists
- not_exists
- in_array
- not_in_array
- time_elapsed_gt
- time_elapsed_lt
value:
type: string
description: The filter value.
key:
type: string
description: The filter key (used for tag filters).
hours_ago:
type: string
description: >-
Hours ago value (used for
last_session/first_session filters).
radius:
type: string
description: >-
Radius in meters (used for location
filters).
lat:
type: string
description: Latitude (used for location filters).
long:
type: string
description: Longitude (used for location filters).
unsupported_in_api:
type: boolean
description: >-
If true, this filter type cannot be used
with the Create/Update segment APIs. These
filters were created via the dashboard UI
using features not available in the public
API (e.g., message_event, custom_event
filters).
- type: object
description: A logical operator to combine filters.
properties:
operator:
type: string
description: The logical operator.
enum:
- AND
- OR
required:
- operator
'400':
description: '400'
content:
application/json:
examples:
Missing Authorization:
value:
errors:
- Please include a case-sensitive header of Authorization
User-based Segment:
value:
errors:
- >-
User-based segments (with message event or custom event
filters) are not yet supported via the API
schema:
$ref: '#/components/schemas/BasicErrorResponse'
'404':
description: '404'
content:
application/json:
examples:
Result:
value:
errors:
- segment not found
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'
example:
errors:
- API rate limit exceeded
'503':
description: >-
Service temporarily unavailable. Retry after a short backoff. The
body may be empty or non-JSON in some failure modes.
headers:
Retry-After:
description: >-
Number of seconds to wait before retrying the request. This
header is optional and may be absent when a proxy or load
balancer generates the 503.
schema:
type: integer
minimum: 0
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorResponse'
example:
errors:
- Service temporarily unavailable
deprecated: false
security: []
x-codeSamples:
- lang: typescript
label: Node.js SDK
source: >-
import Onesignal from '@onesignal/node-onesignal';
const configuration = Onesignal.createConfiguration({
restApiKey: 'YOUR_REST_API_KEY',
});
const apiInstance = new Onesignal.DefaultApi(configuration);
// string | The OneSignal App ID for your app. Available in Keys &
IDs.
const appId: string = "YOUR_APP_ID";
// string | The segment\'s unique identifier. Can be found using the
View Segments API or in the URL of the segment when viewing it in
the dashboard.
const segmentId: string = "d6c5a3e1-9f17-44a1-9d10-7c0e4a2b1c8e";
// boolean | Set to true to include segment metadata and filters in
the response. (optional)
const includeSegmentDetail: boolean = true;
try {
const response = await apiInstance.getSegment(appId, segmentId, includeSegmentDetail);
console.log(response);
} catch (e) {
if (e instanceof Onesignal.ApiException) {
// `e.errorMessages` flattens any error-envelope shape to a `string[]`;
// the raw parsed body remains on `e.body`.
console.error("getSegment failed: HTTP " + e.code, e.errorMessages);
} else {
throw e;
}
}
- lang: python
label: Python SDK
source: >-
import onesignal
from onesignal.api import default_api
from onesignal.models import *
from pprint import pprint
# See configuration.py for a list of all supported configuration
parameters.
# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token
for authorization, while others require REST_API_KEY.
# We recommend adding both of them in the configuration page so that
you will not need to figure it out yourself.
configuration = onesignal.Configuration(
rest_api_key = "YOUR_REST_API_KEY", # App REST API key required for most endpoints
organization_api_key = "YOUR_ORGANIZATION_API_KEY" # Organization key is only required for creating new apps and other top-level endpoints
)
# Enter a context with an instance of the API client
with onesignal.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = default_api.DefaultApi(api_client)
app_id = "YOUR_APP_ID" # The OneSignal App ID for your app. Available in Keys & IDs.
segment_id = "d6c5a3e1-9f17-44a1-9d10-7c0e4a2b1c8e" # The segment's unique identifier. Can be found using the View Segments API or in the URL of the segment when viewing it in the dashboard.
include_segment_detail = True # Set to true to include segment metadata and filters in the response. (optional)
try:
# View Segment
api_response = api_instance.get_segment(app_id, segment_id, include_segment_detail=include_segment_detail)
pprint(api_response)
except onesignal.ApiException as e:
print("Exception when calling DefaultApi->get_segment: %s\n" % e)
print("Status Code: %s" % e.status)
print("Response Body: %s" % e.body)
- lang: php
label: PHP SDK
source: >-
setRestApiKeyToken('YOUR_REST_API_KEY')
->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');
$apiInstance = new onesignal\client\Api\DefaultApi(
// If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
// This is optional, `GuzzleHttp\Client` will be used as default.
new GuzzleHttp\Client(),
$config
);
$app_id = 'YOUR_APP_ID'; // string | The OneSignal App ID for your
app. Available in Keys & IDs.
$segment_id = 'd6c5a3e1-9f17-44a1-9d10-7c0e4a2b1c8e'; // string |
The segment's unique identifier. Can be found using the View
Segments API or in the URL of the segment when viewing it in the
dashboard.
$include_segment_detail = true; // bool | Set to true to include
segment metadata and filters in the response.
try {
$result = $apiInstance->getSegment($app_id, $segment_id, $include_segment_detail);
print_r($result);
} catch (\onesignal\client\ApiException $e) {
echo 'Exception when calling DefaultApi->getSegment: ', $e->getMessage(), PHP_EOL;
echo 'Status Code: ', $e->getCode(), PHP_EOL;
// getErrorMessages() flattens any error-envelope shape to a string[];
// the raw body remains on getResponseBody().
echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;
echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;
} catch (\Exception $e) {
echo 'Exception when calling DefaultApi->getSegment: ', $e->getMessage(), PHP_EOL;
}
- lang: go
label: Go SDK
source: |-
package main
import (
"context"
"fmt"
"os"
"github.com/OneSignal/onesignal-go-api/v5"
)
func main() {
appId := "YOUR_APP_ID" // string | The OneSignal App ID for your app. Available in Keys & IDs.
segmentId := "d6c5a3e1-9f17-44a1-9d10-7c0e4a2b1c8e" // string | The segment's unique identifier. Can be found using the View Segments API or in the URL of the segment when viewing it in the dashboard.
includeSegmentDetail := true // bool | Set to true to include segment metadata and filters in the response. (optional)
configuration := onesignal.NewConfiguration()
apiClient := onesignal.NewAPIClient(configuration)
restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, "YOUR_REST_API_KEY") // App REST API key required for most endpoints
resp, r, err := apiClient.DefaultApi.GetSegment(restAuth, appId, segmentId).IncludeSegmentDetail(includeSegmentDetail).Execute()
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `DefaultApi.GetSegment``: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {
// ErrorMessages() flattens any error-envelope shape to a []string;
// the raw body remains on Body().
fmt.Fprintf(os.Stderr, "Error Messages: %v\n", apiErr.ErrorMessages())
fmt.Fprintf(os.Stderr, "Response Body: %s\n", apiErr.Body())
}
}
// response from `GetSegment`: GetSegmentSuccessResponse
fmt.Fprintf(os.Stdout, "Response from `DefaultApi.GetSegment`: %v\n", resp)
}
- lang: ruby
label: Ruby SDK
source: >-
require 'onesignal'
# setup authorization
OneSignal.configure do |config|
# Configure Bearer authorization: rest_api_key
config.rest_api_key = 'YOUR_REST_API_KEY'
end
api_instance = OneSignal::DefaultApi.new
app_id = 'YOUR_APP_ID' # String | The OneSignal App ID for your
app. Available in Keys & IDs.
segment_id = 'd6c5a3e1-9f17-44a1-9d10-7c0e4a2b1c8e' # String | The
segment's unique identifier. Can be found using the View Segments
API or in the URL of the segment when viewing it in the dashboard.
opts = {
include_segment_detail: true # Boolean | Set to true to include segment metadata and filters in the response.
}
begin
# View Segment
result = api_instance.get_segment(app_id, segment_id, opts)
p result
rescue OneSignal::ApiError => e
puts "Error when calling DefaultApi->get_segment: #{e}"
puts "Status Code: #{e.code}"
# `e.error_messages` flattens any error-envelope shape to an Array;
# the raw body remains on `e.response_body`.
puts "Error Messages: #{e.error_messages}"
puts "Response Body: #{e.response_body}"
end
- lang: java
label: Java SDK
source: |-
// Import classes:
import com.onesignal.client.ApiClient;
import com.onesignal.client.ApiException;
import com.onesignal.client.Configuration;
import com.onesignal.client.auth.*;
import com.onesignal.client.model.*;
import com.onesignal.client.api.DefaultApi;
public class Example {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.onesignal.com");
// Configure HTTP bearer authorization: rest_api_key
HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication("rest_api_key");
rest_api_key.setBearerToken("YOUR_REST_API_KEY");
DefaultApi apiInstance = new DefaultApi(defaultClient);
String appId = "YOUR_APP_ID"; // String | The OneSignal App ID for your app. Available in Keys & IDs.
String segmentId = "d6c5a3e1-9f17-44a1-9d10-7c0e4a2b1c8e"; // String | The segment's unique identifier. Can be found using the View Segments API or in the URL of the segment when viewing it in the dashboard.
Boolean includeSegmentDetail = true; // Boolean | Set to true to include segment metadata and filters in the response.
try {
GetSegmentSuccessResponse result = apiInstance.getSegment(appId, segmentId, includeSegmentDetail);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling DefaultApi#getSegment");
System.err.println("Status code: " + e.getCode());
// getErrorMessages() flattens any error-envelope shape to a List;
// the raw body remains on getResponseBody().
System.err.println("Error messages: " + e.getErrorMessages());
System.err.println("Reason: " + e.getResponseBody());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}
- lang: csharp
label: C# SDK
source: |-
using System;
using System.Collections.Generic;
using System.Diagnostics;
using OneSignalApi.Api;
using OneSignalApi.Client;
using OneSignalApi.Model;
namespace Example
{
public class GetSegmentExample
{
public static void Main()
{
Configuration config = new Configuration();
config.BasePath = "https://api.onesignal.com";
// Configure Bearer token for authorization: rest_api_key
config.AccessToken = "YOUR_REST_API_KEY";
var apiInstance = new DefaultApi(config);
var appId = "YOUR_APP_ID"; // string | The OneSignal App ID for your app. Available in Keys & IDs.
var segmentId = "d6c5a3e1-9f17-44a1-9d10-7c0e4a2b1c8e"; // string | The segment's unique identifier. Can be found using the View Segments API or in the URL of the segment when viewing it in the dashboard.
var includeSegmentDetail = true; // bool? | Set to true to include segment metadata and filters in the response. (optional)
try
{
// View Segment
GetSegmentSuccessResponse result = apiInstance.GetSegment(appId, segmentId, includeSegmentDetail);
Debug.WriteLine(result);
}
catch (ApiException e)
{
Debug.Print("Exception when calling DefaultApi.GetSegment: " + e.Message );
Debug.Print("Status Code: "+ e.ErrorCode);
// e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;
// the raw body remains on e.ErrorContent.
Debug.Print("Error Messages: " + string.Join(", ", e.ErrorMessages));
Debug.Print("Response Body: " + e.ErrorContent);
Debug.Print(e.StackTrace);
}
}
}
}
- lang: rust
label: Rust SDK
source: |-
use onesignal_rust_api::apis::configuration::Configuration;
use onesignal_rust_api::apis::default_api;
#[tokio::main]
async fn main() {
let mut configuration = Configuration::new();
configuration.rest_api_key_token = Some("YOUR_REST_API_KEY".to_string());
// Realistic values are pulled from the spec's `example:` fields where present.
let app_id: &str = "YOUR_APP_ID";
let segment_id: &str = "d6c5a3e1-9f17-44a1-9d10-7c0e4a2b1c8e";
let include_segment_detail: Option = None;
match default_api::get_segment(&configuration, app_id, segment_id, include_segment_detail).await {
Ok(resp) => println!("{:?}", resp),
Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {
// `e.error_messages()` flattens any error-envelope shape to a Vec;
// the raw response remains on the ResponseError variant.
eprintln!("get_segment failed: {:?}", e.error_messages());
}
Err(e) => eprintln!("get_segment failed: {:?}", e),
}
}
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.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.