Braze Loader

The Braze loader pulls data out of Braze  through the REST Export API — no Braze Currents subscription required. It brings your engagement platform’s user profiles (with custom attributes), segments, campaigns, Canvases, custom-event catalog, and daily KPIs into your data warehouse so you can model and activate them alongside the rest of your customer data.

Braze serves different objects in different ways, and this loader matches each one to how Braze actually exposes it:

• User profiles are exported asynchronously: Zeotap submits an export job for a segment, Braze produces a compressed archive of newline-delimited JSON, and the loader downloads and streams it.
• Everything else (segments, campaigns, Canvases, custom-event names, KPIs) is returned directly as JSON from a GET endpoint.

Prerequisites

• A Braze account with REST API access.
• A Braze REST API key with the export permissions for the streams you want (see Authentication).
• Your instance-specific REST endpoint (base URL).
• A connected Warehouse with write permissions on the target schema.

Authentication

The Braze loader authenticates with a REST API key sent as a Bearer token (Authorization: Bearer <key>).

Creating a REST API key

1. In the Braze dashboard, go to Settings > APIs and Identifiers > REST API Keys.
2. Click Create API Key.
3. Grant the permissions for the streams you plan to sync:
   • users.export.segment — User Profiles
   • segments.list — Segments
   • campaigns.list — Campaigns
   • canvas.list — Canvases
   • events.list — Custom Events (catalog)
   • kpi.dau.data_series — KPI — Daily Active Users
4. Save the key and paste it into the REST API Key field in Zeotap.

Finding your REST endpoint (base URL)

Braze is multi-instance — your account lives on one instance and you must call the matching REST endpoint. Find it on the same APIs and Identifiers page. Common values:

Paste the full URL (including https://) into the REST Endpoint (Base URL) field.

Configuration

The default User Profile Fields set includes identity fields, subscription status, total_revenue, all custom_attributes, and the 90-day engagement arrays (custom_events, purchases, campaigns_received, canvases_received), plus devices, push_tokens, apps, and user_aliases.

Available Objects

Purchases are intentionally not a standalone stream. Per-user purchase summaries (last 90 days) are already included in the user_profiles stream’s purchases column.

Key Columns

User Profiles (user_profiles) flattens each profile: identity fields (external_id, braze_id, email, phone, first_name, last_name, …) and total_revenue become typed top-level columns, while nested structures — custom_attributes, custom_events, purchases, devices, push_tokens, apps, user_aliases, campaigns_received, canvases_received, last_coordinates — are stored as JSON. A raw column preserves the complete original record so nothing is lost.

Sync Modes

• Incremental — campaigns and canvases support incremental sync on last_edited. Zeotap saves the highest last_edited it has seen and passes it back as the last_edit.time[gt] filter on the next run, so only campaigns/Canvases edited since the last sync are pulled.
• Full refresh — user_profiles, segments, custom_events, and kpi_dau re-read their full result each run. The segment export has no server-side incremental filter, and the segment/event catalogs and KPI window are small enough to re-pull cheaply.

Data Window

Within an exported user profile, the custom_events, purchases, campaigns_received, and canvases_received arrays reflect only the last 90 days of activity (this is a Braze API limitation). The first and count sub-fields on custom_events/purchases are all-time, however. The kpi_dau stream is bounded by the configurable KPI Lookback (1–100 days).

How It Works

• Async user-profile export — Zeotap POSTs an export job for the configured segment with your chosen fields_to_export. Braze responds with a download url. Because a large export takes time to generate (an app with 20M users can take an hour or more), the loader polls that URL — a 403/404 means “not ready yet” — and downloads the ZIP once it is available. Braze generates roughly one file per 5,000 users; the loader reads every file in the archive.
• Streaming, not buffering — The downloaded archive is written to a temporary file on disk, then each entry is decompressed and read line by line, emitting rows in batches. The full result set is never held in memory, so even multi-gigabyte exports stay within the job’s memory budget.
• Page-based JSON — The list endpoints (segments, campaigns, canvases, custom_events) page through results with a 0-based page parameter (100 items per page; 250 for events), stopping when a short page is returned.
• Cursor checkpointing — For campaigns/canvases, the loader tracks the maximum last_edited and checkpoints it after each batch; Zeotap persists it between runs.

Cloud-storage exports

If you have configured your own cloud-storage credentials (S3, Azure, or Google Cloud Storage) inside Braze, Braze writes segment exports directly to your bucket and the API response contains no download url. In that case the User Profiles stream cannot pull the data over the API — load it instead with the corresponding Zeotap cloud-storage loader (Amazon S3, Google Cloud Storage, or Azure Blob). The loader surfaces a clear error explaining this when it sees an empty url.

Rate Limits

Braze applies a default rate limit of 250,000 requests per hour to most export endpoints. Exceptions relevant to this loader:

• GET /events/list shares a limit of 1,000 requests per hour with a few other catalog endpoints.
• Only one user-profile export per segment may run at a time; a second concurrent export of the same segment returns 429.

The loader is designed to stay well within these limits — the list endpoints paginate rather than hammer, and the user export submits a single job per run.

Troubleshooting

Next Steps

• Create a model to transform raw Braze data — flatten custom_attributes JSON, or join campaigns to campaign KPIs
• Build audiences on engagement (total_revenue, custom-event recency) and sync them back to Braze or other tools