/insights API Endpoint

The /insights endpoint analyzes all available attribution data and calculates cohort-level metrics to help evaluate both overall marketing performance and specific campaign effectiveness.

Use this API to:

Measure average time and number of sessions to convert
Evaluate session duration patterns for converting and drop-off behavior
Benchmark conversion rates across all users and converters
Identify which traffic channels drive the most converting users
Understand each channel’s role: first touch, assist, conversion, or post-conversion

Request


1POST /api/v1/insights  
2Authentication: YOUR_API_KEY  
3Content-Type: application/json

Query Parameters

These filters define which users are eligible for analysis. Users that have one session that matches the filters will be included in the analytics.

All filters use strict matching: string values are case-sensitive and must match exactly as stored (e.g., google.com ≠ Google.com).

Filter logic is AND-based: only users with at least one session matching all filters simultaneously will be analyzed.

Important:

The /insights API analyzes complete user journeys — but users are only included if at least one of their sessions matches the provided filters. This enables powerful segmentation (e.g. “users who clicked a campaign but converted later”).

Parameter	Type	Description
start_date	string (ISO 8601 or YYYY-MM-DD)	Start of the time window to analyze. Only conversions that start on or after this date are included. Example: 2025-07-01T23:59:59Z or 2025-07-01. Defaults to 30 days prior to the current UTC time.
end_date	string (ISO 8601 or YYYY-MM-DD)	End of the time window to analyze. Only conversions before or on this date are included. Example: 2025-07-31T23:59:59Z or 2025-07-31. Defaults to 30 days prior to the current UTC time.
conversion_page	string	Filter to conversions that occurred on a specific page URL. Must be the exact URL tracked during conversion.
meta_type	string	Filter by the type of conversion. Supports values like hubspot_form, custom, or html_form.
meta_id	string	Filter by a specific conversion ID (e.g., a HubSpot form ID or custom event ID).
source	string	Filter by traffic source (e.g., google.com, facebook.com, example.com) Matches against the full primary domain. If utm_source is present, it overrides the derived source.
medium	string	Filter by traffic medium (e.g., cpc, organic). If utm_medium is present, it overrides the derived medium.
campaign	string	Filter by UTM campaign name.
content	string	Filter by UTM content value.
term	string	Filter by UTM term value.
landing_page	string	Filter by the landing page URL (e.g., https://example.com/pricing, https://store.example.com/products/xyz).
touch_scope	enum	Filter users by session type: • any (default) • first • converting • assist • after any – include all sessions (default) first – only the user's first session converting – sessions where a conversion occurred assist – sessions between first and converting session after - sessions after the first converting session

Example: Filter by Time Frame


1POST /api/v1/insights
2Authentication: YOUR_API_KEY
3Content-Type: application/json
4
5{
6  "start_date": "2025-07-15",
7  "end_date": "2025-07-30",
8}

Returns aggregated metrics from users who had at least one session during July 2025.

Example: Filter by Touch Scope


1POST /api/v1/insights
2Authentication: YOUR_API_KEY
3Content-Type: application/json
4
5{
6  "start_date": "2025-07-01",
7  "end_date": "2025-07-31",
8  "source": "google.com",
9  "touch_scope": "converting"
10}

Returns insights for users who came from Google and converted in the same session with-in July 2025. All sessions from these users are analyzed

Response


1{
2  "overall_metrics": {
3    "user_summary": {
4      "total_users": 1280,
5      "total_converted_users": 420,
6      "conversion_rate": "32.81%",
7      "avg_sessions_per_user": 2.7,
8      "avg_sessions_per_converted_user": 3.5
9    },
10    "session_summary": {
11      "total_sessions": 3470,
12      "total_converting_sessions": 423,
13      "total_drop_off_sessions": 1298,
14      "avg_session_duration_seconds": 132.7,
15      "avg_converting_session_duration": 142.3,
16      "avg_drop_off_session_duration": 101.2,
17      "median_converting_session_duration": 118,
18      "median_drop_off_session_duration": 93
19    },
20    "conversion_summary": {
21      "avg_time_to_convert": 90231.3,
22      "median_time_to_convert": 60800,
23      "conversion_timeline_bins": {
24        "counts": {
25          "0-1 days": 142,
26          "1-3 days": 102,
27          "3-7 days": 115,
28          "7+ days": 61
29        },
30        "percentages": {
31          "0-1 days": 33.57,
32          "1-3 days": 24.17,
33          "3-7 days": 27.2,
34          "7+ days": 14.44
35        }
36      }
37    },
38    "channels": [
39      {
40        "channel": "organic/google.com",
41        "total_sessions": 1293,
42        "total_users": 991,
43        "converting_users_first_touch": 320,
44        "converting_users_assisting_touch": 78,
45        "converting_users_converting_touch": 102,
46        "converting_users_after_touch": 27,
47        "session_influence": "37.26%",
48        "conversion_influence": "45.23%",
49        "attributed_to_conversion": 190,
50        "conversion_rate": "19.18%"
51      }
52    ]
53  }
54}

user_summary

Conversion metrics about users who had a single session match the filters.

total_users

Number of unique users with at least one qualifying session. Use this to understand the reach of your campaign or segment.

total_converted_users

Number of users who completed at least one conversion. Highlights total conversion impact within the selected cohort.

conversion_rate

Percentage of users who converted (converted users ÷ total users). A core benchmark for performance across audiences or campaigns.

avg_sessions_per_user

Average number of sessions per user across all included users. Indicates how often users return before converting or exiting.

avg_sessions_per_converted_user

Average number of sessions for users who converted. Helps evaluate the typical effort or touch count required to convert.

session_summary

All metrics included in session_summary are based on sessions that explicitly match all filters. These metrics do not include other sessions inside user timelines.

total_sessions

Number of sessions matching all filters. Represents the full session volume under analysis.

total_converting_sessions

Sessions that included a conversion event. Used to assess how many of the filtered sessions resulted in a conversion.

total_drop_off_sessions

Sessions that ended without a conversion but included an exit timestamp. Useful for identifying drop-off behavior.

avg_sessions_duration_seconds

Average session length (based on exit timestamp). Indicates how long users typically stay active.

avg_converting_session_duration

Average time from session start to conversion. Helps evaluate how fast converting users take action within a session.

avg_drop_off_sessions_duration

Average time from session start to exit for non-converting sessions. Reveals whether drop-off sessions are quick exits or slow fails.

median_converting_sessions_duration

Median session duration for converting sessions. Removes outliers to show typical converter engagement time.

median_drop_off_sessions_duration

Median duration of non-converting sessions (with exit timestamp). Used to identify typical behavior of users who leave without converting.

conversion_summary

Time-to-conversion metrics for users who completed at least one conversion and had a session matching the filters..

avg_time_to_convert

Average number of seconds between a user's first touch and their first conversion. Useful for understanding typical conversion lag.

median_time_to_convert

Median time from first touch to conversion. Removes outliers to show the most common conversion timeline.

conversion_timeline_bins

Buckets converted users by how long they took to convert:

0–1 days
1–3 days
3–7 days
7+ days

Returns both:

counts: raw user totals in each bin
percentages: percent of total converted users in each bin

Helps segment fast vs. delayed converters and track sales cycle speed.

channels

Breakdown of traffic sources (medium/source pairs) touched by users with at least one qualifying session. Helps evaluate how each channel contributes to conversion performance across the full journey.

Each object represents a specific channel (e.g., "organic/google.com"), with the following metrics:

Channels are returned in descending order by total_sessions + total_users

channel

A combined medium/source string (e.g., "email/newsletter", "paid/google.com").

total_sessions

Number of sessions attributed to this channel (across all users).

total_users

Unique users who touched this channel at any point in their journey.

converting_users_first_touch

Number of users who first landed on this channel and eventually converted. Helpful for identifying channels that drive strong first-touch performance.

converting_users_assisting_touch

Users who visited this channel between their first session and their conversion session. Use this to identify influential mid-funnel drivers.

converting_users_converting_touch

Users who converted in a session that came directly from this channel. A good proxy for direct-response performance.

converting_users_after_touch

Users who touched this channel after converting. Useful for evaluating post-conversion retargeting, onboarding, or re-engagement efforts.

session_influence

Percentage of all sessions attributed to this channel. Measures this channel’s share of total site activity.

conversion_influence

Percentage of converted users who touched this channel before converting. Highlights how broadly this channel contributes to conversions.

attributed_to_conversion

Number of users who visited this channel before their first conversion.

conversion_rate

Percent of users who touched this channel before conversion, out of all users who visited the channel. Evaluates this channel’s overall conversion effectiveness (excluding post-conversion sessions).

No Results

If no qualifying conversions are found, the API will return:


1{ "message": "No page data found for the given parameters." }

This is not an error; it simply indicates no users matched the filters.

← /pages API Endpoint