> ## 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 segments
> Retrieve a list of segments associated with a specific OneSignal app. Useful for programmatically accessing segment metadata such as name, creation date, and status.
## Overview
Retrieve a list of segments associated with a specific OneSignal app. This is helpful when you want to access segment metadata programmatically instead of using the OneSignal Dashboard UI.
This endpoint only retrieves existing segment metadata. It does not provide the segment filters or user data.
***
## OpenAPI
````yaml GET /apps/{app_id}/segments
openapi: 3.1.0
info:
title: api.onesignal.com
version: '11.6'
servers:
- url: https://api.onesignal.com
security:
- {}
paths:
/apps/{app_id}/segments:
get:
summary: View segments
description: >-
Retrieve a list of segments associated with a specific OneSignal app.
Useful for programmatically accessing segment metadata such as name,
creation date, and status.
operationId: view-segments
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: 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: offset
in: query
description: >-
The index to start returning segments from. Defaults to `0`.
Segments are sorted by their creation date (`created_at`) in
ascending order.
schema:
type: integer
format: int32
default: 0
- name: limit
in: query
description: >-
The maximum number of segments to return. Default/Max: `300`. Ideal
for controlling data volume in large-scale applications.
schema:
type: integer
format: int32
default: 300
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
total_count: 1
offset: 0
limit: 300
segments:
- id: 4414c404-56a3-11ed-9b6a-0242ac120002
name: Subscribed Users
description: YOUR_SEGMENT_DESCRIPTION
created_at: '2022-07-23T13:44:10.324Z'
updated_at: '2022-09-18T11:33:02.451Z'
app_id: 65c10914-56a3-11ed-9b6a-0242ac120002
read_only: false
is_active: true
schema:
type: object
properties:
total_count:
type: integer
description: The total number of segments available for the app.
offset:
type: integer
description: Value set in the `offset` query parameter.
limit:
type: integer
description: Value set in the `limit` query parameter.
segments:
type: array
items:
type: object
properties:
id:
type: string
description: >-
The unique identifier for the segment in UUID v4
format.
name:
type: string
description: >-
An internal name you set to help organize and track
Segments. Maximum 128 characters.
description:
type: string
nullable: true
description: >-
Human-readable description for the segment. `null`
when unset. Maximum 255 characters.
created_at:
type: string
description: >-
The date and time the segment was created in ISO
8601 format.
updated_at:
type: string
description: >-
The date and time the segment was last updated in
ISO 8601 format.
app_id:
type: string
description: >-
Your OneSignal App ID in UUID v4 format. See [Keys &
IDs](/docs/en/keys-and-ids).
read_only:
type: boolean
description: Indicates if the segment is read-only.
is_active:
type: boolean
description: >-
Indicates if the segment is active. `false` means
the segment is paused and cannot be used to send
messages.
'400':
description: '400'
content:
application/json:
examples:
Result:
value:
errors:
- code: example error code
title: example error title
meta: {}
schema:
$ref: '#/components/schemas/StructuredErrorResponse'
'429':
description: '429'
content:
application/json:
examples:
Result:
value:
errors:
- code: Rate Limit Exceeded
title: Example error title
meta: {}
schema:
$ref: '#/components/schemas/StructuredErrorResponse'
headers:
Retry-After:
description: >-
Number of seconds to wait before retrying the request. Always
emitted on 429 responses.
schema:
type: integer
minimum: 0
'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. Optional — may be
absent when the response is generated upstream.
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 = "00000000-0000-0000-0000-000000000000";
// number | Segments are listed in ascending order of created_at
date. offset will omit that number of segments from the beginning of
the list. Eg offset 5, will remove the 5 earliest created Segments.
(optional)
const offset: number = 0;
// number | The amount of Segments in the response. Maximum 300.
(optional)
const limit: number = 10;
try {
const response = await apiInstance.getSegments(appId, offset, limit);
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("getSegments 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 = "00000000-0000-0000-0000-000000000000" # The OneSignal App ID for your app. Available in Keys & IDs.
offset = 0 # Segments are listed in ascending order of created_at date. offset will omit that number of segments from the beginning of the list. Eg offset 5, will remove the 5 earliest created Segments. (optional)
limit = 10 # The amount of Segments in the response. Maximum 300. (optional)
try:
# Get Segments
api_response = api_instance.get_segments(app_id, offset=offset, limit=limit)
pprint(api_response)
except onesignal.ApiException as e:
print("Exception when calling DefaultApi->get_segments: %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 = '00000000-0000-0000-0000-000000000000'; // string | The
OneSignal App ID for your app. Available in Keys & IDs.
$offset = 0; // int | Segments are listed in ascending order of
created_at date. offset will omit that number of segments from the
beginning of the list. Eg offset 5, will remove the 5 earliest
created Segments.
$limit = 10; // int | The amount of Segments in the response.
Maximum 300.
try {
$result = $apiInstance->getSegments($app_id, $offset, $limit);
print_r($result);
} catch (\onesignal\client\ApiException $e) {
echo 'Exception when calling DefaultApi->getSegments: ', $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->getSegments: ', $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 := "00000000-0000-0000-0000-000000000000" // string | The OneSignal App ID for your app. Available in Keys & IDs.
offset := int32(0) // int32 | Segments are listed in ascending order of created_at date. offset will omit that number of segments from the beginning of the list. Eg offset 5, will remove the 5 earliest created Segments. (optional)
limit := int32(10) // int32 | The amount of Segments in the response. Maximum 300. (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.GetSegments(restAuth, appId).Offset(offset).Limit(limit).Execute()
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `DefaultApi.GetSegments``: %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 `GetSegments`: GetSegmentsSuccessResponse
fmt.Fprintf(os.Stdout, "Response from `DefaultApi.GetSegments`: %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 = '00000000-0000-0000-0000-000000000000' # String | The
OneSignal App ID for your app. Available in Keys & IDs.
opts = {
offset: 0, # Integer | Segments are listed in ascending order of created_at date. offset will omit that number of segments from the beginning of the list. Eg offset 5, will remove the 5 earliest created Segments.
limit: 10 # Integer | The amount of Segments in the response. Maximum 300.
}
begin
# Get Segments
result = api_instance.get_segments(app_id, opts)
p result
rescue OneSignal::ApiError => e
puts "Error when calling DefaultApi->get_segments: #{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 = "00000000-0000-0000-0000-000000000000"; // String | The OneSignal App ID for your app. Available in Keys & IDs.
Integer offset = 0; // Integer | Segments are listed in ascending order of created_at date. offset will omit that number of segments from the beginning of the list. Eg offset 5, will remove the 5 earliest created Segments.
Integer limit = 10; // Integer | The amount of Segments in the response. Maximum 300.
try {
GetSegmentsSuccessResponse result = apiInstance.getSegments(appId, offset, limit);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling DefaultApi#getSegments");
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 GetSegmentsExample
{
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 = "00000000-0000-0000-0000-000000000000"; // string | The OneSignal App ID for your app. Available in Keys & IDs.
var offset = 0; // int? | Segments are listed in ascending order of created_at date. offset will omit that number of segments from the beginning of the list. Eg offset 5, will remove the 5 earliest created Segments. (optional)
var limit = 10; // int? | The amount of Segments in the response. Maximum 300. (optional)
try
{
// Get Segments
GetSegmentsSuccessResponse result = apiInstance.GetSegments(appId, offset, limit);
Debug.WriteLine(result);
}
catch (ApiException e)
{
Debug.Print("Exception when calling DefaultApi.GetSegments: " + 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 = "00000000-0000-0000-0000-000000000000";
let offset: Option = None;
let limit: Option = None;
match default_api::get_segments(&configuration, app_id, offset, limit).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_segments failed: {:?}", e.error_messages());
}
Err(e) => eprintln!("get_segments failed: {:?}", e),
}
}
components:
schemas:
StructuredErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/StructuredErrorItem'
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.
StructuredErrorItem:
type: object
required:
- code
- title
properties:
code:
type: string
description: >-
Stable error-code identifier. Use this for programmatic branching in
your integration.
title:
type: string
description: >-
Human-readable error message intended for logs and operator-facing
surfaces.
meta:
type: object
additionalProperties: true
description: >-
Optional structured details about this specific error. The shape of
`meta` varies by `code` — for example, the create-user `Conflict`
code returns `{ conflicting_aliases: { [alias_label]: alias_id } }`.
````