Skip to content

Export user profile by Global Control Group

post

/users/export/global_control_group

Use this endpoint to export all users within a Global Control Group.

User data is exported as multiple files of user JSON objects separated by new lines (such as one JSON object per line). All users in a Global Control Group are included each time the files are generated. Braze doesn’t store a history of when users are added and removed from a Global Control Group.

Prerequisites

To use this endpoint, you’ll need an API key with the users.export.global_control_group 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.

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 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 will be .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 provided, the response to the request provides the URL where a ZIP containing all the user files can be downloaded. The URL will only become a valid location 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 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 (for example, create a segment where 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, 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 your cloud storage 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
{
  "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, for example, ['first_name', 'email', 'purchases'],
  "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 parameters

Parameter Required Data Type Description
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 When using your own S3 bucket, allows to specify file format as zip or gzip. Defaults to ZIP file format.

Example request

1
2
3
4
5
6
7
8
curl --location --request POST 'https://rest.iad-01.braze.com/users/export/global_control_group' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
  "callback_endpoint" : "",
  "fields_to_export" : ["email", "braze_id"],
  "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 ad group.
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 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 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.

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, 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
}

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
{
    "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),
    "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)
      },
      ...
    ],
    "apps" : [
      {
        "name" : (string),
        "platform" : (string),
        "version" : (string),
        "sessions" : (string),
        "first_used" : (string) date,
        "last_used" : (string) date
      },
      ...
    ],
}
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
{
    "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",
    "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
      },
      ...
    ],
    "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"
      },
      ...
    ],
}
HOW HELPFUL WAS THIS PAGE?
New Stuff!