Ghost ID Docs

Product documentation

Back to Dashboard

Events & Tracking API

These endpoints power dashboard overviews and per-session event timelines.

🌐 Endpoints

GET/api/stats

Return overview metrics, top pages, and top countries for a selected site and time range.

🔑 Authentication required: Yes, via session cookie.

Parameters

Name	Type	Required	Description
siteId	number	Yes	Site to query.
timeRange	string	No	One of 24h, 7d, or 30d. Defaults to 7d.

Example Request

Bash

curl --request GET \
  --url "https://analytics.ghostid.ai/api/stats?siteId=4&timeRange=7d" \
  --cookie "session=YOUR_SESSION_COOKIE"

Response Example

JSON

{
  "overview": {
    "unique_visitors": 142,
    "sessions": 188,
    "pageviews": 913,
    "total_events": 1410,
    "identified_visitors": 37,
    "hot_leads": 21
  },
  "top_pages": [
    { "page": "/", "views": 210 },
    { "page": "/pricing", "views": 144 }
  ],
  "countries": [
    { "country": "United States", "visitors": 88 },
    { "country": "Canada", "visitors": 17 }
  ],
  "time_range": "7d"
}

GET/api/session/:id

Return the full timeline for a specific session, including visited pages and event order.

🔑 Authentication required: Yes, via session cookie.

Parameters

Name	Type	Required	Description
id	path	Yes	Session ID to inspect.
siteId	number	Yes	Site that owns the session.

Example Request

Bash

curl --request GET \
  --url "https://analytics.ghostid.ai/api/session/gs_123?siteId=4" \
  --cookie "session=YOUR_SESSION_COOKIE"

Response Example

JSON

{
  "session_id": "gs_123",
  "ghost_vid": "gv_a1b2c3d4_e5f6g7h8",
  "identified_user_id": "jane@example.com",
  "country": "United States",
  "city": "Austin",
  "device_type": "desktop",
  "browser": "Chrome",
  "os": "macOS",
  "started_at": "2026-03-10T17:09:10.000Z",
  "ended_at": "2026-03-10T17:14:22.000Z",
  "duration_seconds": 312,
  "event_count": 9,
  "pageview_count": 5,
  "entry_page": "/",
  "exit_page": "/pricing",
  "referrer": "https://google.com",
  "pages": ["/", "/features", "/pricing"],
  "timeline": [
    {
      "type": "pageview",
      "event_name": "",
      "page": "/",
      "page_title": "Home",
      "timestamp": "2026-03-10T17:09:10.000Z",
      "time_on_previous_page": 0,
      "props": {}
    },
    {
      "type": "custom_event",
      "event_name": "cta_clicked",
      "page": "/pricing",
      "page_title": "Pricing",
      "timestamp": "2026-03-10T17:13:40.000Z",
      "time_on_previous_page": 48,
      "props": {
        "section": "hero"
      }
    }
  ]
}