Get Assistants Usage

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

Get daily time series usage data grouped by assistant name.

Aggregates assistant interaction metrics into daily buckets, providing a time series view of how different assistants are being used over time. This endpoint is designed for analytics dashboards and usage reports.

Args:

org_id (str): Path parameter - Organization ID that owns the workspace workspace_id (str): Path parameter - Target workspace ID to analyze from_date (datetime): Query parameter - Start date for the analysis period (inclusive) to_date (datetime): Query parameter - End date for the analysis period (inclusive)

Returns

AssistantsUsageMetricsSchema: Nested structure containing:

• data (dict): Dictionary where keys are assistant names and values are time series
  • Keys: Assistant names (string), "unknown" for unidentified assistants
  • Values: List of MetricsTimeSeriesSchema objects with:
    • x (str): Date in "YYYY-MM-DD" format
    • y (int): Number of interactions for that assistant on that day

Details

• Currently returns empty data structure (placeholder implementation)
• Will require integration with assistants message/interaction tracking
• Assistant identification depends on assistant_name field in message records
• Missing assistant names are grouped under "unknown" key
• Days without activity for an assistant will show count of 0
• Date range filtering is inclusive on both ends
• Results are ordered in reverse chronological order (newest first)
• Large date ranges may impact performance depending on message volume

Implementation Status:

This endpoint currently returns empty data as it requires integration with the assistants message tracking system. The data structure and behavior documentation reflects the intended final implementation.

Example Response (when fully implemented):

{ "data": { "GPT-4": [ {"x": "2024-01-03", "y": 25}, {"x": "2024-01-02", "y": 18}, {"x": "2024-01-01", "y": 12} ], "Claude": [ {"x": "2024-01-03", "y": 15}, {"x": "2024-01-02", "y": 22}, {"x": "2024-01-01", "y": 8} ], "unknown": [ {"x": "2024-01-03", "y": 2}, {"x": "2024-01-02", "y": 1}, {"x": "2024-01-01", "y": 0} ] } }

Permissions:

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

Request

Responses

200

Successful Response

422

Validation Error