List Visit Sessions (v1)

Method & Path

GET /api/v1/workspace/:workspaceId/analytics/sessions

Description

Retrieve a paginated list of visit sessions with optional filtering.

Authentication

Required: Workspace authentication. User must be authenticated as Workspace Owner or Staff with workspace.read permission.

Headers

Authorization: Bearer <workspace_token>
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace identifier

Query Parameters

Parameter	Type	Required	Description
type	string	No	Filter by type (vcard, storefront)
destinationSlug	string	No	Filter by destination slug
source	string	No	Filter by source (tracking-link, direct)
trackingLinkId	string	No	Filter by tracking link ID
startDate	string	No	Start date (ISO 8601 datetime format)
endDate	string	No	End date (ISO 8601 datetime format)
limit	number	No	Number of results per page (default: 50, min: 1, max: 100)
offset	number	No	Number of results to skip (default: 0, min: 0)

Response 200 OK

{
  "sessions": [
    {
      "id": "507f1f77bcf86cd799439011",
      "workspaceId": "507f1f77bcf86cd799439012",
      "type": "storefront",
      "destinationSlug": "my-store",
      "source": "tracking-link",
      "trackingLinkId": "507f1f77bcf86cd799439013",
      "firstVisitAt": "2025-01-15T10:30:00.000Z",
      "lastVisitAt": "2025-01-15T10:45:00.000Z",
      "pageViewCount": 5,
      "sessionDuration": 900,
      "userAgent": "Mozilla/5.0...",
      "ipAddress": "192.168.1.1"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

Response Fields

sessions

Array of visit session objects:

• id (string): Session identifier
• workspaceId (string): Workspace identifier
• type (string): Session type (vcard, storefront)
• destinationSlug (string): Destination slug
• source (string): Visit source (tracking-link, direct)
• trackingLinkId (string | null): Tracking link ID if source is tracking-link
• firstVisitAt (string): First visit timestamp (ISO 8601 format)
• lastVisitAt (string): Last visit timestamp (ISO 8601 format)
• pageViewCount (number): Number of page views in session
• sessionDuration (number): Session duration in seconds
• userAgent (string | null): User agent string
• ipAddress (string | null): IP address (may be anonymized)

pagination

• total (number): Total number of sessions
• limit (number): Number of results per page
• offset (number): Number of results skipped
• hasMore (boolean): Whether there are more results

Common Errors

400 Bad Request: Invalid query parameters (e.g., invalid date format, invalid limit/offset)

401 Unauthorized: Missing or invalid authentication token

403 Forbidden: User does not have workspace.read permission

404 Not Found: Workspace not found

500 Internal Server Error: Server error occurred while processing the request

Notes

• Sessions are sorted by firstVisitAt (newest first)
• Date filters use UTC timezone
• IP addresses may be anonymized for privacy