---
openapi: 3.0.3
info:
title: Braze REST API – Export segment details
description: 'Use this endpoint to retrieve relevant information on a segment, which can be identified by the `segment_id`.
'
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/details":
get:
summary: Export segment details
description: |
## Prerequisites
To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key/) with the `segments.details` 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 |
| ------------ | -------- | --------- | ---------------------- |
| `segment_id` | Required | String | See [Segment API identifier]({{site.baseurl}}/api/identifier_types/).
The `segment_id` for a given segment can be found on the [API Keys]({{site.baseurl}}/user_guide/administer/global/workspace_settings/apis_and_identifiers/) page within your Braze account or you can use the [Export segment list endpoint]({{site.baseurl}}/api/endpoints/export/segments/get_segment/). |
## Example request
The following sample request shows an example of how to export segment details.
```
curl --location -g --request GET 'https://rest.iad-01.braze.com/segments/details?segment_id={{segment_identifier}}' \
--header 'Authorization: Bearer YOUR_REST_API_KEY'
```
## Response
The following sample response shows an example of the response returned when you export segment details.
```json
{
"message": (string) returns 'success' when the request completes without errors,
"created_at" : (string) the date created as ISO 8601 date,
"updated_at" : (string) the date last updated as ISO 8601 date,
"name" : (string) the segment name,
"description" : (string) a human-readable description of filters,
"text_description" : (string) the segment description,
"tags" : (array) the tag names associated with the segment formatted as strings,
"teams" : (array) the names of the Teams associated with the campaign
}
```
## 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 details. | `success` | No action needed. |
| `400 Bad Request` | The `segment_id` is missing, isn't a string, or doesn't match a segment in this workspace. | `segment_id must be a string of the object api identifier` | Pass a valid `segment_id` string. Find it on the [API Keys page]({{site.baseurl}}/user_guide/administer/global/workspace_settings/apis_and_identifiers/) or with the [Export segment list endpoint]({{site.baseurl}}/api/endpoints/export/segments/get_segment/). |
| `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.details` 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_details_get_segment_details
tags:
- Export
responses:
'200':
description: The request succeeded and the response body includes the segment details.
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentDetailsResponse'
'400':
description: The `segment_id` is missing, isn't a string, or doesn't match a segment in this workspace.
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: segment_id
in: query
required: true
description: See Segment API identifier. The `segment_id` for a given segment can be found on the API Keys page within your Braze account or you can use the Export segment list endpoint.
schema:
type: string
components:
schemas:
SegmentDetailsResponse:
type: object
properties:
message:
type: string
description: Returns 'success' when the request completes without errors.
created_at:
type: string
description: The date created as ISO 8601 date.
updated_at:
type: string
description: The date last updated as ISO 8601 date.
name:
type: string
description: The segment name.
description:
type: string
description: A human-readable description of filters.
text_description:
type: string
description: The segment description.
tags:
type: array
items:
type: string
description: The tag names associated with the segment formatted as strings.
teams:
type: array
items:
type: string
description: The names of the Teams associated with the campaign.
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