Visitors API

The Visitors API covers the live visitor stream, scored visitor list, and full visitor profile lookup.

🌐 Endpoints

GET/api/visitors

Return the live visitor stream for the last 24 hours, including top countries and pages.

🔑 Authentication required: Yes, via session cookie.

Parameters

Name	Type	Required	Description
siteId	number	Yes	Site to load live activity for.

Example Request

Bash

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

Response Example

JSON

{
  "visitors": [
    {
      "ghost_vid": "gv_a1b2c3d4_e5f6g7h8",
      "identified_user_id": "jane@example.com",
      "country": "United States",
      "city": "Austin",
      "region": "Texas",
      "page": "/pricing",
      "pages_viewed": 6,
      "duration_seconds": 214,
      "lat": 30.2672,
      "lon": -97.7431,
      "device_type": "desktop",
      "browser": "Chrome",
      "referrer": "https://google.com",
      "last_seen": "2026-03-10T17:14:22.000Z",
      "session_count": 2,
      "hot": true,
      "clicks": 1
    }
  ],
  "activity": [
    {
      "ghost_vid": "gv_a1b2c3d4_e5f6g7h8",
      "identified_user_id": "jane@example.com",
      "type": "pageview",
      "page": "/pricing",
      "timestamp": "2026-03-10T17:14:22.000Z"
    }
  ],
  "stats": {
    "unique_visitors": 42,
    "sessions": 55,
    "pageviews": 181,
    "avg_duration": 0
  },
  "countries": [
    { "country": "United States", "visitors": 25 }
  ],
  "pages": [
    { "page": "/pricing", "views": 31 }
  ],
  "timestamp": "2026-03-10T17:15:00.000Z"
}

GET/api/visitor

Return a scored list of visitors for a site, with support for time ranges, limits, and bot filtering.

🔑 Authentication required: Yes, via session cookie.

Parameters

Name	Type	Required	Description
siteId	number	Yes	Site to query.
limit	number	No	Max rows to return. Defaults to 50 and caps at 500.
timeRange	string	No	One of 24h, 7d, 30d, or all. Defaults to 7d.
filter	string	No	Set to bot to return bot traffic instead of standard visitors.

Example Request

Bash

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

Response Example

JSON

{
  "visitors": [
    {
      "ghost_vid": "gv_a1b2c3d4_e5f6g7h8",
      "status": "identified",
      "score": 85,
      "hot": true,
      "identified_user_id": "jane@example.com",
      "country": "United States",
      "city": "Austin",
      "device_type": "desktop",
      "browser": "Chrome",
      "lat": 30.2672,
      "lon": -97.7431,
      "first_seen": "2026-03-02T09:12:11.000Z",
      "last_seen": "2026-03-10T17:14:22.000Z",
      "total_sessions": 4,
      "total_pageviews": 19,
      "clicks": 3,
      "total_time_seconds": 905,
      "high_value_views": 2,
      "is_bot": 0
    }
  ],
  "total": 1
}

GET/api/visitor/:id

Return the full visitor profile, including sessions, recent events, attribution, form events, and link clicks.

🔑 Authentication required: Yes, via session cookie.

Parameters

Name	Type	Required	Description
id	path	Yes	Ghost visitor ID from the visitor list.
siteId	number	Yes	Site to scope the visitor lookup to.

Example Request

Bash

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

Response Example

JSON

{
  "ghost_vid": "gv_a1b2c3d4_e5f6g7h8",
  "status": "identified",
  "score": 85,
  "identified_user_id": "jane@example.com",
  "user_traits": {
    "company": "Acme",
    "plan": "enterprise"
  },
  "gravatar_url": "https://www.gravatar.com/avatar/...",
  "country": "United States",
  "city": "Austin",
  "region": "Texas",
  "lat": 30.2672,
  "lon": -97.7431,
  "device_type": "desktop",
  "browser": "Chrome",
  "os": "macOS",
  "first_seen": "2026-03-02T09:12:11.000Z",
  "last_seen": "2026-03-10T17:14:22.000Z",
  "total_sessions": 4,
  "total_pageviews": 19,
  "total_time_seconds": 905,
  "first_referrer": "https://google.com",
  "last_referrer": "https://google.com",
  "sessions": [
    {
      "session_id": "gs_123",
      "started_at": "2026-03-10T17:09:10.000Z",
      "ended_at": "2026-03-10T17:14:22.000Z",
      "duration_seconds": 312,
      "pageview_count": 5,
      "entry_page": "/",
      "exit_page": "/pricing",
      "referrer": "https://google.com",
      "device_type": "desktop",
      "browser": "Chrome"
    }
  ],
  "recent_events": [
    {
      "session_id": "gs_123",
      "type": "pageview",
      "event_name": "",
      "page": "/pricing",
      "page_title": "Pricing",
      "referrer": "https://google.com",
      "props": {},
      "timestamp": "2026-03-10T17:14:22.000Z"
    }
  ],
  "top_pages": [
    { "page": "/pricing", "views": 8 }
  ],
  "daily_activity": [
    { "date": "2026-03-10", "events": 11 }
  ],
  "attribution": {
    "first_touch": {
      "referrer": "https://google.com",
      "channel": "Organic",
      "utm_source": "google",
      "utm_medium": "organic",
      "utm_campaign": null,
      "utm_content": null,
      "utm_term": null
    },
    "last_touch": {
      "referrer": "https://google.com",
      "channel": "Organic",
      "utm_source": "google",
      "utm_medium": "organic",
      "utm_campaign": null,
      "utm_content": null,
      "utm_term": null
    },
    "touchpoints": [
      {
        "referrer": "https://google.com",
        "channel": "Organic",
        "utm_source": "google",
        "utm_medium": "organic",
        "utm_campaign": "",
        "first_seen": "2026-03-02T09:12:11.000Z",
        "last_seen": "2026-03-10T17:14:22.000Z",
        "touchpoints": 6
      }
    ]
  },
  "form_events": [
    {
      "event_name": "form_submit",
      "props": {
        "form_id": "newsletter"
      },
      "page": "/pricing",
      "timestamp": "2026-03-10T17:12:14.000Z"
    }
  ],
  "link_clicks": [
    {
      "id": 91,
      "ghost_vid": "gv_a1b2c3d4_e5f6g7h8",
      "country": "United States",
      "city": "Austin",
      "region": "Texas",
      "lat": 30.2672,
      "lon": -97.7431,
      "device_type": "desktop",
      "browser": "Chrome",
      "created_at": "2026-03-10T17:13:51.000Z",
      "referrer": "https://google.com",
      "slug": "spring-launch",
      "campaign": "spring-2026",
      "source": "newsletter",
      "medium": "email",
      "destination_url": "https://example.com/pricing"
    }
  ]
}

Sites

Events & Tracking