Custom Reports

Custom reports let you combine any metrics, dimensions, and filters to answer specific questions about your email performance, flows, contacts, and events. You can save reports, duplicate them, and organize them by visibility.

Creating a Report

To create a custom report, you need three things:

Data source -- where the data comes from
Metrics -- what you want to measure
Dimensions -- how you want to group the data

Data Sources

Source	What it measures
`email_logs`	Email delivery, opens, clicks, bounces
`flow_trips`	Flow trips started, completed, failed
`flows`	Flow-level performance aggregates
`contacts`	Contact growth and subscription status
`events`	Custom event volume and activity

Metrics

Metrics are the numbers in your report. Each metric has a field type:

Field	Description	Example
`count`	Total count of records	Emails Sent, New Contacts
`count_distinct`	Count of unique values	Unique Contacts
`rate`	Ratio of two values as a percentage	Open Rate = opened / delivered
`sum`	Sum of a numeric field	Total events
`avg`	Average of a numeric field	Average completion rate

For rate metrics, you specify a numerator and denominator:

json

{

"field": "rate",

"label": "Open Rate",

"numerator": "opened",

"denominator": "delivered"

}

Dimensions

Dimensions group your data. The most common dimension is date (with day, week, or month granularity), but you can also group by flow name, email status, tags, and more.

Dimension	Granularity options	Description
`date`	`day`, `week`, `month`	Time-series grouping
`flow_name`	--	Group by flow
`flow_status`	--	Group by draft, active, paused, archived
`email_status`	--	Group by delivery status
`tag`	--	Group by flow tag

Filters

Filters narrow the data before metrics are calculated.

Operator	Description	Example
`eq`	Equals	`status eq "delivered"`
`neq`	Not equals	`status neq "failed"`
`gt` / `gte`	Greater than (or equal)	`count gt 100`
`lt` / `lte`	Less than (or equal)	`bounce_rate lt 5`
`in`	In a list	`status in ["opened", "clicked"]`
`not_in`	Not in a list	`status not_in ["bounced"]`
`contains`	Contains substring	`flow_name contains "welcome"`

Chart Types

Type	Best for
`line`	Trends over time
`bar`	Comparing categories
`area`	Volume over time with emphasis on magnitude
`pie`	Distribution / proportion
`table`	Detailed data view

Field Discovery

Before building a report, you can discover all available metrics, dimensions, and filters. The field discovery endpoint returns fields organized by category (Email, Flow, Contact, Event), each with its type, data type, and supported operators.

Available field categories:

Category	Metrics	Dimensions	Filters
Email	Sent, Delivered, Opened, Clicked, Bounced, Open Rate, Click Rate, Bounce Rate	Date, Email Status	Email Status
Flow	Trips Started, Trips Completed, Trips Failed, Completion Rate, Emails Sent (via Flow)	Flow Name, Flow Status	Flow Name
Contact	Total Contacts, New Contacts, Subscribed, Unsubscribed	Date Created, Subscription Status	Subscription Status
Event	Total Events, Unique Contacts, Unique Event Types	Date, Event Name	Event Name, Event Source

Tip

Use the field discovery endpoint (GET /v1/reports/fields) in the report builder to see all available fields with their operators. This is the same data that powers the drag-and-drop builder in the dashboard.

Date Ranges

Every report supports date range filtering. You can use preset ranges or explicit dates.

Preset Ranges

Value	Period
`1d`	Last 24 hours
`7d`	Last 7 days
`30d`	Last 30 days (default)
`90d`	Last 90 days
`today`	Current day (midnight to now)
`yesterday`	Previous day (midnight to midnight)

Custom Dates

Pass from_date and to_date as ISO 8601 strings to override the preset range.

Period Comparison

Enable compare: true to see how the current period compares to the previous period of equal length. For example, if you view the last 30 days, comparison shows the 30 days before that. Each KPI will include a trend percentage showing the change.

Saving and Managing Reports

Visibility

Visibility	Who can see it
`private`	Only you
`workspace`	All workspace members with `analytics:read` permission

Duplicating a Report

Duplicate an existing report (including pre-built templates) to create an editable copy. The copy is always set to private visibility so you can customize it without affecting the original.

Deleting a Report

Deleting a report also removes any associated schedule and share link. This action cannot be undone.

Warning

Deleting a report removes its schedule and share link permanently. If other team members rely on a scheduled report, consider transferring ownership or changing visibility to workspace first.

Live Preview

The report builder includes a live preview mode. As you configure metrics, dimensions, and filters, you can execute the query without saving the report. This uses the ad-hoc query endpoint (POST /v1/reports/query) and returns the same KPIs, chart data, and table data as a saved report.

Caching

Report query results are cached in Redis for 5 minutes. This means:

Repeated views of the same report with the same date range return instantly
Changing the date range or filters triggers a fresh query
Shared report links benefit from the same cache

Note

The 5-minute cache means that very recent data (events ingested in the last few minutes) may not appear immediately in report results. Refresh the report after the cache expires to see the latest data.