.svg)
Advanced Braze reporting strategies begin by matching each question to the report built for it. Report Builder compares campaigns and Canvases, Query Builder answers custom questions in SQL, funnel reports show where users drop off, and retention reports show who comes back. This guide covers when to use each, why their numbers differ, and the order we suggest for setting them up.
Key Takeaways
- Match each question to one report: Report Builder compares, Query Builder runs SQL, funnel reports show drop-off and retention reports show who returns.
- Query Builder needs the View PII permission as well as the dashboard report permissions, because its data can include customer data.
- Several gaps between reports are documented, including deleted variants, event ordering, time zones and soft bounce counting.
- Query Builder returns data from the past 60 days, and a report that runs longer than six minutes times out.
- We recommend choosing the retention event before launch and agreeing tags before building standing reports.
- Start with tags and one standing Report Builder report, then add funnel, retention and SQL views as named questions need them.
Which Braze reporting strategies are worth setting up?
Braze documents several reports, and each one is built for a different job. The table restates the documented purpose of the four that matter for advanced analysis, and adds our view on when each earns its place. You can find the full comparison in the Braze documentation on reports.
| Report | Documented purpose | When it earns its place (our view) |
|---|---|---|
| Report Builder | Compares results across several campaigns or Canvases in one view, with adjustable metrics and drilldowns | You need a standing comparison that someone reruns every month |
| Query Builder | Runs custom SQL against your Braze data in Snowflake, or starts from pre-built templates | A question needs a cut that the built-in views don't offer |
| Funnel reports | Analyses the journeys customers take after receiving a campaign or Canvas, including drop-off points | You want to know where users leave between message and conversion |
| Retention reports | Measures how well a campaign or Canvas re-engages users over time, up to 30 days | You suspect a message wins the click but not the return visit |
The right-hand column is our judgement, not documentation. It rests on the purposes in the middle column, and your own measurement plan should overrule it.
How do you choose between Report Builder and Query Builder?
Report Builder suits comparison across messages. Query Builder suits questions that the built-in metrics don't phrase for you. Both read Braze data, and Query Builder uses the same Snowflake SQL tables as SQL Segment Extensions and Snowflake Data Sharing.
Access differs. Report Builder needs workspace permissions to view and to edit dashboard reports. Query Builder needs those two as well as View PII, because the data it opens can include customer data.
Our suggestion is to decide who holds View PII before you decide who gets SQL training, because the permission decides who can open the data at all. This post describes the documented permission and does not settle any legal question about handling customer data.
How should you structure Report Builder reports?
Choose rows first, because your Rows selection impacts the metrics that you can view. Multivariate metrics, for example, appear only when you report on Canvases, or on campaigns with a Variant drilldown.
Tags make a report durable. You can add a Tags column that shows the tags applied to each campaign or Canvas. You can also set rules, so that campaigns or Canvases that meet your conditions are added to future runs automatically.
We recommend agreeing a tag naming convention before you build the first standing report. A rule-based report is only as clean as the tags behind it, and changing tags later changes which messages future runs include.
Check team access before you lean on rules. Saved reports can't be assigned to a team the way campaigns and Canvases can. Users with team-level View Dashboard Reports permission see only reports where every selected campaign and Canvas belongs to their teams, and reports that use automatic selection are hidden from them, because Braze can't verify team access for messages that may be added when the report runs.
Why do two Braze reports show different numbers?
Several mismatches trace to a documented difference in what each report counts. Record these as design facts in your measurement guide, and you won't need to chase them as errors.
| Comparison | Documented reason for the gap |
|---|---|
| Report Builder channel totals against a campaign breakdown | Statistics for deleted message variants are not displayed in a breakdown by campaign or Canvas, though channel-level totals include all statistics |
| Unique Recipients against Unique Impressions | Unique Recipients can be higher when a message variant was deleted after send |
| Canvas step analytics against a funnel report | Step analytics include broader engagement and conversions, while the funnel enforces event order and timing rules |
| Funnel conversions against standard conversions | Funnel reports convert a maximum of one time per user, even if the user performs the event more than once |
| Query Builder against the Email Channel Engagement page | Query Builder defaults to UTC, while the page follows your company's time zone |
| Query Builder soft bounces against a deduplicated count | Query Builder counts all occurrences of soft bounces without deduplication |
| One Query Builder run against the next | Results may change between runs, including within the same day, as new data arrives |
We suggest writing the reason next to each metric in your measurement guide. Then the next person to compare two screens has the answer written down.
What should you know before writing Query Builder SQL?
Query Builder returns data from the past 60 days. If you use Currents or Snowflake Data Sharing, you may be able to query up to two years of data, which is how long your data is retained in Snowflake.
The default time zone for querying Snowflake is Coordinated Universal Time. To line your results up with a screen that follows your company's time zone, convert the timestamp inside the query. The example below adapts the pattern in the documentation, so replace each placeholder and check the table and column names against the current Query Builder reference.
-- Adapted from the Query Builder documentation. Replace the placeholders.
SELECT
DATE_TRUNC('day', CONVERT_TIMEZONE('UTC', 'YOUR_TIME_ZONE', TO_TIMESTAMP(TIME))) AS send_date,
COUNT(ID) AS emails_sent
FROM USERS_MESSAGES_EMAIL_SEND_SHARED
WHERE CONVERT_TIMEZONE('UTC', 'YOUR_TIME_ZONE', TO_TIMESTAMP(TIME)) >= 'START_DATE'
AND CONVERT_TIMEZONE('UTC', 'YOUR_TIME_ZONE', TO_TIMESTAMP(TIME)) < 'END_DATE'
AND APP_GROUP_ID = 'YOUR_APP_GROUP_ID'
GROUP BY send_date
ORDER BY send_date;
Reports that take longer than six minutes to run will time out. Restricting your query to a specific time period helps you generate results quicker, so narrow the dates or the data before you reach for a bigger query.
Query history is retained for seven days, and older queries are removed automatically. Save any query you expect to reuse. Variables help here: teammates who are comfortable with SQL can create reports that less technical teammates can then use.
How do funnel reports differ from Canvas analytics?
A funnel report follows users through events in the order you set. A user leaves the funnel at the first step where they don't perform the next event in the exact sequence you configured. Canvas analytics count all conversions and engagement without an ordering constraint, which is why step counts can run higher for the same dates.
The date logic differs as well. A funnel report filters users by when they entered the Canvas, while Canvas analytics filter events by when they occurred. A funnel can look within the past six months and follow users for a window of up to 30 days.
Keep funnels short. The documentation says there isn't a hard limit on events, gives four to six as the working range, and warns that very long funnels can run slowly or time out.
Two coverage points matter before you plan around funnels. Funnel reports aren't available for API campaigns. They also don't track orphaned users: when an anonymous user later becomes identified through the changeUser() method, their Braze ID changes, and the funnel only tracks follow-up events that match the user ID at entry.
How do you read retention reports without fooling yourself?
Retention reports come in two forms. Rolling retention measures how many users come back and do the retention event on or after any of the days listed across the top of the report. Range retention measures how many users come back within each listed range of days.
Rolling figures can look strange. A user who completes the event several times is counted in multiple time frames, which could result in the retention rate exceeding 100%. The All Users row counts a user twice if they received the campaign in more than one cohort.
We recommend choosing the retention event before you launch the message, not after you see the data. You can change the event and run the report again, so your plan is the only record of what you meant to measure.
Once a report has run, it can't be re-run with the same retention event for 24 hours. For variant comparisons, Braze compares each variant's conversion rate against the control's with a statistical procedure called a Z Test, to calculate a confidence percentage.
Retention reports aren't available for API-triggered campaigns.
What does a worked example look like?
Take a hypothetical subscription app that sends a welcome Canvas with two variants and a control group. The team wants to know whether the second variant performs better, and whether any difference lasts. This is an illustration, not client work, and it uses no delivery data.
- In Report Builder, set Rows to Canvases and add the Tags column. Confirm that the welcome Canvas carries the tag your convention requires, so a rule-based report picks it up.
- Open the Canvas funnel report. Start from message receipt, add the two events that define a good first week, and compare each variant with the control group.
- Run a retention report on the same Canvas, using the retention event the team agreed before launch. Read it by variant, and check the confidence figure against control.
- If the team needs a cut that the built-in views don't offer, such as sends by day in the company time zone, write a short query with the time zone converted.
- Note in the measurement guide why the funnel and the Canvas step counts differ, so nobody reopens the question next month.
The point of the sequence is that each report answers one question, and none of them is asked to answer another report's question.
What goes wrong when teams build advanced reports?
These failure modes are our names for patterns the documentation makes possible. Each one links to a documented behaviour in the tables above.
| Failure mode | What happens | Prevention |
|---|---|---|
| The untagged backlog | A rule-based report pulls in messages nobody meant to compare | Agree the tag convention first, then build the rules |
| The mismatched window | Someone compares a funnel with Canvas step analytics for the same dates and concludes one is wrong | Record the documented reasons for the gap in the measurement guide |
| The late retention event | The retention event is chosen after the data is visible | Fix the event in the plan before launch |
| The expired link | A report download link stops working, because links expire after one hour | Generate the report again and download it within the hour |
| The forgotten recipient | An external partner misses a scheduled report, because external addresses must be entered manually each time you create a schedule | Consider adding regular external readers as company users with appropriate permissions |
| The lost query | Useful SQL disappears, because query history is retained for seven days | Save queries you expect to reuse |
What should you set up first?
Sequence matters more than coverage. Each step below makes the next one cheaper, and none of them needs a new tool.
- Agree the tag convention for campaigns and Canvases.
- Build one standing Report Builder report that uses rules and the Tags column.
- Decide who holds View PII before anyone writes SQL.
- Write the page that explains why the numbers differ.
- Add funnel and retention reports on the Canvases that carry the programme.
As a Braze implementation partner, CustomerIK recommends starting with tags and one standing Report Builder report, then adding funnel, retention and SQL views only when a named question needs them.
How does this connect to the rest of the programme?
Channel-level reporting is covered in Email Campaign Reporting: What to Track in Braze, How to Analyse Push Notification Performance in Braze and How to Measure In-App Message Engagement in Braze. For lifecycle measures, read Retention Metrics Every Marketer Should Track in Braze and Measuring Onboarding Success: Key Metrics in Braze.
If you send Braze data to other tools, Connecting Braze with External Analytics Platforms covers that route. If you want help with the reporting layer around these reports, CustomerIK's Marketing Analytics service covers BI layer design, attribution modelling and executive dashboards.
Frequently Asked Questions
1. Which Braze report should I start with?
Start with Report Builder. Its documented purpose is comparison across campaigns and Canvases, which suits a first standing report.
2. Does Query Builder need special permissions?
Yes, it needs the workspace permissions to view and to edit dashboard reports, and View PII, because the data can include customer data.
3. How long does Query Builder keep my query history?
Query history is retained for seven days, and older queries are removed automatically.
4. Can I use funnel and retention reports on API campaigns?
No, funnel reports aren't available for API campaigns, and retention reports aren't available for API-triggered campaigns.
5. Why does my rolling retention rate exceed 100%?
A user who completes the retention event several times is counted in multiple time frames, which could result in the retention rate exceeding 100%.
Sources
- Braze, Reports. Retrieved 31 Oct 2026.
- Braze, Report Builder. Retrieved 31 Oct 2026.
- Braze, Query Builder. Retrieved 31 Oct 2026.
- Braze, Funnel reports. Retrieved 31 Oct 2026.
- Braze, Retention reports. Retrieved 31 Oct 2026.
- Limits and behaviours in Braze documentation can change, so check the linked pages before you rely on them.
- Written by CustomerIK, a Braze implementation partner.
CustomerIK is a Braze implementation partner working across onboarding, technical integration, marketing operations and customer data management.
If you want your Braze reports matched to the questions your team actually asks, let's talk.
.svg)
