Visitor Endpoints

The Visitors API provides access to individual visitor profiles, including identity information, browsing history, and revenue attribution. Use these endpoints to look up specific visitors or browse your full visitor list.

Authentication

All visitor endpoints require a valid API key passed via the Authorization header and a site_id query parameter.

Endpoints

GET /api/v1/visitors

Returns a paginated list of visitors for your website. Each visitor includes identity fields, geographic data, device information, and activity counts.

Parameter	Type	Required	Description
`site_id`	string	Yes	Your website ID (e.g., `ds_abc123`)
`start`	string	No	ISO 8601 start date. Default: 30 days ago
`end`	string	No	ISO 8601 end date. Default: now
`timezone`	string	No	IANA timezone. Default: UTC
`limit`	number	No	Results per page, 1–1000. Default: 100
`offset`	number	No	Number of results to skip for pagination. Default: 0

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/visitors?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=20&offset=0"

{
  "results": [
    {
      "visitor_id": "v_8f3a2b1c",
      "country": "United States",
      "city": "San Francisco",
      "browser": "Chrome",
      "os": "macOS",
      "device_type": "desktop",
      "referrer": "google.com",
      "last_seen": "2026-03-25T14:32:00Z",
      "pageview_count": 24,
      "goal_count": 3,
      "user_id": "usr_12345",
      "display_name": "Jane Doe",
      "email": "jane@example.com",
      "custom_properties": {
        "plan": "pro",
        "company": "Acme Inc"
      }
    },
    {
      "visitor_id": "v_9d4c3e2f",
      "country": "Germany",
      "city": "Berlin",
      "browser": "Firefox",
      "os": "Linux",
      "device_type": "desktop",
      "referrer": "twitter.com",
      "last_seen": "2026-03-25T12:10:00Z",
      "pageview_count": 8,
      "goal_count": 1,
      "user_id": null,
      "display_name": null,
      "email": null,
      "custom_properties": {}
    }
  ],
  "meta": {
    "site_id": "ds_abc123",
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-26T23:59:59Z",
    "limit": 20,
    "offset": 0,
    "total": 1243
  }
}

Tip

Use the offset parameter together with limit to paginate through large visitor lists. The meta.total field tells you the total number of matching visitors.

GET /api/v1/visitors/:id

Returns the full profile for a single visitor, including identity information, geographic and device data, attribution details, and revenue associated with this visitor. No date parameters are needed.

Parameter	Type	Required	Description
`site_id`	string	Yes	Your website ID
`:id`	string	Yes	The visitor_id (URL path parameter)

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/visitors/v_8f3a2b1c?site_id=ds_abc123"

{
  "results": {
    "visitor_id": "v_8f3a2b1c",
    "user_id": "usr_12345",
    "display_name": "Jane Doe",
    "email": "jane@example.com",
    "custom_properties": {
      "plan": "pro",
      "company": "Acme Inc"
    },
    "country": "United States",
    "region": "California",
    "city": "San Francisco",
    "browser": "Chrome",
    "os": "macOS",
    "device_type": "desktop",
    "first_seen": "2026-02-10T08:15:00Z",
    "last_seen": "2026-03-25T14:32:00Z",
    "total_visits": 18,
    "total_pageviews": 124,
    "total_goals": 5,
    "referrer": "google.com",
    "utm_source": "google",
    "utm_medium": "organic",
    "utm_campaign": null,
    "revenue": {
      "total_paid": 299.00,
      "payments": [
        {
          "amount": 99.00,
          "currency": "USD",
          "transaction_id": "txn_abc123",
          "product_name": "Pro Plan",
          "paid_at": "2026-02-15T10:00:00Z"
        },
        {
          "amount": 200.00,
          "currency": "USD",
          "transaction_id": "txn_def456",
          "product_name": "Enterprise Addon",
          "paid_at": "2026-03-01T12:00:00Z"
        }
      ],
      "subscription": {
        "status": "active",
        "plan": "Pro Plan",
        "mrr": 99.00,
        "started_at": "2026-02-15T10:00:00Z"
      }
    }
  },
  "meta": {
    "site_id": "ds_abc123"
  }
}

GET /api/v1/visitors/:id/journey

Returns the complete event timeline for a visitor, ordered chronologically. This includes pageviews, goal completions, and other tracked events across all sessions.

Parameter	Type	Required	Description
`site_id`	string	Yes	Your website ID
`:id`	string	Yes	The visitor_id (URL path parameter)

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/visitors/v_8f3a2b1c/journey?site_id=ds_abc123"

{
  "results": [
    {
      "event_type": "pageview",
      "pathname": "/",
      "goal_name": null,
      "referrer": "google.com",
      "session_id": "s_1a2b3c",
      "timestamp": "2026-03-25T14:00:00Z"
    },
    {
      "event_type": "pageview",
      "pathname": "/pricing",
      "goal_name": null,
      "referrer": null,
      "session_id": "s_1a2b3c",
      "timestamp": "2026-03-25T14:02:30Z"
    },
    {
      "event_type": "goal",
      "pathname": "/pricing",
      "goal_name": "signup",
      "referrer": null,
      "session_id": "s_1a2b3c",
      "timestamp": "2026-03-25T14:05:00Z"
    },
    {
      "event_type": "pageview",
      "pathname": "/dashboard",
      "goal_name": null,
      "referrer": null,
      "session_id": "s_1a2b3c",
      "timestamp": "2026-03-25T14:05:15Z"
    }
  ],
  "meta": {
    "site_id": "ds_abc123",
    "visitor_id": "v_8f3a2b1c",
    "total_events": 4
  }
}

Note

The journey endpoint returns all events across all sessions for the visitor. Use the session_id field to group events by individual visits.

Analytics

Goals & Revenue