Skip to main content
GET
/
api
/
websites
/
:id
/
journey
Get User Journey
curl --request GET \
  --url https://api.example.com/api/websites/:id/journey
{
  "data": {
    "anchor": {
      "type": "<string>",
      "value": "<string>"
    },
    "direction": "<string>",
    "max_depth": 123,
    "total_anchor_sessions": 123,
    "branches": [
      {
        "nodes": [
          {}
        ],
        "sessions": 123,
        "share": 123
      }
    ]
  }
}

​
Path Parameters

​
id
string
required
Website ID

​
Query Parameters

​
anchor_type
string
required
Type of anchor point: page or event.
​
anchor_value
string
required
The anchor value to analyze (page URL or event name). Maximum 500 characters.
​
direction
string
required
Journey direction: next (what happens after) or previous (what happens before).
​
max_depth
integer
default:"3"
Maximum depth of journey branches to analyze (1-5).
​
start_date
string
required
Start date in YYYY-MM-DD format.
​
end_date
string
required
End date in YYYY-MM-DD format.
​
timezone
string
IANA timezone string (e.g., America/New_York). Required for accurate date boundary calculations.
​
include_bots
boolean
Whether to include bot traffic in results. Defaults to website’s bot policy setting.

​
Filter Parameters

​
filter_country
string
ISO 3166-1 alpha-2 country code.
​
filter_page
string
Filter by page URL path.
​
filter_referrer
string
Filter by referrer domain.
​
filter_browser
string
Filter by browser name.
​
filter_os
string
Filter by operating system.
​
filter_device
string
Filter by device type.
​
filter_language
string
Filter by browser language.
​
filter_utm_source
string
Filter by UTM source parameter.
​
filter_utm_medium
string
Filter by UTM medium parameter.
​
filter_utm_campaign
string
Filter by UTM campaign parameter.
​
filter_region
string
Filter by geographic region/state.
​
filter_city
string
Filter by city name.
​
filter_hostname
string
Filter by hostname.

​
Response

​
data
object
User journey analysis results.
​
anchor
object
The anchor point that was analyzed.
​
type
string
Anchor type: page or event.
​
value
string
The anchor value (page URL or event name).
​
direction
string
Direction analyzed: next or previous.
​
max_depth
integer
Maximum depth of branches analyzed.
​
total_anchor_sessions
integer
Total number of sessions that included the anchor point.
​
branches
array
Array of journey branches, sorted by session count descending.
​
nodes
array
Array of node values representing the journey path (strings).
​
sessions
integer
Number of sessions that followed this path.
​
share
number
Percentage of total anchor sessions that followed this path (0-100).

​
Example Request - Next Pages

curl -X GET "https://analytics.example.com/api/websites/abc123/journey?anchor_type=page&anchor_value=/pricing&direction=next&max_depth=3&start_date=2024-03-01&end_date=2024-03-07&timezone=America/New_York" \
  -H "Authorization: Bearer spk_live_your_api_key"

​
Example Response - Next Pages

{
  "data": {
    "anchor": {
      "type": "page",
      "value": "/pricing"
    },
    "direction": "next",
    "max_depth": 3,
    "total_anchor_sessions": 1823,
    "branches": [
      {
        "nodes": ["/signup"],
        "sessions": 542,
        "share": 29.7
      },
      {
        "nodes": ["/features"],
        "sessions": 389,
        "share": 21.3
      },
      {
        "nodes": ["/signup", "/onboarding"],
        "sessions": 321,
        "share": 17.6
      },
      {
        "nodes": ["/"],
        "sessions": 234,
        "share": 12.8
      },
      {
        "nodes": ["/features", "/signup"],
        "sessions": 198,
        "share": 10.9
      },
      {
        "nodes": ["/signup", "/onboarding", "/dashboard"],
        "sessions": 176,
        "share": 9.7
      },
      {
        "nodes": ["/docs"],
        "sessions": 142,
        "share": 7.8
      }
    ]
  }
}

​
Example Request - Previous Events

curl -X GET "https://analytics.example.com/api/websites/abc123/journey?anchor_type=event&anchor_value=signup_completed&direction=previous&max_depth=2&start_date=2024-03-01&end_date=2024-03-07" \
  -H "Authorization: Bearer spk_live_your_api_key"

​
Example Response - Previous Events

{
  "data": {
    "anchor": {
      "type": "event",
      "value": "signup_completed"
    },
    "direction": "previous",
    "max_depth": 2,
    "total_anchor_sessions": 618,
    "branches": [
      {
        "nodes": ["/pricing"],
        "sessions": 287,
        "share": 46.4
      },
      {
        "nodes": ["/", "/pricing"],
        "sessions": 198,
        "share": 32.0
      },
      {
        "nodes": ["/features"],
        "sessions": 89,
        "share": 14.4
      },
      {
        "nodes": ["/blog/getting-started", "/pricing"],
        "sessions": 44,
        "share": 7.1
      }
    ]
  }
}

​
Rate Limits

This endpoint has stricter rate limits due to computational complexity:
  • Concurrent query limit enforced via semaphore (5 second wait timeout)
  • May return 429 if query capacity is reached

​
Notes

  • Journey analysis is session-based (tracks paths within individual sessions)
  • The nodes array represents the sequence of pages/events in the journey
  • For direction=next, nodes show what happens after the anchor
  • For direction=previous, nodes show what happens before the anchor
  • Branches are sorted by session count in descending order (most common paths first)
  • The share percentage shows what portion of sessions that included the anchor followed each path
  • All shares sum to ≤100% (not all sessions may have subsequent/previous events)
  • Maximum depth controls how many steps in the journey are analyzed
  • Higher max_depth values may result in more granular but sparser data
  • Timezone parameter is recommended for accurate date boundary alignment
  • The anchor value must be non-empty and at most 500 characters

Build docs developers (and LLMs) love

Get started for freeTalk to us