Journey Tracking

Journey tracking lets you see what visitors do after clicking your short link. Ingest events from your site, then query sessions, funnels, and summaries.

Ingest events

Send events via POST /public-api/v1/journey/events. This endpoint does not count toward your hourly API rate limit, but events do count against your monthly journey event limit (see Volume limits).

curl -X POST https://qck.sh/public-api/v1/journey/events \
  -H "X-API-Key: qck_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "link_id": "550e8400-e29b-41d4-a716-446655440000",
        "visitor_id": "user-123",
        "session_id": "sess-abc",
        "event_type": "page_view",
        "page_url": "https://example.com/landing",
        "page_title": "Landing Page"
      },
      {
        "link_id": "550e8400-e29b-41d4-a716-446655440000",
        "visitor_id": "user-123",
        "session_id": "sess-abc",
        "event_type": "scroll_depth",
        "page_url": "https://example.com/landing",
        "scroll_percent": 75
      }
    ]
  }'

Event fields

Field	Type	Required	Description
link_id	string	Yes	UUID of the QCK link
visitor_id	string	Yes	Your visitor identifier
session_id	string	No	Session ID (enables session analytics and funnels)
event_type	string	Yes	page_view, scroll_depth, time_on_page, custom, or conversion
event_name	string	No	Name for custom/conversion events
page_url	string	Yes	Page URL or screen name
page_title	string	No	Page title
scroll_percent	number	No	Scroll depth (0–100)
time_on_page	number	No	Seconds spent on page
properties	object	No	Arbitrary key-value data

Query journey data

All query endpoints are scoped to a specific link.

Summary

curl "https://qck.sh/public-api/v1/journey/links/{link_id}/summary?period=30d" \
  -H "X-API-Key: qck_your_api_key_here"

Returns total visitors, sessions, events, average session duration, top pages, and top events.

Sessions

curl "https://qck.sh/public-api/v1/journey/links/{link_id}/sessions?period=30d" \
  -H "X-API-Key: qck_your_api_key_here"

Events

curl "https://qck.sh/public-api/v1/journey/links/{link_id}/events?period=30d" \
  -H "X-API-Key: qck_your_api_key_here"

Funnel analysis

Define a sequence of steps to see where visitors drop off:

curl -G "https://qck.sh/public-api/v1/journey/links/{link_id}/funnel" \
  --data-urlencode "steps=page_view,scroll_depth,conversion" \
  --data-urlencode "period=30d" \
  -H "X-API-Key: qck_your_api_key_here"

Volume limits

Journey events per month by tier: Free (15,000), Basic (450,000), Growth (3,000,000), Pro (6,000,000), Business (30,000,000), Scale (75,000,000).

Events count against your monthly limit at ingestion. Enforcement is graduated:

• Up to 100% of your limit: batches are accepted normally.
• 100–150% of your limit: batches are still accepted, but responses include warning headers: x-journey-warning: soft_limit (100–120%) or hard_limit_approaching (120–150%), plus x-journey-usage: used/limit and a usage object in the response body.
• Past 150%: ingestion returns 429 with error code JOURNEY_LIMIT_EXCEEDED and a Retry-After header (seconds until the month resets).

The counter resets at the start of each calendar month. Query date ranges are additionally clamped by your usage and retention. When over the limit, queries show only the most recent events within budget.