Pre-built Report Endpoints
Specialized analytical endpoints for funnel analysis, cohort retention, flow comparison, and flow group performance. These endpoints execute purpose-built queries that go beyond the generic report builder.
Endpoints
| Method | Path | Description |
|---|---|---|
POST | /v1/reports/funnel | Email or flow funnel analysis |
POST | /v1/reports/cohort | Cohort retention analysis |
POST | /v1/reports/compare-flows | Compare 2--4 flows side by side |
POST | /v1/reports/flow-groups | Flow metrics grouped by tags |
All endpoints require JWT authentication and analytics:read permission.
Funnel Analysis
Visualize the email delivery pipeline or a specific flow's conversion funnel.
bash
curl -X POST "https://synapse-api.pyrx.tech/v1/reports/funnel" \
-H "Authorization: Bearer eyJhbGciOiJS..." \
-H "Content-Type: application/json" \
-d '{
"funnel_type": "email",
"date_range": "30d"
}'
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
funnel_type | string | Yes | email or flow |
flow_id | UUID | Flow only | Required when funnel_type is flow |
date_range | string | No | Preset: 1d, 7d, 30d (default), 90d |
from_date | string | No | ISO 8601 start date |
to_date | string | No | ISO 8601 end date |
Email Funnel Response
json
{
"funnel_type": "email",
"steps": [
{ "label": "Sent", "count": 12450, "percentage": 100.0, "drop_off_rate": 0.0 },
{ "label": "Delivered", "count": 12301, "percentage": 98.8, "drop_off_rate": 1.2 },
{ "label": "Opened", "count": 4892, "percentage": 39.29, "drop_off_rate": 60.23 },
{ "label": "Clicked", "count": 1567, "percentage": 12.59, "drop_off_rate": 67.97 }
],
"total_entered": 12450,
"total_converted": 1567,
"overall_conversion_rate": 12.59,
"date_range": {
"from": "2026-03-19T10:00:00+00:00",
"to": "2026-04-18T10:00:00+00:00"
}
}
Flow Funnel Request
bash
curl -X POST "https://synapse-api.pyrx.tech/v1/reports/funnel" \
-H "Authorization: Bearer eyJhbGciOiJS..." \
-H "Content-Type: application/json" \
-d '{
"funnel_type": "flow",
"flow_id": "f1l2o3w4-i5d6-7890-abcd-ef1234567890",
"date_range": "30d"
}'
Flow Funnel Response
json
{
"funnel_type": "flow",
"steps": [
{ "label": "Entered", "count": 3200, "percentage": 100.0, "drop_off_rate": 0.0 },
{ "label": "Email Sent", "count": 3100, "percentage": 96.88, "drop_off_rate": 3.13 },
{ "label": "Delivered", "count": 3050, "percentage": 95.31, "drop_off_rate": 1.61 },
{ "label": "Opened", "count": 1280, "percentage": 40.0, "drop_off_rate": 58.03 },
{ "label": "Clicked", "count": 420, "percentage": 13.13, "drop_off_rate": 67.19 },
{ "label": "Completed", "count": 2890, "percentage": 90.31, "drop_off_rate": 0.0 }
],
"total_entered": 3200,
"total_converted": 2890,
"overall_conversion_rate": 90.31,
"date_range": {
"from": "2026-03-19T10:00:00+00:00",
"to": "2026-04-18T10:00:00+00:00"
}
}
Note
For flow funnels, "Completed" refers to contacts who finished all flow steps, not email clicks. A flow can have a high completion rate even if email engagement is lower, because not all flows are email-centric -- some include wait steps, conditions, or contact updates.
Funnel Step Fields
| Field | Type | Description |
|---|---|---|
label | string | Step name |
count | integer | Number of records at this step |
percentage | float | Percentage of total_entered |
drop_off_rate | float | Percentage lost from the previous step |
Cohort Retention
Group contacts by signup period and track engagement over subsequent periods.
bash
curl -X POST "https://synapse-api.pyrx.tech/v1/reports/cohort" \
-H "Authorization: Bearer eyJhbGciOiJS..." \
-H "Content-Type: application/json" \
-d '{
"granularity": "monthly",
"metric": "any_activity",
"periods": 6,
"date_range": "90d"
}'
Request Body
| Field | Type | Default | Description |
|---|---|---|---|
granularity | string | monthly | weekly or monthly |
metric | string | any_activity | Retention metric: email_opened, email_clicked, event_active, any_activity |
periods | integer | 6 | Number of periods to track (2--12) |
date_range | string | 90d | Preset date range for cohort selection |
from_date | string | ISO 8601 start date | |
to_date | string | ISO 8601 end date |
Retention Metrics
| Metric | Counts as "active" |
|---|---|
email_opened | Opened at least one email in the period |
email_clicked | Clicked at least one email link in the period |
event_active | Triggered at least one custom event in the period |
any_activity | Union of email opens and custom events |
Response
json
{
"granularity": "monthly",
"metric": "any_activity",
"period_labels": ["Month 0", "Month 1", "Month 2", "Month 3", "Month 4", "Month 5"],
"cohorts": [
{
"cohort_label": "Jan 2026",
"cohort_start": "2026-01-01",
"cohort_size": 450,
"retention": [85.0, 62.0, 48.5, 41.2, 38.0, 35.1],
"counts": [383, 279, 218, 185, 171, 158]
},
{
"cohort_label": "Feb 2026",
"cohort_start": "2026-02-01",
"cohort_size": 520,
"retention": [88.0, 65.0, 50.2, 43.1, 39.8, null],
"counts": [458, 338, 261, 224, 207, 0]
},
{
"cohort_label": "Mar 2026",
"cohort_start": "2026-03-01",
"cohort_size": 380,
"retention": [82.0, 58.0, 45.0, null, null, null],
"counts": [312, 220, 171, 0, 0, 0]
}
],
"total_contacts": 1350,
"average_retention": [85.0, 61.67, 47.9, 42.15, 38.9, 35.1]
}
Response Fields
| Field | Type | Description |
|---|---|---|
period_labels | string[] | Column headers for the retention table |
cohorts | array | One row per cohort |
cohorts[].cohort_label | string | Human-readable label (e.g., "Jan 2026" or "W5 2026") |
cohorts[].cohort_start | string | ISO date of the cohort period start |
cohorts[].cohort_size | integer | Number of contacts in this cohort |
cohorts[].retention | (float or null)[] | Retention percentage per period (null = future period) |
cohorts[].counts | integer[] | Active contact count per period |
total_contacts | integer | Sum of all cohort sizes |
average_retention | (float or null)[] | Average retention across all cohorts per period |
Flow Comparison
Compare 2 to 4 flows side by side. The response identifies the "winner" (highest completion rate).
bash
curl -X POST "https://synapse-api.pyrx.tech/v1/reports/compare-flows" \
-H "Authorization: Bearer eyJhbGciOiJS..." \
-H "Content-Type: application/json" \
-d '{
"flow_ids": [
"f1l2o3w4-aaaa-7890-abcd-ef1234567890",
"f1l2o3w4-bbbb-7890-abcd-ef1234567890"
],
"date_range": "30d"
}'
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
flow_ids | UUID[] | Yes | 2--4 flow IDs to compare |
date_range | string | No | Preset: 1d, 7d, 30d (default), 90d |
from_date | string | No | ISO 8601 start date |
to_date | string | No | ISO 8601 end date |
Response
json
{
"flows": [
{
"flow_id": "f1l2o3w4-aaaa-7890-abcd-ef1234567890",
"flow_name": "Welcome Series v1",
"flow_status": "active",
"tags": ["onboarding"],
"total_trips": 1500,
"completed": 1350,
"failed": 12,
"completion_rate": 90.0,
"emails_sent": 4500,
"open_rate": 42.5,
"click_rate": 15.2
},
{
"flow_id": "f1l2o3w4-bbbb-7890-abcd-ef1234567890",
"flow_name": "Welcome Series v2",
"flow_status": "active",
"tags": ["onboarding"],
"total_trips": 1480,
"completed": 1410,
"failed": 8,
"completion_rate": 95.27,
"emails_sent": 2960,
"open_rate": 48.1,
"click_rate": 18.7
}
],
"winner": "f1l2o3w4-bbbb-7890-abcd-ef1234567890",
"date_range": {
"from": "2026-03-19T10:00:00+00:00",
"to": "2026-04-18T10:00:00+00:00"
}
}
Per-Flow Metrics
| Field | Type | Description |
|---|---|---|
flow_id | UUID | Flow identifier |
flow_name | string | Flow name |
flow_status | string | Current status (draft, active, paused, archived) |
tags | string[] | Flow tags |
total_trips | integer | Trips started in the period |
completed | integer | Trips completed |
failed | integer | Trips failed |
completion_rate | float | completed / total_trips * 100 |
emails_sent | integer | Emails sent through this flow |
open_rate | float | Emails opened / emails sent * 100 |
click_rate | float | Emails clicked / emails sent * 100 |
Tip
The winner field is the flow_id with the highest completion rate among flows that have at least one trip. If no flows have trips, winner is null.
Flow Group Performance
Aggregate flow metrics by tag. Useful for comparing categories of flows (e.g., "onboarding" vs "retention" vs "transactional").
bash
curl -X POST "https://synapse-api.pyrx.tech/v1/reports/flow-groups" \
-H "Authorization: Bearer eyJhbGciOiJS..." \
-H "Content-Type: application/json" \
-d '{
"tags": ["onboarding", "retention"],
"date_range": "30d"
}'
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
tags | string[] | No | Filter to specific tags. null or omitted = all tags. |
date_range | string | No | Preset: 1d, 7d, 30d (default), 90d |
from_date | string | No | ISO 8601 start date |
to_date | string | No | ISO 8601 end date |
Response
json
{
"kpis": [
{ "label": "Flow Groups", "value": 2 },
{ "label": "Total Flows", "value": 8 },
{ "label": "Total Trips", "value": 5200 },
{ "label": "Avg Completion", "value": 87.5, "subtitle": "4550 completed" },
{ "label": "Open Rate", "value": 41.2, "subtitle": "3890 opened" }
],
"chart_data": [
{
"dimensions": { "tag": "onboarding" },
"metrics": {
"flows": 3,
"total_trips": 3200,
"completed": 2890,
"failed": 24,
"completion_rate": 90.31,
"emails_sent": 9600,
"open_rate": 45.2,
"click_rate": 16.8
}
},
{
"dimensions": { "tag": "retention" },
"metrics": {
"flows": 5,
"total_trips": 2000,
"completed": 1660,
"failed": 40,
"completion_rate": 83.0,
"emails_sent": 6000,
"open_rate": 35.8,
"click_rate": 12.1
}
}
],
"table_data": [
{
"tag": "onboarding",
"flows": 3,
"total_trips": 3200,
"completed": 2890,
"failed": 24,
"completion_rate": 90.31,
"emails_sent": 9600,
"open_rate": 45.2,
"click_rate": 16.8
},
{
"tag": "retention",
"flows": 5,
"total_trips": 2000,
"completed": 1660,
"failed": 40,
"completion_rate": 83.0,
"emails_sent": 6000,
"open_rate": 35.8,
"click_rate": 12.1
}
],
"date_range": {
"from": "2026-03-19T10:00:00+00:00",
"to": "2026-04-18T10:00:00+00:00",
"range": "30d"
}
}
Note
A single flow with multiple tags appears in each tag group it belongs to. This means metrics can appear in multiple groups -- the totals across groups may exceed the actual totals if flows have overlapping tags.
Flows without tags are grouped under "untagged". If no flows match the specified tags, the response returns an "untagged" group containing all flows.