---
openapi: 3.0.3
info:
title: Braze REST API – Export user profile by segment
description: 'Use this endpoint to export all the users within a segment.
'
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: |
## 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/).
## Request body
```
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
```
```json
{
"segment_id" : (required, string) identifier for the segment to be exported,
"callback_endpoint" : (optional, string) endpoint to post a download URL when the export is available,
"fields_to_export" : (required, array of string) name of user data fields to export, you may also export custom attributes. New accounts must specify specific fields to export,
"output_format" : (optional, string) when using your own S3 bucket, specifies file format as 'zip' or 'gzip'. Defaults to ZIP file format,
"user_last_updated_at" : (optional, datetime as string) only export users whose profiles were last updated at or after this time. Must be a parseable datetime, such as "2024-01-01T00:00:00Z"
}
```
## Response
```json
{
"message": (string) returns 'success' when the request completes without errors,
"object_prefix": (required, string) the filename prefix that is used for the JSON file produced by this export, for example, 'bb8e2a91-c4aa-478b-b3f2-a4ee91731ad1-1464728599',
"url" : (optional, string) the URL where the segment export data can be downloaded if you do not have your own S3 credentials
}
```
### `null` URL
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.
## Credentials-based response details
If you have added your [S3]({{site.baseurl}}/partners/data_and_infrastructure_agility/cloud_storage/amazon_s3), [Azure]({{site.baseurl}}/partners/data_and_infrastructure_agility/cloud_storage/microsoft_azure_blob_storage_for_currents/), or [Google Cloud Storage]({{site.baseurl}}/partners/data_and_infrastructure_agility/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.
## Request parameters
The following table lists the request parameters for this endpoint.
| Parameter | Required | Data Type | Description |
| ----------------------------- | --------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `segment_id` | Required | String | 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/). |
| `callback_endpoint` | Optional | String | Endpoint to post a download URL to when the export is available. |
| `fields_to_export` | Required* | Array of strings | 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. |
| `custom_attributes_to_export` | Optional | Array of strings | 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**. |
| `output_format` | Optional | String | 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`. |
| `user_last_updated_at` | Optional | String | 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. |
**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.
## 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"
},
...
]
}
```
## Example request to export all custom attributes
```
curl --location --request POST 'https://rest.iad-01.braze.com/users/export/segment' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
"segment_id" : "segment_identifier",
"callback_endpoint" : "example_endpoint",
"fields_to_export" : ["first_name", "email", "purchases", "custom_attributes"],
"output_format" : "zip"
}'
```
## Example request to export specific custom attributes
```
curl --location --request POST 'https://rest.iad-01.braze.com/users/export/segment' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
"segment_id" : "segment_identifier",
"callback_endpoint" : "example_endpoint",
"fields_to_export" : ["first_name", "email", "purchases"],
"custom_attributes_to_export" : ["allergies", "favorite_food"],
"output_format" : "zip"
}'
```
## Example request to export users updated at or after a given time
```
curl --location --request POST 'https://rest.iad-01.braze.com/users/export/segment' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
"segment_id" : "segment_identifier",
"fields_to_export" : ["first_name", "email", "external_id"],
"user_last_updated_at" : "2024-01-01T00:00:00Z"
}'
```
## 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 |
| --- | --- | --- | --- |
| `2XX Success` | The request was accepted and the export was queued. | `success` | No action needed. |
| `400 Bad Request` | The `segment_id` is missing or empty. | `nothing-to-export` | Include a valid `segment_id` in the request body. |
| `400 Bad Request` | The `segment_id` doesn't match a segment in this workspace. | `invalid-segment-id` | Pass a valid `segment_id`. Find it with the [Export segment list endpoint]({{site.baseurl}}/api/endpoints/export/segments/get_segment/). |
| `400 Bad Request` | The `fields_to_export` value isn't an array. | `Invalid format of fields to export. Needs to be an array.` | Pass `fields_to_export` as an array of field-name strings. |
| `400 Bad Request` | The `custom_attributes_to_export` value isn't formatted correctly. | `Invalid format of custom attributes to export.` | Pass `custom_attributes_to_export` as an array of custom attribute names. |
| `400 Bad Request` | You requested more than 500 custom attributes. | `Number of custom attributes cannot exceed 500` | Request 500 or fewer custom attributes. |
| `400 Bad Request` | Exporting specific custom attributes is disabled for this workspace. | `Exporting specific custom attributes is disabled.` | Remove `custom_attributes_to_export`, or contact [Support]({{site.baseurl}}/braze_support/) to enable it. |
| `400 Bad Request` | The `callback_endpoint` isn't a valid URL. | `Invalid callback URL.` | Provide a valid URL for `callback_endpoint`, or omit it. |
| `400 Bad Request` | The `output_format` value isn't supported. | `Invalid file output_format` | Set `output_format` to `zip` or `gzip`. |
| `400 Bad Request` | The `user_last_updated_at` value isn't a parseable datetime. | `Invalid user_last_updated_at. Must be a parseable datetime.` | Pass a parseable datetime, such as `2024-01-01T00:00:00Z`, or omit `user_last_updated_at`. |
| `429 Too Many Requests` | An export of this segment is already in progress. | `An export of the segment: {name} is already in progress` | Wait for the in-progress export of that segment to finish before requesting another. |
| `429 Too Many Requests` | Too many exports are already running for this workspace. | `Too many exports currently in progress.` | Wait for in-progress exports to finish, 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 `users.export.segment` 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/).
[1]: {{site.baseurl}}/partners/data_and_analytics/cloud_storage/amazon_s3
[2]: {{site.baseurl}}/partners/data_and_analytics/cloud_storage/microsoft_azure_blob_storage_for_currents/
[3]: {{site.baseurl}}/partners/data_and_analytics/cloud_storage/google_cloud_storage_for_currents/
operationId: post_users_export_segment_post_users_segment
tags:
- Export
responses:
'2XX':
description: The request was accepted and the export was queued.
content:
application/json:
schema:
$ref: '#/components/schemas/UsersSegmentResponse'
'400':
description: |-
Bad Request. Causes include:
- `nothing-to-export` — The `segment_id` is missing or empty.
- `invalid-segment-id` — The `segment_id` doesn't match a segment in this workspace.
- `Invalid format of fields to export. Needs to be an array.` — The `fields_to_export` value isn't an array.
- `Invalid format of custom attributes to export.` — The `custom_attributes_to_export` value isn't formatted correctly.
- `Number of custom attributes cannot exceed 500` — You requested more than 500 custom attributes.
- `Exporting specific custom attributes is disabled.` — Exporting specific custom attributes is disabled for this workspace.
- `Invalid callback URL.` — The `callback_endpoint` isn't a valid URL.
- `Invalid file output_format` — The `output_format` value isn't supported.
- `Invalid user_last_updated_at. Must be a parseable datetime.` — The `user_last_updated_at` value isn't a parseable datetime.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: |-
Too Many Requests. Causes include:
- `An export of the segment: {name} is already in progress` — An export of this segment is already in progress.
- `Too many exports currently in progress.` — Too many exports are already running for this workspace.
- `Over rate limit` — You exceeded the rate limit for this endpoint.
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'
'5XX':
description: An unexpected error occurred on the Braze server.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
segment_id:
type: string
description: Identifier for the segment to be exported. See segment identifier. The `segment_id` for a given segment can be found from the API Keys page within your Braze account or you can use the Segment List Endpoint.
callback_endpoint:
type: string
description: Endpoint to post a download URL to when the export is available.
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 for a complete list of fields you can export.
custom_attributes_to_export:
type: array
items:
type: string
description: Name of specific custom attribute to export. Up to 500 custom attributes can be exported. To create and manage custom attributes in the dashboard, go to **Data Settings** > **Custom Attributes**.
output_format:
type: string
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`.
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.
required:
- segment_id
- fields_to_export
examples:
export_all_custom_attributes:
summary: Export all custom attributes
value:
segment_id: segment_identifier
callback_endpoint: example_endpoint
fields_to_export:
- first_name
- email
- purchases
- custom_attributes
output_format: zip
export_specific_custom_attributes:
summary: Export specific custom attributes
value:
segment_id: segment_identifier
callback_endpoint: example_endpoint
fields_to_export:
- first_name
- email
- purchases
custom_attributes_to_export:
- allergies
- favorite_food
output_format: zip
export_users_updated_since:
summary: 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'
components:
schemas:
UsersSegmentResponse:
type: object
properties:
message:
type: string
description: Returns `success` when the request completes without errors.
object_prefix:
type: string
description: The prefix of the exported file names, used to locate the export output.
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:
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