Get Usage Metrics

GET 
/api/v2/org/:org_id/workspace/:workspace_id/metrics/usage

Get workspace usage analytics: Daily, Weekly, and Monthly Active Users.

Calculates user activity metrics based on login events (METRIC_TYPE_LOGIN). Each day in the period gets DAU/WAU/MAU values calculated from unique subjects. Uses a rolling window approach for WAU and MAU calculations.

Args:

org_id (str): Path parameter - Organization ID that owns the workspace workspace_id (str): Path parameter - Target workspace ID to analyze period_length (int): Query parameter - Number of days to look back from today (default: 365) Maximum recommended: 730 days (2 years) for performance metrics (List[str], optional): Query parameter - Which metrics to calculate Valid values: ["dau", "wau", "mau"] If None/empty, calculates all three metrics Can specify subset like ["dau", "mau"] to skip WAU calculation

Returns

list[UsageMetricSchema]: Daily usage metrics with schema:

• date (str): Date in "YYYY-MM-DD" format
• dau (int|None): Daily Active Users count for that day
• wau (int|None): Weekly Active Users count (7-day rolling window ending on that day)
• mau (int|None): Monthly Active Users count (30-day rolling window ending on that day)

Details

• Only counts login events (settings.METRIC_TYPE_LOGIN), not all metric types
• Users are identified by the 'subject' field in metrics, typically member_id
• WAU uses calendar week boundaries (Monday-Sunday), not 7-day rolling windows
• MAU uses month boundaries (1st-last day), not 30-day rolling windows
• For MAU, the date format is "YYYY-MM-01" (first day of month) in calculations
• Missing data results in None values, not 0
• WAU and MAU inherit previous day's value if no new data (forward-fill behavior)
• Results are ordered from oldest to newest (ascending chronological order)
• Period calculation starts from (today - period_length) to today

Example Response:

[ {"date": "2024-01-01", "dau": 45, "wau": 120, "mau": 450}, {"date": "2024-01-02", "dau": 52, "wau": 125, "mau": 450}, {"date": "2024-01-03", "dau": 38, "wau": 128, "mau": 460} ]

Performance Notes:

• Large period_length values (>365 days) significantly impact query performance
• WAU calculation requires date_trunc operations which are slower
• Consider caching results for frequently accessed date ranges

Permissions:

• Scope: workspace_metrics:read
• Allowed Roles:
  • superadmin: ✓
  • admin: ✓
  • controller: ✓
  • curator: ✓
  • basic: ✗ (read permission denied)

Request

Responses

200

Successful Response

422

Validation Error