/sessions API Endpoint

The /sessions endpoint returns individual user sessions within a specified timeframe, including attribution data (like UTM parameters), landing page URLs, and any associated conversion or exit events.

This API is ideal for analyzing session-level behavior, validating attribution accuracy, and powering dashboards that require detailed user journey data. It also supports QA of marketing funnels, analysis of drop-off trends, and reconciliation with other tracking systems.

By exposing raw session records enriched with conversion and exit details, the /sessions endpoint gives you a clear view into how users arrive, engage, and convert (or leave) — making it easy to:

• Identify which marketing efforts drive engagement or abandonment
• Surface top landing pages and drop-off points across campaigns
• Validate attribution logic and funnel performance at the session level
• Cross-check against CRM or analytics platforms for data consistency

Request

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

Query Parameters

These parameters allow you to filter the sessions returned by the query.

All filters are optional and use exact match logic. You can combine multiple filters to narrow results; all filters are applied using AND conditions.

Example: Filter by Time Window

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

Returns all sessions between July 15th, 2025 and July 30th, 2025

Example: Filter by Specific Campaign

Copy
1POST /api/v1/sessions
2Authentication: YOUR_API_KEY
3Content-Type: application/json
4
5{
6  "campaign": "summer_sale",
7  "source": "facebook",
8  "term": "bathing suits"
9}

Returns sessions where the UTM campaign is summer_sale, the traffic source is facebook, and the UTM term is bathing suits.

Response

Copy
1{
2  "records": [
3    {
4      "timestamp": "2025-03-03T10:15:00Z",
5      "source": "organic",
6      "medium": "organic",
7      "campaign": "campaign2",
8      "content": "none",
9      "term": "winter coats",
10      "landing_page": "https://testdomain.com/winter"
11    },
12    {
13      "timestamp": "2025-03-02T11:15:00Z",
14      "source": "paid",
15      "medium": "cpc",
16      "campaign": "campaign2",
17      "content": "banner1",
18      "term": "winter coats",
19      "landing_page": "https://testdomain.com/landing",
20      "conversion": {
21        "email": "[email protected]",
22        "timestamp": "2025-03-02T11:35:00Z",
23        "conversion_page": "https://testdomain.com/thankyou",
24        "previous_page": "https://testdomain.com/pricing"
25      },
26      "exit": {
27        "exit_page": "https://testdomain.com/thankyou",
28        "previous_page": "https://testdomain.com/pricing",
29        "timestamp": "2025-03-02T11:36:00Z"
30      },
31      "duration": 1260
32    },
33    {
34      "timestamp": "2025-03-01T12:15:00Z",
35      "source": "social",
36      "medium": "social",
37      "campaign": "campaign3",
38      "content": "video_ad",
39      "term": "winter coats",
40      "landing_page": "https://testdomain.com/landing",
41      "exit": {
42        "exit_page": "https://testdomain.com/checkout-complete",
43        "previous_page": "https://testdomain.com/pricing",
44        "timestamp": "2025-03-03T12:29:00Z"
45      },
46      "duration": 840
47    }
48    ... 47 more records
49  ],
50  "pagination": {
51    "current_page": 1,
52    "total_pages": 300,
53    "total_records": 3000
54  }
55}

Sample Response Highlights

Each session record represents a unique session that meets the filter criteria.  Each page can contain up to 50 records. Use the pagination object to request additional pages of results.

Session records may include the following fields:

timestamp

When the session started (ISO 8601 UTC format).

source

Referring domain or platform (e.g., google, facebook, direct). We use referral information to interpret the source without utm_source being provided. If utm_source is provided, the utm_source is used.

medium

Marketing channel (e.g., organic, cpc, email). We use referral information to interpret the medium without utm_source being provided. If utm_source is provided, the utm_source is used.

campaign

UTM campaign name used in the session. Only available if the session originated from a UTM-tagged URL.

content

UTM content value (e.g., ad variation). Only available if present in the URL.

term

UTM term value. Only available if provided via UTM parameters.

landing_page

The URL where the session began.

conversion

Present if a conversion occurred in the session. Each conversion event object includes:

• email: The user’s email address.
• conversion_page: Page where the user converted
• previous_page: Page before the conversion
• timestamp: When the conversion occurred

exit

Present if the session ended with an identifiable exit. Each exit event object includes:

• exit_page: The final page visited
• previous_page: The page viewed just before exiting
• timestamp: When the session ended

duration

Time in seconds between session start and the exit event, only included if an exit timestamp is available.

Pagination

The /sessions endpoint uses page-based pagination to return up to 50 session records per request. Use the page parameter to request specific pages of data, starting from page 1. Each response includes a pagination object that shows the current page, total number of pages, and total number of matching session records.

current_page

The current page number returned in this response.

total_pages

The total number of available pages based on your filters and date range.

total_records

The total number of matching sessions across all pages.

No Results

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

Copy
1{ "message": "No sessions found for the given parameters." }

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