Best Practices

Recommended setup

Join list + analytics entities

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.

Append the three KPI entities

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.

Set a specific start date

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.

Data refresh and scheduling

Daily refresh for KPIs and analytics

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.

Less frequent refresh for list and details entities

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.

Performance optimization

Scope your API key to only what you need

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.

Use BigQuery for nested canvas data

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.

Common pitfalls

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.

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

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