---
openapi: 3.0.3
info:
title: Braze REST API – Export segment list
description: 'Use this endpoint to export a list of segments, each of which will include its name, Segment API identifier, and whether it has analytics tracking enabled.
'
version: 1.0.0
contact:
name: Braze Support
url: https://www.braze.com/docs/braze_support/
license:
name: Braze Documentation
url: https://www.braze.com/docs/api/home/
servers:
- url: https://rest.iad-01.braze.com
description: US-01
- url: https://rest.iad-02.braze.com
description: US-02
- url: https://rest.iad-03.braze.com
description: US-03
- url: https://rest.iad-04.braze.com
description: US-04
- url: https://rest.iad-05.braze.com
description: US-05
- url: https://rest.iad-06.braze.com
description: US-06
- url: https://rest.iad-07.braze.com
description: US-07
- url: https://rest.iad-08.braze.com
description: US-08
- url: https://rest.us-10.braze.com
description: US-10
- url: https://rest.fra-01.braze.eu
description: EU-01
- url: https://rest.fra-02.braze.eu
description: EU-02
- url: https://rest.au-01.braze.com
description: AU-01
- url: https://rest.id-01.braze.com
description: ID-01
- url: https://rest.jp-01.braze.com
description: JP-01
- url: https://rest.kr-01.braze.com
description: KR-01
security:
- BearerAuth: []
paths:
"/segments/list":
get:
summary: Export segment list
description: |
## Prerequisites
To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key/) with the `segments.list` permission.
## Rate limit
For rate limit details, see [API rate limits]({{site.baseurl}}/api/api_limits/).
## Request parameters
The following table lists the request parameters for this endpoint.
| Parameter| Required | Data Type | Description |
| -------- | -------- | --------- | ----------- |
| `page` | Optional | Integer | The page of segments to return, defaults to 0 (returns the first set of up to 100). |
| `sort_direction` | Optional | String | - Sort creation time from newest to oldest: pass in the value `desc`.
- Sort creation time from oldest to newest: pass in the value `asc`.
If `sort_direction` is not included, the default order is oldest to newest. |
## Example request
The following sample request shows an example of how to export segment list.
```
curl --location --request GET 'https://rest.iad-01.braze.com/segments/list?page=1&sort_direction=desc' \
--header 'Authorization: Bearer YOUR_REST_API_KEY'
```
## Response
The following sample response shows an example of the response returned when you export segment list.
```json
{
"message": (string) returns 'success' when the request completes without errors,
"segments" : [
{
"id" : (string) the Segment API identifier,
"name" : (string) segment name,
"analytics_tracking_enabled" : (boolean) whether the segment has analytics tracking enabled,
"tags" : (array) the tag names associated with the segment formatted as strings
},
...
]
}
```
## Response status codes
The following table lists the responses for this endpoint, the error message you may receive, and how to resolve it.
| Status code | Meaning | Error message | How to resolve |
| --- | --- | --- | --- |
| `200 OK` | The request succeeded and the response body includes the segment list. | `success` | No action needed. |
| `400 Bad Request` | The `page` value wasn't an integer. | `page must be an integer` | Pass a non-negative integer for the `page` parameter, then retry. |
| `401 Unauthorized` | The REST API key is missing, malformed, or sent to the wrong REST endpoint. | `Invalid API key` | Send the key as `Authorization: Bearer YOUR_REST_API_KEY` to the correct [REST endpoint]({{site.baseurl}}/api/basics/#endpoints). For more causes, see [Errors and responses]({{site.baseurl}}/api/errors/#fatal-errors). |
| `403 Access Denied` | The REST API key doesn't have the required permission. | `Access Denied` | Use a REST API key that has the `segments.list` permission. |
| `429 Rate Limited` | You exceeded the rate limit for this endpoint. | `Over rate limit` | Slow your request rate and retry with exponential backoff. See [API rate limits]({{site.baseurl}}/api/api_limits/). |
| `5XX Internal Server Error` | An unexpected error occurred on the Braze server. | `Internal Server Error` | Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/). |
**Tip:**
For help with CSV and API exports, visit [Export troubleshooting]({{site.baseurl}}/user_guide/data/distribution/export_braze_data/export_troubleshooting/).
operationId: get_segments_list_get_segment
tags:
- Export
responses:
'200':
description: The request succeeded and the response body includes the segment list.
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentResponse'
'400':
description: The `page` value wasn't an integer.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: The REST API key is missing, malformed, or sent to the wrong REST endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: The REST API key doesn't have the required permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: You exceeded the rate limit for this endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'5XX':
description: An unexpected error occurred on the Braze server.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
parameters:
- name: page
in: query
required: false
description: The page of segments to return, defaults to 0 (returns the first set of up to 100).
schema:
type: integer
minimum: 0
default: 0
- name: sort_direction
in: query
required: false
description: "- Sort creation time from newest to oldest: pass in the value `desc`. - Sort creation time from oldest to newest: pass in the value `asc`. If `sort_direction` is not included, the default order is oldest to newest."
schema:
type: string
components:
schemas:
SegmentResponse:
type: object
properties:
message:
type: string
description: Returns 'success' when the request completes without errors.
segments:
type: array
items:
type: object
properties:
id:
type: string
description: The Segment API identifier.
name:
type: string
description: Segment name.
analytics_tracking_enabled:
type: boolean
description: Whether the segment has analytics tracking enabled.
tags:
type: array
items:
type: string
description: The tag names associated with the segment formatted as strings.
ErrorResponse:
type: object
properties:
message:
type: string
description: The error message describing why the request failed.
errors:
type: array
description: Non-fatal errors encountered while processing the request. Data unaffected by these errors is still processed.
items:
type: object
properties:
type:
type: string
description: The error type.
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: REST API key