---
openapi: 3.0.3
info:
title: Braze REST API – Export user profile by Global Control Group
description: 'Use this endpoint to export all users within a Global Control Group.
'
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/global_control_group":
post:
summary: Export user profile by Global Control Group
description: |
## Prerequisites
To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key-permissions) 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]({{site.baseurl}}/api/api_limits/).
## Example request
```
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"
}'
```
## Credentials-based response details
If you have added your [S3]({{site.baseurl}}/partners/data_and_analytics/cloud_storage/amazon_s3/) or [Azure]({{site.baseurl}}/partners/data_and_analytics/cloud_storage/microsoft_azure_blob_storage_for_currents/) credentials to Braze through the respective **Technology Partners** page, then each file is 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 create one 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 (by going to **Partner Integrations** > **Technology Partners** > partner page) 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 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 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 make a post request to the provided address when the download is ready. The body of the post is `"success":true`. If you haven't added your cloud storage credentials to Braze, the body of the post additionally has 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
```
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
```
```json
{
"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
}
**Warning:**
Individual custom attributes cannot be exported. However, all custom attributes can be exported by including custom_attributes in the fields_to_export array (for example, `['first_name', 'email', 'custom_attributes']`).
## Request parameters
The following table lists the request parameters for this endpoint.
| 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. |
## 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]({{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. |
| `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. |
| `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. |
| `purchase`s | Array | Purchases this user has made in the last 90 days. |
| `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. |
## 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
}
After the URL is made available, it is valid for only a few hours. As such, we highly recommend that you add your own S3 credentials to Braze.
### Example user export file output
User export object (we include the least data possible—if a field is missing from the object it should be assumed to be null or empty):
### All fields
The following sample request body shows an example for 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),
"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
},
...
]
}
```
### 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",
"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"
},
...
]
}
```
## 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` | No global control group is assigned for this workspace. | `Global control group is not assigned` | Assign a global control group before requesting this export. |
| `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`. |
| `429 Too Many Requests` | A global control group export is already in progress. | `Global control group is currently exporting` | Wait for the in-progress export to finish, then retry. |
| `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.global_control_group` 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/). |
operationId: post_users_export_global_control_group_post_users_global_control_group
tags:
- Export
responses:
'2XX':
description: The request was accepted and the export was queued.
content:
application/json:
schema:
$ref: '#/components/schemas/UsersGlobalControlGroupResponse'
'400':
description: |-
Bad Request. Causes include:
- `Global control group is not assigned` — No global control group is assigned for 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.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: |-
Too Many Requests. Causes include:
- `Global control group is currently exporting` — A global control group export 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:
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 may also export custom attributes. *Beginning April 2021, new accounts must specify specific fields to export.
output_format:
type: string
description: When using your own S3 bucket, allows to specify file format as `zip` or `gzip`. Defaults to ZIP file format.
required:
- fields_to_export
examples:
example_request:
summary: Example request
value:
callback_endpoint: ''
fields_to_export:
- email
- braze_id
output_format: zip
components:
schemas:
UsersGlobalControlGroupResponse:
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