> 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/best-practices.md).

# Best Practices

## Recommended setup

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Join list + analytics entities</strong></td><td>The list entities (e.g., Campaigns) give you names and metadata; the analytics entities give you metrics. Join them on the campaign or canvas ID in Coupler.io to build enriched tables that include both the campaign name and its performance numbers.</td></tr><tr><td><strong>Append the three KPI entities</strong></td><td>KPI daily new users, KPI daily active users, and KPI daily app uninstalls share the same date-based structure. Use Append transformation to combine them into one unified growth KPI table — easier to chart and compare over time.</td></tr><tr><td><strong>Set a specific start date</strong></td><td>Always use the date picker to set a start date that matches your reporting needs. Leaving it open-ended can result in unnecessarily large syncs or incomplete historical coverage depending on Braze's default API window.</td></tr></tbody></table>

## Data refresh and scheduling

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Daily refresh for KPIs and analytics</strong></td><td>KPI entities and analytics entities update daily in Braze. A once-per-day schedule (e.g., early morning) is sufficient and avoids unnecessary API calls throughout the day.</td></tr><tr><td><strong>Less frequent refresh for list and details entities</strong></td><td>Campaigns, Canvases, and Segments lists don't change as frequently as analytics data. A daily or even weekly schedule is usually enough for these — save your sync frequency budget for the analytics entities that matter for live dashboards.</td></tr></tbody></table>

## Performance optimization

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Scope your API key to only what you need</strong></td><td>Create separate API keys for different data flows if you're syncing different entity groups. This makes it easier to manage permissions and troubleshoot rate limit issues — you'll know exactly which key is hitting which endpoints.</td></tr><tr><td><strong>Use BigQuery for nested canvas data</strong></td><td>Canvas analytics include nested step-level data that doesn't flatten cleanly in spreadsheets. Route canvases_analytics to BigQuery if you need per-step metrics — it handles nested JSON natively and lets you query step performance with SQL.</td></tr></tbody></table>

## Common pitfalls

{% hint style="danger" %}
**Don't use the wrong REST endpoint.** Braze is region-specific — using the default `iad-01` endpoint when your workspace is in the EU or another region will silently fail or return no data. Always confirm your endpoint in the Braze Developer Console before setting up a data flow.
{% endhint %}

{% columns %}
{% column %}
**Do**

* Use the correct region-specific REST endpoint
* Scope API key permissions to only the endpoints you're syncing
* Join list entities with analytics entities for richer reports
* Test with a short date range on the first manual run
  {% endcolumn %}

{% column %}
**Don't**

* Pull details entities (campaigns\_details, canvases\_details) on a high-frequency schedule — they're config data, not metrics
* Expect Braze API numbers to match the dashboard exactly without accounting for timezone and attribution window differences
* Use a single API key for all data flows if you're syncing many entities — it makes rate limit troubleshooting harder
  {% endcolumn %}
  {% endcolumns %}


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.