---
openapi: 3.0.3
info:
title: Braze REST API – Export user profile by segment
description: |
## Prerequisites
To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key-permissions) with the `users.export.segment` permission.
## Rate limit
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits]({{site.baseurl}}/api/api_limits/).
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:
/users/export/segment:
post:
summary: Export user profile by segment
description: |
## Credentials-based response details
If you have added your [S3]({{site.baseurl}}/partners/data_and_analytics/cloud_storage/amazon_s3), [Azure]({{site.baseurl}}/partners/data_and_analytics/cloud_storage/microsoft_azure_blob_storage_for_currents/), or [Google Cloud Storage]({{site.baseurl}}/partners/data_and_analytics/cloud_storage/google_cloud_storage_for_currents/) credentials to Braze, then each file is uploaded to your bucket as a ZIP file with the key format that looks like `segment-export/SEGMENT_ID/YYYY-MM-dd/RANDOM_UUID-TIMESTAMP_WHEN_EXPORT_STARTED/filename.zip`. If using Azure, make sure that you have the **Make this the default data export destination** box checked in the Azure partner overview page in Braze. Generally, Braze creates 1 file per 5,000 users to optimize processing. Exporting smaller segments within a large workspace may result in multiple files. You can then extract the files and concatenate all of the `json` files to a single file if needed. If you specify an `output_format` of `gzip`, then the file extension is `.gz` instead of `.zip`.
### Export pathing breakdown for ZIP
**ZIP format:**
`bucket-name/segment-export/SEGMENT_ID/YYYY-MM-dd/RANDOM_UUID-TIMESTAMP_WHEN_EXPORT_STARTED/filename.zip`
**Example ZIP:**
`braze.docs.bucket/segment-export/abc56c0c-rd4a-pb0a-870pdf4db07q/2019-04-25/d9696570-dfb7-45ae-baa2-25e302r2da27-1556044807/114f0226319130e1a4770f2602b5639a.zip`
| Property | Details | Shown in Example as |
| ------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------- |
| `bucket-name` | Fixed based on your bucket name. | `braze.docs.bucket` |
| `segment-export` | Fixed. | `segment-export` |
| `SEGMENT_ID` | Included in the export request. | `abc56c0c-rd4a-pb0a-870pdf4db07q` |
| `YYYY-MM-dd` | The date the successful callback is received. | `2019-04-25` |
| `RANDOM_UUID` | A random UUID generated by Braze at the time of the request. | `d9696570-dfb7-45ae-baa2-25e302r2da27` |
| `TIMESTAMP_WHEN_EXPORT_STARTED` | Unix time (seconds since 2017-01-01:00:00:00Z) that the export was requested in UTC. | `1556044807` |
| `filename` | Random per file. | `114f0226319130e1a4770f2602b5639a` |
We strongly suggest setting up your own S3 or Azure credentials when using this endpoint to enforce your own bucket policies on the export. If you do not have your cloud storage credentials, the response to the request provides the URL where a ZIP file containing all the user files can be downloaded. The URL becomes a valid location only after the export is ready.
Be aware that if you do not provide your cloud storage credentials, there is a limitation on the amount of data you can export from this endpoint. Depending on the fields you're exporting and the number of users, the file transfer may fail if it is too large. A best practice is to specify which fields you want to export using `fields_to_export` and specify only the fields you need to keep the size of the transfer lower. If you are getting errors generating the file, consider breaking your user base into more segments based on a random bucket number (for example, create a segment where a random bucket number is less than 1,000 or between 1,000 and 2,000).
In either scenario, you may optionally provide a `callback_endpoint` to be notified when the export is ready. If the `callback_endpoint` is provided, Braze makes a post request to the provided address when the download is ready. The body of the post is "success":true. If you have not added S3 credentials to Braze, then the body of the post additionally has the attribute `url` with the download URL as the value.
Larger user bases result in longer export times. For example, an app with 20 million users could take an hour or more.
## Fields to export
The following is a list of valid `fields_to_export`. Using `fields_to_export` to minimize the data returned can improve the response time of this API endpoint:
| Field to export | Data type | Description |
| --------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apps` | Array | Apps this user has logged sessions for, which includes the fields:
- `name`: app name
- `platform`: app platform, such as iOS, Android, or Web
- `version`: app version number or name
- `sessions`: total number of sessions for this app
- `first_used`: date of first session
- `last_used`: date of last session
All fields are strings. |
| `attributed_campaign` | String | Data from [attribution integrations]({{site.baseurl}}/partners/message_orchestration/), if set up. Identifier for a particular ad campaign. |
| `attributed_source` | String | Data from [attribution integrations]({{site.baseurl}}/partners/message_orchestration/), if set up. Identifier for the platform the ad was on. |
| `attributed_adgroup` | String | Data from [attribution integrations]({{site.baseurl}}/partners/message_orchestration/), if set up. Identifier for an optional sub-grouping below campaign. |
| `attributed_ad` | String | Data from [attribution integrations]({{site.baseurl}}/partners/message_orchestration/), if set up. Identifier for an optional sub-grouping below campaign and ad group. |
| `push_subscribe` | String | User's push subscription status. |
| `email_subscribe` | String | User's email subscription status. |
| `braze_id` | String | Device-specific unique user identifier set by Braze for this user. |
| `country` | String | User's country using [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard. |
| `created_at` | String | Date and time for when the user profile was created, in ISO 8601 format. |
| `created_from` | String | Method used to create the user profile (for example, SDK, REST API, or CSV import). |
| `custom_attributes` | Object | Custom attribute key-value pairs for this user. |
| `custom_events` | Array | Custom events attributed to this user in the last 90 days. |
| `devices` | Array | Information about the user's device, which could include the following depending on platform:
- `model`: Device's model name
- `os`: Device's operating system
- `carrier`: Device's service carrier, if available
- `idfv`: (iOS) Braze device identifier, the Apple Identifier for Vendor, if exists
- `idfa`: (iOS) Identifier for Advertising, if exists
- `device_id`: (Android) Braze device identifier
- `google_ad_id`: (Android) Google Play Advertising Identifier, if exists
- `roku_ad_id`: (Roku) Roku Advertising Identifier
- `ad_tracking_enabled`: If ad tracking is enabled on the device, can be true or false |
| `dob` | String | User's date of birth in the format `YYYY-MM-DD`. |
| `email` | String | User's email address. |
| `external_id` | String | Unique user identifier for identified users. |
| `first_name` | String | User's first name. |
| `gender` | String | User's gender. Possible values are:
- `M`: male
- `F`: female
- `O`: other
- `N`: not applicable
- `P`: prefer not to say
- `nil`: unknown |
| `home_city` | String | User's home city. |
| `language` | String | User's language in ISO-639-1 standard. |
| `last_coordinates` | Array of floats | User's most recent device location, formatted as `[longitude, latitude]`. |
| `last_name` | String | User's last name. |
| `phone` | String | User's phone number in the format that was imported into Braze. For example, if a request to add a phone number comes in as `1234567890`, then it is exported in the same format. |
| `purchases` | Array | Purchases this user has made in the last 90 days. |
| `push_tokens` | Array | Information about the user's push tokens. |
| `random_bucket` | Integer | User's [random bucket number]({{site.baseurl}}/user_guide/data/distribution/braze_currents/event_glossary/customer_behavior_events#random-bucket-number-update-events), used to create uniformly distributed segments of random users. |
| `time_zone` | String | User's time zone in the same format as the IANA Time Zone Database. |
| `total_revenue` | Float | Total revenue attributed to this user. Total revenue is calculated based on purchases the user made during conversion windows for the campaigns and Canvases they received. |
| `uninstalled_at` | Timestamp | Date and time the user uninstalls the app. Omitted if the app has not been uninstalled. |
| `user_aliases` | Object | [User aliases object]({{site.baseurl}}/api/objects_filters/user_alias_object) containing the `alias_name` and `alias_label`, if exists. |
## Important reminders
- The fields for `custom_events`, `purchases`, `campaigns_received`, and `canvases_received` contain only data from the last 90 days.
- Both `custom_events` and `purchases` contain fields for `first` and `count`. Both of these fields reflect information from all time, and are not limited to data from the last 90 days. For example, if a particular user first did the event 90 days ago, this is accurately reflected in the `first` field, and the `count` field takes into account events that occurred prior to the last 90 days as well.
- The number of concurrent segment exports a company can run at the endpoint level is capped at 100. Attempts that surpass this limit result in an error.
- Attempting to export a segment a second time while the first export job is still running results in a 429 error.
- Subscription group data is not available through segment exports. To identify users by subscription status, create a separate segment based on subscription group membership and export that segment.
- A [`403 Forbidden` response]({{site.baseurl}}/user_guide/data/distribution/export_braze_data/export_troubleshooting/?sdktab=cloud%20storage%20connected#segment-export-api-downloads) often means the export file isn't ready yet.
## Example user export file output
User export object (Braze includes the least data possible—if a field is missing from the object, it should be assumed to be null or empty):
### All fields
```json
{
"created_at": (string),
"external_id" : (string),
"user_aliases" : [
{
"alias_name" : (string),
"alias_label" : (string)
}
],
"braze_id": (string),
"first_name" : (string),
"last_name" : (string),
"email" : (string),
"dob" : (string) date for the user's date of birth,
"home_city" : (string),
"country" : (string) ISO-3166-1 alpha-2 standard,
"phone" : (string),
"language" : (string) ISO-639-1 standard,
"time_zone" : (string),
"last_coordinates" : (array of float) [lon, lat],
"gender" : (string) "M" | "F",
"total_revenue" : (float),
"attributed_campaign" : (string),
"attributed_source" : (string),
"attributed_adgroup" : (string),
"attributed_ad" : (string),
"push_subscribe" : (string) "opted_in" | "subscribed" | "unsubscribed",
"email_subscribe" : (string) "opted_in" | "subscribed" | "unsubscribed",
"custom_attributes" : (object) custom attribute key-value pairs,
"custom_events" : [
{
"name" : (string),
"first" : (string) date,
"last" : (string) date,
"count" : (int)
},
...
],
"purchases" : [
{
"name" : (string),
"first" : (string) date,
"last" : (string) date,
"count" : (int)
},
...
],
"devices" : [
{
"model" : (string),
"os" : (string),
"carrier" : (string),
"idfv" : (string) only included for iOS devices when IDFV collection is enabled,
"idfa" : (string) only included for iOS devices when IDFA collection is enabled,
"google_ad_id" : (string) only included for Android devices when Google Play Advertising Identifier collection is enabled,
"roku_ad_id" : (string) only included for Roku devices,
"ad_tracking_enabled" : (boolean)
},
...
],
"push_tokens" : [
{
"app" : (string) app name,
"platform" : (string),
"token" : (string),
"device_id": (string),
"notifications_enabled": (boolean) whether foreground push notifications are enabled for this token. `true` means foreground push is enabled for the token, and `false` means foreground push is disabled (for example, background-only). This is device-level and doesn't indicate the user's global push subscription status,
"provisionally_opted_in": (boolean) included for iOS and Android tokens only. Indicates whether the token is in a provisional push authorization state. `true` means the token is provisionally opted in (notifications are delivered quietly), `false` means the token isn't provisional (the user has explicitly authorized or denied push), and `null` means provisional status isn't set. Provisional authorization applies to iOS; Android tokens report `null`
},
...
],
"apps" : [
{
"name" : (string),
"platform" : (string),
"version" : (string),
"sessions" : (integer),
"first_used" : (string) date,
"last_used" : (string) date
},
...
],
"campaigns_received" : [
{
"name" : (string),
"last_received" : (string) date,
"engaged" :
{
"opened_email" : (boolean),
"opened_push" : (boolean),
"clicked_email" : (boolean),
"clicked_triggered_in_app_message" : (boolean)
},
"converted" : (boolean),
"api_campaign_id" : (string),
"variation_name" : (optional, string) exists only if it is a multivariate campaign,
"variation_api_id" : (optional, string) exists only if it is a multivariate campaign,
"in_control" : (optional, boolean) exists only if it is a multivariate campaign
},
...
],
"canvases_received": [
{
"name": (string),
"api_canvas_id": (string),
"last_received_message": (string) date,
"last_entered": (string) date,
"variation_name": (string),
"in_control": (boolean),
"steps_received": [
{
"name": (string),
"api_canvas_step_id": (string),
"last_received": (string) date
},
{
"name": (string),
"api_canvas_step_id": (string),
"last_received": (string) date
},
{
"name": (string),
"api_canvas_step_id": (string),
"last_received": (string) date
}
]
},
...
],
"cards_clicked" : [
{
"name" : (string)
},
...
]
}
```
### Sample output
The following sample request body shows an example for Sample output.
```json
{
"created_at" : "2020-07-10 15:00:00.000 UTC",
"external_id" : "A8i3mkd99",
"user_aliases" : [
{
"alias_name" : "user_123",
"alias_label" : "amplitude_id"
}
],
"braze_id": "5fbd99bac125ca40511f2cb1",
"random_bucket" : 2365,
"first_name" : "Jane",
"last_name" : "Doe",
"email" : "jane.doe@example.com",
"dob" : "1980-12-21",
"home_city" : "Chicago",
"country" : "US",
"phone" : "+15551234567",
"language" : "en",
"time_zone" : "Eastern Time (US & Canada)",
"last_coordinates" : [41.84157636433568, -87.83520818508256],
"gender" : "F",
"total_revenue" : 65,
"attributed_campaign" : "braze_test_campaign_072219",
"attributed_source" : "braze_test_source_072219",
"attributed_adgroup" : "braze_test_adgroup_072219",
"attributed_ad" : "braze_test_ad_072219",
"push_subscribe" : "opted_in",
"push_opted_in_at": "2020-01-26T22:45:53.953Z",
"email_subscribe" : "subscribed",
"custom_attributes":
{
"loyaltyId": "37c98b9d-9a7f-4b2f-a125-d873c5152856",
"loyaltyPoints": "321",
"loyaltyPointsNumber": 107
},
"custom_events": [
{
"name": "Loyalty Acknowledgement",
"first": "2021-06-28T17:02:43.032Z",
"last": "2021-06-28T17:02:43.032Z",
"count": 1
},
...
],
"purchases": [
{
"name": "item_40834",
"first": "2021-09-05T03:45:50.540Z",
"last": "2022-06-03T17:30:41.201Z",
"count": 10
},
...
],
"devices": [
{
"model": "Pixel XL",
"os": "Android (Q)",
"carrier": null,
"device_id": "312ef2c1-83db-4789-967-554545a1bf7a",
"ad_tracking_enabled": true
},
...
],
"push_tokens": [
{
"app": "MovieCanon",
"platform": "Android",
"token": "12345abcd",
"device_id": "312ef2c1-83db-4789-967-554545a1bf7a",
"notifications_enabled": true
},
...
],
"apps": [
{
"name": "MovieCannon",
"platform": "Android",
"version": "3.29.0",
"sessions": 1129,
"first_used": "2020-02-02T19:56:19.142Z",
"last_used": "2021-11-11T00:25:19.201Z"
},
...
],
"campaigns_received": [
{
"name": "Email Unsubscribe",
"api_campaign_id": "d72fdc84-ddda-44f1-a0d5-0e79f47ef942",
"last_received": "2022-06-02T03:07:38.105Z",
"engaged":
{
"opened_email": true
},
"converted": true,
"multiple_converted":
{
"Primary Conversion Event - A": true
},
"in_control": false,
"variation_name": "Variant 1",
"variation_api_id": "1bddc73a-a134-4784-9134-5b5574a9e0b8"
},
...
],
"canvases_received": [
{
"name": "Non Global Holdout Group 4/21/21",
"api_canvas_id": "46972a9d-dc81-473f-aa03-e3473b4ed781",
"last_received_message": "2021-07-07T20:46:24.136Z",
"last_entered": "2021-07-07T20:45:24.000+00:00",
"variation_name": "Variant 1",
"in_control": false,
"last_entered_control_at": null,
"steps_received": [
{
"name": "Step",
"api_canvas_step_id": "43d1a349-c3c8-4be1-9fbe-ce708e4d1c39",
"last_received": "2021-07-07T20:46:24.136Z"
},
...
]
}
...
],
"cards_clicked" : [
{
"name" : "Loyalty Promo"
},
...
]
}
```
operationId: post_users_export_segment_post_users_segment
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExportUsersBySegmentRequest'
examples:
export_all_custom_attributes:
summary: Example request to export all custom attributes
value:
segment_id: segment_identifier
callback_endpoint: https://example.com/export-callback
fields_to_export:
- first_name
- email
- purchases
- custom_attributes
output_format: zip
export_specific_custom_attributes:
summary: Example request to export specific custom attributes
value:
segment_id: segment_identifier
callback_endpoint: https://example.com/export-callback
fields_to_export:
- first_name
- email
- purchases
custom_attributes_to_export:
- allergies
- favorite_food
output_format: zip
export_users_updated_since:
summary: Example request to export users updated at or after a given time
value:
segment_id: segment_identifier
fields_to_export:
- first_name
- email
- external_id
user_last_updated_at: '2024-01-01T00:00:00Z'
responses:
2XX:
description: |
The request was accepted and the export was queued. No action needed.
If the response includes `"url": null` (or omits a download URL) and you have configured a [cloud storage integration]({{site.baseurl}}/user_guide/data/distribution/export_braze_data/export_troubleshooting) such as an Amazon S3 bucket or Azure Blob Storage container, Braze writes the export to your connected bucket or container instead of returning a temporary download URL in the API response. Retrieve the files from your connected cloud storage bucket or container.
If a download URL is returned, it is valid for only a few hours. As such, we highly recommend that you add your own S3 credentials to Braze.
If you see `object_prefix` in your API response and no URL to download the data, this means you have an Amazon S3 bucket already set up for this endpoint. Any data exported using this endpoint goes directly to your S3 bucket.
content:
application/json:
schema:
$ref: '#/components/schemas/UsersSegmentResponse'
examples:
braze_hosted:
summary: Export queued, download URL returned
value:
message: success
object_prefix: bb8e2a91-c4aa-478b-b3f2-a4ee91731ad1-1464728599
url: https://example.com/segment-export/bb8e2a91-c4aa-478b-b3f2-a4ee91731ad1-1464728599.zip
cloud_storage:
summary: Export queued to your cloud storage
value:
message: success
object_prefix: bb8e2a91-c4aa-478b-b3f2-a4ee91731ad1-1464728599
"400":
description: |
Bad request. To resolve it:
- **The `segment_id` is missing or empty:** Include a valid `segment_id` in the request body.
- **The `segment_id` doesn't match a segment in this workspace:** Pass a valid `segment_id`. Find it with the [Export segment list endpoint]({{site.baseurl}}/api/endpoints/export/segments/get_segment/).
- **The `fields_to_export` value isn't an array:** Pass `fields_to_export` as an array of field-name strings.
- **The `custom_attributes_to_export` value isn't formatted correctly:** Pass `custom_attributes_to_export` as an array of custom attribute names.
- **You requested more than 500 custom attributes:** Request 500 or fewer custom attributes.
- **Exporting specific custom attributes is disabled for this workspace:** Remove `custom_attributes_to_export`, or contact [Support]({{site.baseurl}}/braze_support/) to enable it.
- **The `callback_endpoint` isn't a valid URL:** Provide a valid URL for `callback_endpoint`, or omit it.
- **The `output_format` value isn't supported:** Set `output_format` to `zip` or `gzip`.
- **The `user_last_updated_at` value isn't a parseable datetime:** Pass a parseable datetime, such as `2024-01-01T00:00:00Z`, or omit `user_last_updated_at`.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
nothing_to_export:
summary: Missing or empty segment_id
value:
message: nothing-to-export
invalid_segment_id:
summary: Unknown segment_id
value:
message: invalid-segment-id
invalid_fields_to_export:
summary: fields_to_export isn't an array
value:
message: Invalid format of fields to export. Needs to be an array.
invalid_custom_attributes_to_export:
summary: custom_attributes_to_export isn't formatted correctly
value:
message: Invalid format of custom attributes to export.
too_many_custom_attributes:
summary: More than 500 custom attributes
value:
message: Number of custom attributes cannot exceed 500
custom_attributes_disabled:
summary: Exporting specific custom attributes is disabled
value:
message: Exporting specific custom attributes is disabled.
invalid_callback_url:
summary: Invalid callback_endpoint
value:
message: Invalid callback URL.
invalid_output_format:
summary: Unsupported output_format
value:
message: Invalid file output_format
invalid_user_last_updated_at:
summary: Invalid user_last_updated_at
value:
message: Invalid user_last_updated_at. Must be a parseable datetime.
"401":
description: |
Unauthorized. The REST API key is missing, malformed, or sent to the wrong REST endpoint. 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).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalid_api_key:
summary: Invalid API key
value:
message: 'Invalid API key: YOUR_REST_API_KEY'
"403":
description: Access denied. The REST API key doesn't have the required permission. Use a REST API key that has the `users.export.segment` permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
access_denied:
summary: Missing permission
value:
message: Access Denied
"429":
description: |
Too many requests. To resolve it:
- **An export of this segment is already in progress:** Wait for the in-progress export of that segment to finish before requesting another.
- **Too many exports are already running for this workspace:** Wait for in-progress exports to finish, then retry.
- **You exceeded the rate limit for this endpoint:** Slow your request rate and retry with exponential backoff. See [API rate limits]({{site.baseurl}}/api/api_limits/).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
segment_export_in_progress:
summary: Export of this segment already in progress
value:
message: 'An export of the segment: {name} is already in progress'
too_many_exports:
summary: Too many exports in progress
value:
message: Too many exports currently in progress.
over_rate_limit:
summary: Over rate limit
value:
message: You have exceeded your limit of 250000 requests per hour. Please contact your account executive to increase your limit. If you do not have their info, you may contact Braze directly at https://www.braze.com/contact/.
5XX:
description: |
Internal server error. An unexpected error occurred on the Braze server. Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: REST API key
description: |
REST API keys are created in the Braze dashboard at **Settings → APIs and
Identifiers → API Keys**. The key must include the `users.export.segment` permission.
Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`.
schemas:
ExportUsersBySegmentRequest:
title: Export users by segment request
type: object
required: [segment_id, fields_to_export]
properties:
segment_id:
type: string
description: |
Identifier for the segment to be exported. See [segment identifier]({{site.baseurl}}/api/identifier_types/).
The `segment_id` for a given segment can be found from the [API Keys]({{site.baseurl}}/user_guide/administer/global/workspace_settings/apis_and_identifiers/) page within your Braze account or you can use the [Segment List Endpoint]({{site.baseurl}}/api/endpoints/export/segments/get_segment/).
example: segment_identifier
callback_endpoint:
type: string
format: uri
description: Endpoint to post a download URL to when the export is available.
example: https://example.com/export-callback
fields_to_export:
type: array
items:
type: string
description: |
Name of user data fields to export. You can also export all custom attributes by including `custom_attributes` in this parameter. Reference [Fields to export](#fields-to-export) for a complete list of fields you can export.
New accounts must specify specific fields to export.
example:
- first_name
- email
- purchases
custom_attributes_to_export:
type: array
maxItems: 500
items:
type: string
description: |
Names of specific custom attributes to export (up to 500). Omit `custom_attributes` from `fields_to_export` when you use this parameter, or Braze exports every custom attribute regardless of this list. To create and manage custom attributes in the dashboard, go to **Data Settings** > **Custom Attributes**.
**Note:**
If `custom_attributes` is included in the `fields_to_export` parameter, all custom attributes are exported regardless of what is in `custom_attributes_to_export`. If your goal is to export specific attributes, `custom_attributes` should not be included in the `fields_to_export` parameter. Instead, use the `custom_attributes_to_export` parameter.
example:
- allergies
- favorite_food
output_format:
type: string
enum: [zip, gzip]
default: zip
description: The output format of your file. Defaults to `zip` file format. If you are using your own S3 bucket, you can specify `zip` or `gzip`.
example: zip
user_last_updated_at:
type: string
format: date-time
description: Export only users whose profiles were last updated at or after this time. Must be a parseable datetime (for example, `2024-01-01T00:00:00Z`). Invalid values return a `400` error.
example: '2024-01-01T00:00:00Z'
UsersSegmentResponse:
title: Export users by segment response
type: object
required: [object_prefix]
properties:
message:
type: string
description: Returns `success` when the request completes without errors.
example: success
object_prefix:
type: string
description: The prefix of the exported file names, used to locate the export output, for example, `bb8e2a91-c4aa-478b-b3f2-a4ee91731ad1-1464728599`. Braze uses it as the filename prefix for the JSON files produced by this export.
example: bb8e2a91-c4aa-478b-b3f2-a4ee91731ad1-1464728599
url:
type: string
nullable: true
description: The URL the export can be downloaded from. Null when the workspace hosts its own exports, in which case the files are written to your own storage.
ErrorResponse:
title: Error
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.