Get Analytics Summary (v1)

Method & Path

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

Description

Retrieve analytics summary with aggregated metrics for vCard and storefront pages.

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
timeRange	string	No	Time range aggregation (hourly, daily, weekly, monthly) - default: daily
startDate	string	No	Start date (ISO 8601 datetime format)
endDate	string	No	End date (ISO 8601 datetime format)

Response 200 OK

{
  "analytics": {
    "totalVisits": 1250,
    "totalPageViews": 3420,
    "uniqueVisitors": 890,
    "averageSessionDuration": 180,
    "bounceRate": 0.35,
    "byTimeRange": [
      {
        "date": "2025-01-15",
        "visits": 45,
        "pageViews": 120,
        "uniqueVisitors": 32
      }
    ],
    "bySource": {
      "tracking-link": 850,
      "direct": 400
    },
    "byType": {
      "vcard": 600,
      "storefront": 650
    }
  }
}

Response Fields

• totalVisits (number): Total number of visits
• totalPageViews (number): Total number of page views
• uniqueVisitors (number): Number of unique visitors
• averageSessionDuration (number): Average session duration in seconds
• bounceRate (number): Bounce rate (0-1)
• byTimeRange (array): Aggregated metrics by time range
• bySource (object): Metrics grouped by source
• byType (object): Metrics grouped by type (vCard/storefront)

Common Errors

400 Bad Request: Invalid query parameters (e.g., invalid date format, invalid time range)

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

• Default time range is daily if not specified
• Date filters use UTC timezone
• Analytics data is aggregated and may have a slight delay