Skip to content

Export user profile by segment

post

/users/export/segment

Use this endpoint 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). Data is exported to an automatically generated URL, or to an S3 bucket if this integration is already set up.

This endpoint is currently not supported by Google Cloud Storage.

Note that a company may run at most one export per segment using this endpoint at a given time. Wait for your export to complete before retrying.

Rate limit

We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.

Credentials-based response details

If you have added your S3 or Azure 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. 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, we will create 1 file per 5,000 users to optimize processing. Exporting smaller segments within a large workspace may result in multiple files. 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

We strongly suggest that customers who use this endpoint set up their own S3 or Azure credentials so that customers can enforce their own bucket policies on the export. If you do not have your cloud storage 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.

Be aware that if you do not provide your cloud storage 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 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" : (required, array of string) name of user data fields to export, you may also export custom attributes. *Beginning April 2021, 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
}

Request parameters

Parameter Required Data Type Description
segment_id Required String 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 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 may also export custom attributes.

*Beginning April 2021, new accounts must specify specific fields to export.
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.

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" : "segment_identifier",
  "callback_endpoint" : "example_endpoint",
  "fields_to_export" : ["first_name", "email", "purchases"],
  "output_format" : "zip"
}'

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:

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, if set up. Identifier for a particular ad campaign.
attributed_source String Data from attribution integrations, if set up. Identifier for the platform the ad was on.
attributed_adgroup String Data from attribution integrations, if set up. Identifier for an optional sub-grouping below campaign.
attributed_ad String Data from attribution integrations, if set up. Identifier for an optional sub-grouping below campaign and adgroup.
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 standard.
created_at String Date and time for when the user profile was created, in ISO 8601 format.
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’s device identifier, the Apple Identifier for Vendor, if exists
- idfa: (iOS) Identifier for Advertising, if exists
- device_id: (Android) Braze’s 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 telephone number in E.164 format.
purchases Array Purchases this user has made in the last 90 days.
random_bucket Integer User’s random bucket number, 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 containing the alias_name and alias_label, if exists.

Important reminders

  • The fields for custom_events, purchases, campaigns_received, and canvases_received will contain only contain data from the last 90 days.
  • Both custom_events and purchases contain fields for first and count. Both of these fields will reflect information from all time, and will not be limited to just data from the last 90 days. For example, if a particular user first did the event prior to 90 days ago, this will be accurately reflected in the first field, and the count field will take 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 will result in an error.

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
134
{
    "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" : (bool)
      },
      ...
    ],
    "push_tokens" : [
      {
        "app" : (string) app name,
        "platform" : (string),
        "token" : (string)
      },
      ...
    ],
    "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" : (bool),
           "opened_push" : (bool),
           "clicked_email" : (bool),
           "clicked_triggered_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)
      },
      ...
    ]
}
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
{
    "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" : "[email protected]",
    "dob" : "1980-12-21",
    "home_city" : "Chicago",
    "country" : "US",
    "phone" : "+442071838750",
    "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,
        "last_exited": "2021-07-07T20:46:24.136Z",
        "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"
      },
      ...
    ]
}
WAS THIS PAGE HELPFUL?
New Stuff!