> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/email/braze.md).

# Braze

Connect Braze campaigns, canvases, and segments to Google Sheets or BigQuery via Coupler.io — automate marketing performance reporting.

Braze is a customer engagement platform that helps marketing teams orchestrate campaigns, canvases, and messaging across email, push, SMS, and in-app channels. It centralizes user behavior data, segmentation, and performance analytics in one place. Connecting Braze to Coupler.io lets you pull that data into your reporting tools without manual exports.

**Why connect Braze to Coupler.io?**

* Sync campaign and canvas performance data automatically to Google Sheets, BigQuery, Looker Studio, or AI tools like ChatGPT and Gemini
* Combine Braze data with other sources (CRM, revenue, ad spend) using Join or Append transformations
* Track KPIs like daily new users, active users, and uninstalls over time in a centralized dashboard
* Keep historical snapshots of segment sizes and engagement metrics without manual downloads

## Prerequisites

* A Braze account with access to the **Developer Console**
* An API key with read permissions for the entities you want to sync (campaigns, canvases, segments, events, cards, KPIs)
* Your Braze **REST endpoint URL** (varies by region, e.g., `https://rest.iad-01.braze.com`)

## Quick start

{% hint style="success" %}
Start with **Campaigns analytics** or **Canvases analytics** — these give you the richest performance data right away and work well as a foundation for dashboards.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Create a Braze API key.** In Braze, go to **Settings → Developer Console → API Keys** and create a new key. Grant it read access to the data entities you need (campaigns, canvases, segments, events, cards, KPIs). Copy the key.
{% endstep %}

{% step %}
**Add Braze as a source in Coupler.io.** In your Coupler.io workspace, create a new data flow and select **Braze** as the source. Paste your API key and enter your Braze REST endpoint URL.
{% endstep %}

{% step %}
**Select an entity.** Choose which entity to pull — for example, Campaigns analytics, Canvases analytics, or Segments. Set a start date using the date picker to define how far back to sync historical data.
{% endstep %}

{% step %}
**Choose a destination.** Pick where you want your data to land — Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination like Claude, ChatGPT, or Gemini.
{% endstep %}

{% step %}
**Run the data flow.** Click **Run** to execute a manual sync. Once it completes successfully, your data will appear in the destination and you'll be able to set up a schedule.
{% endstep %}
{% endstepper %}

## Available entities

| Entity                   | What it contains                                 |
| ------------------------ | ------------------------------------------------ |
| Campaigns                | List of all campaigns with metadata              |
| Campaigns analytics      | Performance metrics per campaign                 |
| Campaigns details        | Detailed configuration and settings per campaign |
| Canvases                 | List of all canvases                             |
| Canvases analytics       | Performance metrics per canvas                   |
| Canvases details         | Step-level canvas configuration                  |
| Events                   | Custom event list                                |
| Events analytics         | Event occurrence counts over time                |
| KPI daily new users      | New user registrations per day                   |
| KPI daily active users   | Daily active user counts                         |
| KPI daily app uninstalls | App uninstall counts per day                     |
| Cards                    | Content card list                                |
| Cards analytics          | Impressions, clicks, and dismissals per card     |
| Segments                 | List of all segments                             |
| Segments analytics       | Segment size over time                           |
| Segments details         | Segment filter logic and configuration           |

## Braze data overview

Braze exposes data across campaigns, canvases, segments, events, content cards, and platform-level KPIs. Each entity type has a list/metadata variant, an analytics variant (time-series performance metrics), and in some cases a details variant (configuration and structure).

## Entity types

| Entity group | List | Analytics          | Details |
| ------------ | ---- | ------------------ | ------- |
| Campaigns    | ✅    | ✅                  | ✅       |
| Canvases     | ✅    | ✅                  | ✅       |
| Events       | ✅    | ✅                  | —       |
| Cards        | ✅    | ✅                  | —       |
| Segments     | ✅    | ✅                  | ✅       |
| KPIs         | —    | ✅ (3 KPI entities) | —       |

## Campaigns

#### Campaigns — list fields

| Field        | Description                              |
| ------------ | ---------------------------------------- |
| id           | Unique campaign identifier               |
| name         | Campaign name                            |
| is\_active   | Whether the campaign is currently active |
| last\_edited | Timestamp of last edit                   |
| tags         | Tags applied to the campaign             |

#### Campaigns analytics fields

| Metric       | Description                            |
| ------------ | -------------------------------------- |
| sends        | Total messages sent                    |
| deliveries   | Successfully delivered messages        |
| opens        | Total opens (unique and total)         |
| clicks       | Total clicks                           |
| bounces      | Hard and soft bounces                  |
| unsubscribes | Unsubscribe events                     |
| conversions  | Conversion events tied to the campaign |
| revenue      | Revenue attributed to the campaign     |

## Canvases

#### Canvases analytics fields

| Metric      | Description                                |
| ----------- | ------------------------------------------ |
| entries     | Users who entered the canvas               |
| revenue     | Revenue attributed to the canvas           |
| exits       | Users who exited                           |
| conversions | Conversion events per canvas               |
| steps\_data | Per-step breakdown of sends, opens, clicks |

## Events

#### Events analytics fields

| Field       | Description                                |
| ----------- | ------------------------------------------ |
| event\_name | Name of the custom event                   |
| total       | Total event occurrences in the time window |
| date        | Date of the data point                     |

## KPIs

#### KPI fields (all three KPI entities)

| Field      | Description                                  |
| ---------- | -------------------------------------------- |
| date       | Date of the data point                       |
| new\_users | New user registrations (KPI daily new users) |
| dau        | Daily active users (KPI daily active users)  |
| uninstalls | App uninstalls (KPI daily app uninstalls)    |

## Cards

#### Cards analytics fields

| Metric      | Description                            |
| ----------- | -------------------------------------- |
| impressions | Number of times the card was viewed    |
| clicks      | Number of clicks on the card           |
| dismissals  | Number of times the card was dismissed |
| enrollments | Users who received the card            |

## Segments

#### Segments analytics fields

| Field | Description                                 |
| ----- | ------------------------------------------- |
| date  | Date of the data point                      |
| size  | Number of users in the segment on that date |

#### Segments details fields

| Field          | Description                       |
| -------------- | --------------------------------- |
| id             | Segment identifier                |
| name           | Segment name                      |
| creation\_time | When the segment was created      |
| filters        | Filter logic defining the segment |

## Common metric combinations

* **Campaign deliverability**: `sends` + `deliveries` + `bounces` to monitor inbox placement health
* **Engagement funnel**: `opens` + `clicks` + `unsubscribes` + `conversions` per campaign
* **Growth KPIs**: Join `kpi_daily_new_users` + `kpi_daily_active_users` + `kpi_daily_app_uninstalls` into a single time-series table using Append
* **Segment size trends**: `segments_analytics` over time to track audience growth or churn within key segments
* **Canvas vs. campaign ROI**: Join `campaigns_analytics` and `canvases_analytics` on date to compare revenue attribution across both channel types

## Use cases by role

{% tabs %}
{% tab title="Marketers" %}

* Pull `campaigns_analytics` and `canvases_analytics` into Google Sheets or Looker Studio to build live performance dashboards without manual exports
* Use `segments_analytics` to track how audience sizes change week over week — useful for monitoring churn or growth in key cohorts
* Send campaign performance snapshots to ChatGPT or Claude for AI-assisted analysis and copy recommendations
  {% endtab %}

{% tab title="Growth & Product" %}

* Combine `kpi_daily_new_users`, `kpi_daily_active_users`, and `kpi_daily_app_uninstalls` using Append to build a unified growth KPI table in BigQuery
* Track `events_analytics` over time to measure feature adoption through custom event counts
* Join segment data with external user data in BigQuery to identify which segments drive the most revenue
  {% endtab %}

{% tab title="Data & Analytics" %}

* Load all Braze entities into BigQuery to build a centralized marketing data warehouse
* Use Aggregate transformation to summarize campaign performance by tag, channel, or time period
* Join `campaigns` (metadata) with `campaigns_analytics` (metrics) using the campaign ID to build enriched reporting tables
  {% endtab %}
  {% endtabs %}

## Platform-specific notes

* Braze REST endpoints vary by region — make sure you use the correct endpoint for your account (e.g., `rest.iad-01.braze.com` vs. `rest.fra-01.braze.com`)
* Analytics entities return time-series data; the granularity is daily
* The `start_date` parameter controls how far back data is fetched — if left unset, Braze may return a limited default window
* `campaigns_details` and `canvases_details` return structural/configuration data, not performance metrics — useful for auditing or documentation, not trend analysis
* Segment filter logic in `segments_details` is returned as a nested JSON structure that may need flattening depending on your destination

## Braze common issues

### Connection issues

<details>

<summary>Authentication failed — invalid API key</summary>

Double-check that you copied the full API key from Braze without any trailing spaces. Also confirm the key is active — in Braze, go to **Settings → Developer Console → API Keys** and verify the key hasn't been deleted or rotated. If your organization rotates keys regularly, you may need to generate a new one and update it in your Coupler.io data flow.

</details>

<details>

<summary>Wrong REST endpoint — connection times out or returns 404</summary>

Braze hosts data on region-specific endpoints. Using the wrong URL (e.g., `rest.iad-01.braze.com` when your account is on `rest.fra-01.braze.com`) will cause the connection to fail. Find your correct endpoint in Braze under **Settings → Developer Console** — it's shown at the top of the page.

</details>

### Missing data

<details>

<summary>Analytics entities return no rows or fewer rows than expected</summary>

This usually means the `start_date` is set too far in the future, or no data exists for the selected time window. Use the date picker to set a start date that covers the period you need. Also verify that the campaigns, canvases, or segments you're expecting have actually sent messages or logged activity during that period.

</details>

<details>

<summary>Certain campaigns or canvases are missing from the list entity</summary>

Braze's API only returns items the API key has permission to access. If you recently created a restricted API key, confirm it has read access to campaigns and canvases. Archived items may also be excluded from list responses depending on your Braze plan.

</details>

### Permission errors

<details>

<summary>403 Forbidden when fetching a specific entity</summary>

Your API key may not have the required permission scope for that entity. In Braze, open the API key and check which endpoints are whitelisted. For example, to pull segments you need access to `/segments/list` and `/segments/data_series`. Add the missing endpoint permissions and re-run the data flow.

{% hint style="warning" %}
Braze allows you to restrict API keys to specific endpoints. If you're using a tightly scoped key, you'll need to explicitly allow each endpoint that Coupler.io calls.
{% endhint %}

</details>

### Data discrepancies

<details>

<summary>Numbers in Coupler.io don't match the Braze dashboard</summary>

Braze dashboards often apply timezone adjustments and attribution windows that differ from raw API responses. The API returns data in UTC by default. If your Braze account is configured for a different timezone, totals may not align directly. Check your Braze workspace timezone settings and account for any attribution window differences when comparing numbers.

</details>

<details>

<summary>Canvas step-level metrics look aggregated rather than per-step</summary>

The `canvases_analytics` entity returns a `steps_data` field that contains nested per-step data. Depending on your destination, this nested structure may appear collapsed or as a single JSON string. You may need to use BigQuery or a transformation step to unnest this field for per-step reporting.

</details>

### Rate limits

<details>

<summary>Sync fails partway through with a rate limit error</summary>

Braze enforces rate limits per API key — typically 250,000 requests per hour for most endpoints, but lower for some analytics endpoints. If you're syncing many entities in the same data flow or running very large date ranges, you may hit these limits. Try splitting entities into separate data flows or narrowing the date range per run.

{% hint style="warning" %}
Analytics endpoints like `campaigns/data_series` and `canvases/data_series` have stricter rate limits than list endpoints. Avoid running multiple analytics entities simultaneously if you're on a high-volume plan.
{% endhint %}

</details>

## Braze FAQ

<details>

<summary>Which Braze entities should I start with?</summary>

If you're building a marketing performance dashboard, start with **Campaigns analytics** and **Canvases analytics** — these have the most actionable metrics (sends, opens, clicks, conversions, revenue). Add **KPI daily new users** and **KPI daily active users** if you also want growth metrics in the same workspace.

</details>

<details>

<summary>What's the difference between the list, analytics, and details entities?</summary>

* **List entities** (Campaigns, Canvases, Segments, Events, Cards) return metadata — names, IDs, tags, active status.
* **Analytics entities** return time-series performance metrics — daily breakdowns of sends, opens, clicks, segment sizes, event counts, etc.
* **Details entities** return structural/configuration data — the actual setup of a campaign, the step logic of a canvas, or the filter rules of a segment.

For reporting, you'll mostly use analytics entities. Use list entities to enrich analytics data with human-readable names via a Join transformation.

</details>

<details>

<summary>How do I find my Braze REST endpoint URL?</summary>

In Braze, go to **Settings → Developer Console**. Your REST endpoint is displayed at the top of the page and looks like `https://rest.iad-01.braze.com`. The number and prefix change based on your region (US, EU, AU, etc.). Use exactly this URL when configuring your Coupler.io data flow.

</details>

<details>

<summary>Can I sync data from multiple Braze workspaces?</summary>

Yes. Each Braze workspace has its own API key and REST endpoint. Create a separate source connection in Coupler.io for each workspace, then use the **Append** transformation to combine data from multiple workspaces into a single destination table. This is useful for agencies or businesses that manage multiple brands under separate Braze workspaces.

</details>

<details>

<summary>Why does my analytics data look different from what I see in the Braze dashboard?</summary>

Braze's API returns data in UTC, while the dashboard may display data adjusted to your workspace timezone. Attribution windows (how conversions are counted) can also differ. When comparing API data to the dashboard, account for these timezone and attribution differences. See the Data Discrepancies section for more detail.

{% hint style="info" %}
For a full list of known discrepancy causes, see [Common Issues](#braze-common-issues).
{% endhint %}

</details>

<details>

<summary>Can I use Braze data with AI tools through Coupler.io?</summary>

Yes. Coupler.io supports AI destinations including ChatGPT, Claude, Gemini, Cursor, Perplexity, and OpenClaw. You can route campaign performance data or KPI trends directly to these tools for automated analysis, anomaly detection, or content recommendations.

</details>

<details>

<summary>How far back can I pull historical data?</summary>

Use the date picker in the source settings to set a start date. Braze's API supports historical analytics data, but very long date ranges (e.g., 2+ years of daily data across many campaigns) can result in slow syncs or rate limit errors. For initial historical loads, consider splitting the range across a few manual runs before switching to incremental daily updates.

{% hint style="info" %}
For tips on managing large syncs efficiently, see [Best Practices](https://docs.coupler.io/sources/category/email/braze/best-practices.md).
{% endhint %}

</details>

<details>

<summary>What permissions does my Braze API key need?</summary>

Your API key needs read access to the specific endpoints Coupler.io calls. At minimum:

* `/campaigns/list` and `/campaigns/data_series` for campaign data
* `/canvas/list` and `/canvas/data_series` for canvas data
* `/segments/list` and `/segments/data_series` for segment data
* `/events/list` and `/events/data_series` for event data
* `/feed/list` and `/feed/data_series` for cards data
* `/kpi/new_users/data_series`, `/kpi/dau/data_series`, `/kpi/uninstalls/data_series` for KPIs

If you get a 403 error on a specific entity, that endpoint permission is likely missing from your key.

{% hint style="info" %}
See [Common Issues — Permission Errors](#braze-common-issues) for troubleshooting steps.
{% endhint %}

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/email/braze.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
