Users by Segment Endpoint
/users/export/segment
This endpoint allows you to export all the users within a segment. User data is exported as multiple files of user JSON objects separated by new lines (i.e. one JSON object per line).
Looking for the api_key
parameter?
As of May 2020, Braze has changed how we read API keys to be more secure. Now API keys must be passed as a request header, please see YOUR_REST_API_KEY
within the Example Request below.
Braze will continue to support the api_key
being passed through the request body and URL parameters, but will eventually be sunset. Please update your API calls accordingly.
Credentials-Based Response Details
If you have added your S3 credentials to Braze, then each file will be uploaded in 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
. We will create 1 file per 5,000 users to optimize processing. You can then unzip 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 will be .gz
instead of .zip
.
Export Pathing Breakdown for ZIP File
ZIP file format:
bucket-name/segment-export/SEGMENT_ID/YYYY-MM-dd/RANDOM_UUID-TIMESTAMP_WHEN_EXPORT_STARTED/filename.zip
Example ZIP File:
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. | 1556044807 |
filename |
Random per file. | 114f0226319130e1a4770f2602b5639a |
If you do not have S3 credentials provided, the response to the request provides the URL where a zip file containing all the user files can be downloaded. The URL will only become a valid location once the export is ready. Please be aware that if you do not have S3 credentials, there is a limitation on the amount of data that 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 specifying only the fields you need, in order to keep the size of the transfer lower. If you want to export all your users and are getting errors generating the file, consider breaking your user base up into more segments based on a random bucket number (e.g. create a segment where random bucket number <1000, between 1000 and 2000, etc).
In either scenario, you may optionally provide a callback_endpoint
to be notified when the export is ready. If the callback_endpoint
is provided, we will make a post request to the provided address when the download is ready. The body of the post will be “success”:true. If you have not added S3 credentials to Braze, then the body of the post will additionally have the attribute url
with the download url as the value.
Larger user bases will result in longer export times. For example, an app with 20 million users could take an hour or more.
Request Body
1
2
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY
1
2
3
4
5
6
{
"segment_id" : (required, string) identifier for the segment to be exported,
"callback_endpoint" : (optional, string) endpoint to post a download url to when the export is available,
"fields_to_export" : (optional, array of string) name of user data fields to export, e.g. ['first_name', 'email', 'purchases']. Defaults to all if not provided.
"output_format" : (optional, string) When using your own S3 bucket, allows to specify file format as 'zip' or 'gzip'. Defaults to zip file format
}
The segment_id
for a given segment can be found in your Developer Console within your Braze account or you can use the Segment List Endpoint.
Individual custom attributes cannot be exported. However, all custom attributes can be exported by including custom_attributes
in the fields_to_export
array (e.g. [‘first_name’, ‘email’, ‘custom_attributes’]).
Request Parameters
Key | Requirement | Data Type | Details |
---|---|---|---|
segment_id |
Required | String | Identifier for the segment to be exported |
callback_endpoint |
Optional | String | Endpoint to post a download url to when the export is available |
fields_to_export |
Optional | Array of Strings | Name of user data fields to export. You may export custom attributes. Defaults to all if not provided. |
output_format |
Optional | String | When using your own S3 bucket, allows to specify file format as ‘zip’ or ‘gzip’. Defaults to zip file format |
Request Components
Example Request
1
2
3
4
5
6
7
8
9
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" : "",
"callback_endpoint" : "",
"fields_to_export" : ["field1", "field2", "field3"],
"output_format" : ""
}'
Fields to Export
The following is a list of valid fields_to_export
. Using fields_to_export
to minimize the data returned can improve response time of this API endpoint:
apps
attributed_campaign
attributed_source
attributed_adgroup
attributed_ad
braze_id
campaigns_received
canvases_received
cards_clicked
country
created_at
custom_attributes
custom_events
devices
dob
email
email_subscribe
external_id
first_name
gender
home_city
language
last_coordinates
last_name
phone
purchases
push_subscribe
push_tokens
random_bucket
time_zone
total_revenue
uninstalled_at
user_aliases
Response
1
2
3
4
5
6
7
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY
{
"message": (required, string) the status of the export, returns 'success' when completed without errors,
"object_prefix": (required, string) the filename prefix that will be used for the JSON file produced by this export, e.g. '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
}
Once made available, the url will only be valid for a few hours. As such, we highly recommend that you add your own S3 credentials to Braze.
Sample User Export File Output
User export object (we will include the least data possible - if a field is missing from the object it should be assumed to be null, false, or empty):
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
{
"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),
"phone" : (string),
"language" : (string) ISO-639 two letter code,
"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,
"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,
"windows_ad_id" : (string) only included for Windows devices,
"ad_tracking_enabled" : (bool)
},
...
],
"push_tokens" : [
{
"app" : (string) app name,
"platform" : (string),
"token" : (string)
},
...
],
"apps" : [
{
"name" : (string),
"platform" : (string),
"version" : (string),
"sessions" : (string),
"first_used" : (string) date,
"last_used" : (string) date
},
...
],
"campaigns_received" : [
{
"name" : (string),
"last_received" : (string) date,
"engaged" : {
"opened_email" : (bool),
"opened_push" : (bool),
"clicked_email" : (bool),
"clicked_in_app_message" : (bool)
},
"converted" : (bool),
"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, bool) 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": (bool),
"last_exited": (string) date,
"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)
},
...
]
}
For help with CSV and API exports, visit our troubleshooting article here.