--- title: Journeys description: POST /v1/journeys/* - Query visitor journeys and individual visitor details url: https://www.supalytics.co/docs/api/journeys --- View visitor journeys, list all visitors with filtering, and get detailed timelines for individual visitors. ## List Visitors ``` POST https://api.supalytics.co/v1/journeys/list ``` Returns a paginated list of visitors with aggregated stats. ### Request Body | Field | Type | Required | Description | | ---------------- | --------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- | | `domain` | string | Yes | Site domain to query | | `date_range` | string or \[string, string] | No | Period (`7d`, `14d`, `30d`, `90d`, `12mo`, `all`) or `[start, end]` dates. Default: `30d` | | `filters` | array | No | Page-level filters as `[field, operator, value]` tuples | | `pageviews_gt` | number | No | Minimum pageviews | | `pageviews_lt` | number | No | Maximum pageviews | | `sessions_gt` | number | No | Minimum sessions | | `sessions_lt` | number | No | Maximum sessions | | `revenue_gt` | number | No | Minimum revenue (cents) | | `revenue_lt` | number | No | Maximum revenue (cents) | | `has_revenue` | boolean | No | Only visitors with revenue | | `first_purchase` | boolean | No | Only first-time purchases | | `sort_by` | string | No | Sort field: `last_seen`, `first_seen`, `pageviews`, `sessions`, `revenue`, `latest_revenue`. Default: `last_seen` | | `sort_order` | string | No | `asc` or `desc`. Default: `desc` | | `limit` | number | No | Results per page (1-100). Default: `50` | | `offset` | number | No | Pagination offset. Default: `0` | | `timezone` | string | No | IANA timezone. Default: `UTC` | | `is_dev` | boolean | No | Query localhost/test data | ### Filter Fields Filters use the format `[field, operator, value]`: * **Fields**: `page`, `country`, `region`, `city`, `browser`, `os`, `device`, `referrer`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `event`, `event_property` * **Operators**: `is`, `is_not`, `contains`, `not_contains`, `starts_with` ### Response ```json { "data": [ { "visitor_id": "abc123xyz789", "country": "US", "browser": "Chrome", "os": "macOS", "device": "Desktop", "pageview_count": 12, "session_count": 3, "event_count": 5, "total_revenue_cents": 2900, "first_seen": "2025-01-15 10:30:45", "last_seen": "2025-01-20 14:15:00", "first_referrer": "google.com", "entry_page": "/pricing", "latest_revenue_date": "2025-01-20 14:15:00", "revenue_event_count": 1 } ], "meta": { "domain": "example.com", "date_range": ["2024-12-25 00:00:00", "2025-01-24 23:59:59"], "timezone": "UTC", "query_ms": 45 }, "pagination": { "limit": 50, "offset": 0, "has_more": true, "total": 150 } } ``` ### Example ```bash curl -X POST https://api.supalytics.co/v1/journeys/list \ -H "Authorization: Bearer sly_xxx..." \ -H "Content-Type: application/json" \ -d '{ "domain": "example.com", "date_range": "30d", "has_revenue": true, "sort_by": "revenue", "sort_order": "desc", "limit": 20 }' ``` With filters: ```bash curl -X POST https://api.supalytics.co/v1/journeys/list \ -H "Authorization: Bearer sly_xxx..." \ -H "Content-Type: application/json" \ -d '{ "domain": "example.com", "filters": [ ["country", "is", "US"], ["device", "is", "Desktop"] ], "pageviews_gt": 5, "revenue_gt": 1000 }' ``` *** ## Get Visitor Timeline ``` POST https://api.supalytics.co/v1/journeys/timeline ``` Returns the chronological timeline of actions for a specific visitor. ### Request Body | Field | Type | Required | Description | | ------------ | --------------------------- | -------- | -------------------------------------------- | | `domain` | string | Yes | Site domain | | `visitor_id` | string | Yes | Visitor ID | | `date_range` | string or \[string, string] | No | Period or date range. Default: `30d` | | `limit` | number | No | Items per page (1-1000). Default: `100` | | `offset` | number | No | Pagination offset. Default: `0` | | `timezone` | string | No | IANA timezone for timestamps. Default: `UTC` | | `is_dev` | boolean | No | Query localhost/test data | ### Response ```json { "data": [ { "timestamp": "2025-01-20 14:15:45", "type": "revenue", "session_id": "", "transaction_id": "tx_abc123", "amount_cents": 2900, "currency": "USD", "revenue_event": "purchase" }, { "timestamp": "2025-01-20 14:12:30", "type": "pageview", "session_id": "sess_xyz789", "url_path": "/checkout", "is_entry_page": 0 }, { "timestamp": "2025-01-20 14:10:00", "type": "pageview", "session_id": "sess_xyz789", "url_path": "/pricing", "referrer": null, "utm_source": null, "is_entry_page": 1, "scroll_depth": 85, "country": "US", "browser": "Chrome", "os": "macOS", "device": "Desktop" }, { "timestamp": "2025-01-18 09:20:10", "type": "event", "session_id": "", "event_name": "newsletter_signup", "event_properties": "{\"source\": \"blog\"}" } ], "meta": { "domain": "example.com", "visitor_id": "abc123xyz789", "date_range": ["2024-12-25 00:00:00", "2025-01-24 23:59:59"], "timezone": "UTC", "query_ms": 32 }, "pagination": { "limit": 100, "offset": 0, "has_more": false } } ``` ### Timeline Action Types | Type | Description | | ---------- | --------------------------------------------------------------------------------- | | `pageview` | Page visit with URL, referrer (on entry), scroll depth | | `event` | Custom event with name and properties | | `revenue` | Payment event with amount, currency, transaction ID | | `auto` | Auto-tracked event (clicks, form submits) - only with `include_auto_events: true` | ### Example ```bash curl -X POST https://api.supalytics.co/v1/journeys/timeline \ -H "Authorization: Bearer sly_xxx..." \ -H "Content-Type: application/json" \ -d '{ "domain": "example.com", "visitor_id": "abc123xyz789", "date_range": "90d", "timezone": "America/New_York" }' ``` *** ## Get Visitor Stats ``` POST https://api.supalytics.co/v1/journeys/stats ``` Returns aggregated statistics for a specific visitor. ### Request Body | Field | Type | Required | Description | | ------------ | ------- | -------- | ------------------------- | | `domain` | string | Yes | Site domain | | `visitor_id` | string | Yes | Visitor ID | | `is_dev` | boolean | No | Query localhost/test data | ### Response ```json { "data": { "visitor_id": "abc123xyz789", "first_seen": "2025-01-15 10:30:45", "last_seen": "2025-01-20 14:15:00", "total_sessions": 3, "total_pageviews": 12, "total_events": 5, "total_revenue_cents": 2900, "avg_scroll_depth": 65, "avg_session_duration_seconds": 225, "country": "US", "region": "California", "city": "San Francisco", "browser": "Chrome", "os": "macOS", "device": "Desktop", "entry_page": "/pricing", "source": "google.com", "utm_source": "google", "utm_medium": "cpc", "utm_campaign": "winter_sale" }, "meta": { "domain": "example.com", "visitor_id": "abc123xyz789", "query_ms": 18 } } ``` ### Example ```bash curl -X POST https://api.supalytics.co/v1/journeys/stats \ -H "Authorization: Bearer sly_xxx..." \ -H "Content-Type: application/json" \ -d '{ "domain": "example.com", "visitor_id": "abc123xyz789" }' ``` *** ## Get Visitor Activity Heatmap ``` POST https://api.supalytics.co/v1/journeys/activity ``` Returns activity patterns by day of week and hour for a specific visitor. ### Request Body | Field | Type | Required | Description | | ------------ | ------- | -------- | ------------------------- | | `domain` | string | Yes | Site domain | | `visitor_id` | string | Yes | Visitor ID | | `is_dev` | boolean | No | Query localhost/test data | ### Response ```json { "data": [ { "day_of_week": 1, "hour_of_day": 10, "pageviews": 5, "unique_visitors": 1 }, { "day_of_week": 3, "hour_of_day": 14, "pageviews": 3, "unique_visitors": 1 } ], "meta": { "domain": "example.com", "visitor_id": "abc123xyz789", "query_ms": 12 } } ``` `day_of_week`: 1 = Monday, 7 = Sunday `hour_of_day`: 0-23 *** ## Authentication All endpoints require `analytics:read` scope. ``` Authorization: Bearer sly_xxx... ``` Both Project API Keys and Personal Access Tokens (PATs) are supported. ## Rate Limits 100 requests per minute per API key. ## Error Responses | Status | Description | | ------ | ------------------------------------- | | 400 | Invalid request (validation error) | | 403 | Access denied or usage limit exceeded | | 404 | Visitor not found | | 500 | Server error | See [Errors](/docs/api/errors) for details. --- ## Other Documentation - [Autocapture](https://www.supalytics.co/llms/docs/autocapture) - [Backfill Existing Subscriptions](https://www.supalytics.co/llms/docs/backfill-existing-subscriptions) - [Block Your Own Traffic](https://www.supalytics.co/llms/docs/block-your-traffic) - [CLI](https://www.supalytics.co/llms/docs/cli) - [Custom Events](https://www.supalytics.co/llms/docs/custom-events) - [Features](https://www.supalytics.co/llms/docs/features) - [Conversion Funnels](https://www.supalytics.co/llms/docs/funnels) - [Introduction](https://www.supalytics.co/llms/docs) - [Install Script](https://www.supalytics.co/llms/docs/install-script) - [MRR Tracking](https://www.supalytics.co/llms/docs/mrr-tracking) - [Revenue Attribution](https://www.supalytics.co/llms/docs/revenue-attribution) - [Agent Skills](https://www.supalytics.co/llms/docs/skills) - [Tracking Modes](https://www.supalytics.co/llms/docs/tracking-modes) - [Visitor Journey](https://www.supalytics.co/llms/docs/visitor-journey) - [Annotations](https://www.supalytics.co/llms/docs/api/annotations) - [Error Codes](https://www.supalytics.co/llms/docs/api/errors) - [Events (Read)](https://www.supalytics.co/llms/docs/api/events) - [API Reference](https://www.supalytics.co/llms/docs/api) - [Query API](https://www.supalytics.co/llms/docs/api/query) - [Realtime API](https://www.supalytics.co/llms/docs/api/realtime) - [Revenue Attribution API](https://www.supalytics.co/llms/docs/api/revenue-attribution) - [Events (Write)](https://www.supalytics.co/llms/docs/api/server-side-events)