# 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 %}