# analytics ## Get Content Analytics - [GET /api/analytics/content/](https://docs.ibl.ai/apis/ibl/ai-analytics/get_content_analytics.md): Retrieve aggregated analytics for catalog content (courses, programs, pathways, skills). Returns both summary statistics and paginated list of content items with individual analytics. When a platform_key is provided, results are filtered to show only content consumed by learners associated with that platform. Metrics supported: - course or courses: Course analytics with time spent - program or programs: Program analytics - pathway or pathways: Pathway analytics - skill or skills: Skill analytics Platform Filtering: - Without platform_key: Shows global analytics across all platforms - With platform_key: Shows analytics filtered by platform learners only Time Spent Analytics: - Platform-level: Total time spent across all content and average per learner - Course-level: Total time spent per course and average per enrolled learner - Time values are provided in seconds for precision - Overtime: Time series data showing platform time spent over last 7 days (courses only, and include_overtime=true) External Content: - Content not owned by the requesting platform but used by its learners is marked as "external" - External content has limited metadata exposure for privacy ## Get Content Details - [GET /api/analytics/content/details/{content_id}/](https://docs.ibl.ai/apis/ibl/ai-analytics/get_content_details.md): Retrieve detailed analytics for a specific content item including summary statistics, learner-level data, and optional time series information. ## analytics_financial_retrieve - [GET /api/analytics/financial/](https://docs.ibl.ai/apis/ibl/ai-analytics/analytics_financial_retrieve.md): Financial Analytics API - Get comprehensive cost metrics with comparison analysis. This endpoint provides period-based cost analysis (not cumulative) with support for: - Multiple time granularities and metrics - Cross-dimensional filtering - Percentage change vs comparison periods - Forward-filled time series Examples: Basic Weekly Costs: GET /api/analytics/financial/?metric=weekly_costs&comparison_days=10 Platform & Mentor Filtered: # Get total costs for a specific platform and mentor GET /api/analytics/financial/?metric=total_costs&platform_key=web-app&mentor_unique_id=mentor-123&comparison_days=14 Monthly Costs by Provider: GET /api/analytics/financial/?metric=monthly_costs&provider=openai&granularity=month&comparison_days=30 Daily Costs for Specific User: GET /api/analytics/financial/?metric=total_costs&username=user-456&granularity=day&start_date=2025-01-15&end_date=2025-01-21&comparison_days=7 Response Structure: json { "metric": "weekly_costs", "value": 12.47, "percentage_change": 8.5, "overtime": [ {"date": "2025-01-06", "value": 2.89}, {"date": "2025-01-13", "value": 3.12} ], "period_info": { "start_date": "2025-01-01", "end_date": "2025-01-31", "period_days": 31 }, "comparison_info": { "previous_period_value": 11.50, ... } } ## analytics_financial_details_retrieve - [GET /api/analytics/financial/details/](https://docs.ibl.ai/apis/ibl/ai-analytics/analytics_financial_details_retrieve.md): Financial Details Analytics API – paginated cost tables with flexible grouping. This endpoint returns tabular cost metrics aggregated by the dimension specified via the group_by query parameter. One or more KPI columns can be requested through the comma-separated metrics list while typical filters (date range, provider, platform_key, user, etc.) narrow the dataset. Results are paginated with page / limit. Required query parameters - group_by – provider | llm_model | username | mentor | platform - metrics – csv list of KPI names, e.g. total_cost, sessions Shared optional filters - start_date, end_date – ISO yyyy-mm-dd (ignored when all_time=true) - platform_key – tenant isolation - mentor_unique_id – filter to one mentor - username – filter to a learner - provider / llm_model – filter to LLM provider / model - all_time – true → lifetime totals - page (default 1), limit (default 50) Examples -------- 1. Cost by provider for the last week GET /api/v2/analytics/financial/details? group_by=provider& metrics=total_cost& start_date=2025-01-01& end_date=2025-01-07& page=1&limit=10 2. Lifetime cost per user with extra KPIs GET /api/v2/analytics/financial/details? group_by=username& metrics=total_cost,sessions& all_time=true&page=1&limit=50 3. Cost by LLM model with tenant filter GET /api/v2/analytics/financial/details? group_by=llm_model& metrics=total_cost& platform_key=web-app& start_date=2025-01-01&end_date=2025-01-31 Response structure ------------------- `` { "page": 1, "limit": 10, "total_pages": 1, "total_records": 3, "rows": [ {"provider": "openai", "total_cost": "2.50000"}, {"provider": "anthropic", "total_cost": "1.00000"}, {"provider": "azure", "total_cost": "0.50000"} ], "metrics": [ { "name": "total_cost", "unit": "$", "description": "Cost for this entity in period" } ], "total_cost": "4.00000" // optional grand-total when available } ` ## analytics_financial_invoice_retrieve - [GET /api/analytics/financial/invoice/](https://docs.ibl.ai/apis/ibl/ai-analytics/analytics_financial_invoice_retrieve.md): Flexible Invoice Report API – Billing summary with username and platform filtering. This endpoint generates invoice reports with flexible filtering options: - Platform admins can view their platform's data and filter by username within their platform - Super admins can view any combination of username/platform or global summaries Key Features: - Flexible filtering by username and/or platform_key - Essential metrics: total cost, sessions, usage period - Provider breakdown (OpenAI, Anthropic, etc.) - Top mentors/actions by cost - Clean, invoice-ready format Query Parameters: - username: Filter by specific username (optional) - platform_key: Filter by platform (optional, but required for platform admins) - start_date, end_date: billing period (defaults to last 30 days) - include_breakdown: show provider/mentor details (default: true) Permission Logic: - Platform admins: Must include platform_key matching their permission scope - Super admins: Can use any combination of filters or none (global summary) Examples: # Platform admin viewing their platform GET /api/analytics/financial/invoice?platform_key=web-app # Platform admin viewing specific user in their platform GET /api/analytics/financial/invoice?platform_key=web-app&username=john.doe # Super admin viewing specific user across all platforms GET /api/analytics/financial/invoice?username=john.doe # Super admin viewing global summary GET /api/analytics/financial/invoice Response Structure: json { "entity": { "type": "user|platform|global", "username": "john.doe", "platform_key": "web-app", "platform_name": "Web Application", "display_name": "John Doe on Web Application" }, "billing_period": { "start_date": "2025-01-01", "end_date": "2025-01-31", "days": 31 }, "summary": { "total_cost": 245.750, "total_sessions": 1250, "active_users": 85, "cost_per_session": 0.196 }, "breakdown": { "by_provider": [...], "by_mentor": [...], "by_action": [...] } } ## analytics_learners_retrieve - [GET /api/analytics/learners/](https://docs.ibl.ai/apis/ibl/ai-analytics/analytics_learners_retrieve.md): Unified API endpoint for learner analytics. This endpoint provides either: 1. Cross-platform summary (when only username is provided) 2. Platform-specific detailed data (when username + platform_key are provided) Query params: - username (required): Username of the learner - platform_key (optional): Platform key for platform-specific data - page (optional): Page number (default: 1) - limit (optional): Records per page (default: 20, max: 100) Returns: - If platform_key provided: Detailed platform metrics - If no platform_key: Cross-platform summary with pagination ## analytics_learners_list_retrieve - [GET /api/analytics/learners/list/](https://docs.ibl.ai/apis/ibl/ai-analytics/analytics_learners_list_retrieve.md): Retrieve a paginated list of learners for a specific platform with their comprehensive metrics from the UserPlatformSummary materialized view. This endpoint is accessible only to platform administrators and supports search, sorting, and pagination. ## analytics_messages_retrieve - [GET /api/analytics/messages/](https://docs.ibl.ai/apis/ibl/ai-analytics/analytics_messages_retrieve.md): Conversation list endpoint for analytics. Query params (all optional unless specified by permissions): - platform_key: filter by platform - mentor_unique_id: filter by mentor - page: page number (default 1) - limit: page size (default 20, max 100) - search: search in user name and first user message - min_messages, max_messages: message_count range - sentiment: positive|negative|neutral - topic: topic name contains - start_date, end_date: date filter on conversation date Returns: summary totals, results list (paginated), and pagination metadata. ## analytics_messages_details_retrieve - [GET /api/analytics/messages/details/](https://docs.ibl.ai/apis/ibl/ai-analytics/analytics_messages_details_retrieve.md): Conversation detail endpoint for analytics. Query params: - session_id (required): UUID of the session to fetch - platform_key, mentor_unique_id (optional): further scope - start_date, end_date (optional): date filter on message timestamps Returns: summary metadata from conversation_list MV, and a list of human/ai message pairs in chronological order. ## analytics_ratings_retrieve - [GET /api/analytics/ratings/](https://docs.ibl.ai/apis/ibl/ai-analytics/analytics_ratings_retrieve.md): Ratings overtime endpoint. Query params: - metric: only 'ratings' is supported (default) - platform_key, mentor_unique_id: optional filters - granularity: 'day' (default) or 'hour' (hour only for today) - start_date, end_date: optional date range; defaults applied if not provided Returns: { metric: 'ratings', points: [{date, value}, ...] } ## analytics_sessions_retrieve - [GET /api/analytics/sessions/](https://docs.ibl.ai/apis/ibl/ai-analytics/analytics_sessions_retrieve.md) ## analytics_sessions_details_retrieve - [GET /api/analytics/sessions/details/](https://docs.ibl.ai/apis/ibl/ai-analytics/analytics_sessions_details_retrieve.md) ## analytics_time_retrieve - [GET /api/analytics/time/](https://docs.ibl.ai/apis/ibl/ai-analytics/analytics_time_retrieve.md): Time Analytics API - User activity patterns by time of day and day of week. Provides heatmap data showing when users are most active, useful for: - Understanding peak usage times - Capacity planning and resource allocation - User behavior analysis - Support scheduling optimization Key Features: - Day of week patterns (0=Sunday through 6=Saturday) - Hour of day activity levels (0-23) - Flexible date range filtering - Platform and mentor-specific filtering - Message count aggregation Data Structure: - day_of_week: 0-6 (Sunday-Saturday) - hour: 0-23 (24-hour format) - value: Message count for that time slot ## analytics_topics_retrieve - [GET /api/analytics/topics/](https://docs.ibl.ai/apis/ibl/ai-analytics/analytics_topics_retrieve.md) ## analytics_topics_details_retrieve - [GET /api/analytics/topics/details/](https://docs.ibl.ai/apis/ibl/ai-analytics/analytics_topics_details_retrieve.md) ## analytics_users_retrieve - [GET /api/analytics/users/](https://docs.ibl.ai/apis/ibl/ai-analytics/analytics_users_retrieve.md): User Analytics API - Comprehensive user activity metrics and trends. Provides real-time and historical user analytics including: - Currently active users (last hour) - Active users over time periods (7d, 30d, 90d) - Registered user counts and growth - Time series charts with customizable granularity Key Features: - Real-time active user counting - Percentage change calculations vs previous periods - Flexible date filtering and granularity - Platform and mentor-specific filtering - Forward-filled time series data Supported Metrics: - currently_active: Users active in last hour - active_users: Unique users in specified period - registered_users: Total and new user counts ## analytics_users_details_retrieve - [GET /api/analytics/users/details/](https://docs.ibl.ai/apis/ibl/ai-analytics/analytics_users_details_retrieve.md): User Details API - Comprehensive user activity details with search and filtering. Provides detailed user information including: - User contact information (email, full name) - Activity metrics (message count, last activity) - Search functionality across multiple fields - Flexible date range filtering - CSV export capability Key Features: - Full-text search across email, name, and user ID - Date range filtering for activity periods - Platform and mentor-specific filtering - Comprehensive pagination with metadata - CSV export for data analysis - User aggregation across platforms/mentors Search Capabilities: - Email address matching - Full name search - User ID lookup - Partial string matching (case-insensitive) Export Options: - JSON response (default) - CSV export (?export=csv) - Includes all user fields in export ## Get Content Analytics - [GET /api/analytics/content/](https://docs.ibl.ai/apis/ibl/analytics/get_content_analytics.md): Retrieve aggregated analytics for catalog content (courses, programs, pathways, skills). Returns both summary statistics and paginated list of content items with individual analytics. When a platform_key is provided, results are filtered to show only content consumed by learners associated with that platform. Metrics supported: - course or courses: Course analytics with time spent - program or programs: Program analytics - pathway or pathways: Pathway analytics - skill or skills: Skill analytics Platform Filtering: - Without platform_key: Shows global analytics across all platforms - With platform_key: Shows analytics filtered by platform learners only Time Spent Analytics: - Platform-level: Total time spent across all content and average per learner - Course-level: Total time spent per course and average per enrolled learner - Time values are provided in seconds for precision - Overtime: Time series data showing platform time spent over last 7 days (courses only, and include_overtime=true) External Content: - Content not owned by the requesting platform but used by its learners is marked as "external" - External content has limited metadata exposure for privacy ## Get Content Details - [GET /api/analytics/content/details/{content_id}/](https://docs.ibl.ai/apis/ibl/analytics/get_content_details.md): Retrieve detailed analytics for a specific content item including summary statistics, learner-level data, and optional time series information. ## analytics_financial_retrieve - [GET /api/analytics/financial/](https://docs.ibl.ai/apis/ibl/analytics/analytics_financial_retrieve.md): Financial Analytics API - Get comprehensive cost metrics with comparison analysis. This endpoint provides period-based cost analysis (not cumulative) with support for: - Multiple time granularities and metrics - Cross-dimensional filtering - Percentage change vs comparison periods - Forward-filled time series Examples: Basic Weekly Costs: GET /api/analytics/financial/?metric=weekly_costs&comparison_days=10 Platform & Mentor Filtered: # Get total costs for a specific platform and mentor GET /api/analytics/financial/?metric=total_costs&platform_key=web-app&mentor_unique_id=mentor-123&comparison_days=14 Monthly Costs by Provider: GET /api/analytics/financial/?metric=monthly_costs&provider=openai&granularity=month&comparison_days=30 Daily Costs for Specific User: GET /api/analytics/financial/?metric=total_costs&username=user-456&granularity=day&start_date=2025-01-15&end_date=2025-01-21&comparison_days=7 Response Structure: json { "metric": "weekly_costs", "value": 12.47, "percentage_change": 8.5, "overtime": [ {"date": "2025-01-06", "value": 2.89}, {"date": "2025-01-13", "value": 3.12} ], "period_info": { "start_date": "2025-01-01", "end_date": "2025-01-31", "period_days": 31 }, "comparison_info": { "previous_period_value": 11.50, ... } } ## analytics_financial_details_retrieve - [GET /api/analytics/financial/details/](https://docs.ibl.ai/apis/ibl/analytics/analytics_financial_details_retrieve.md): Financial Details Analytics API – paginated cost tables with flexible grouping. This endpoint returns tabular cost metrics aggregated by the dimension specified via the group_by query parameter. One or more KPI columns can be requested through the comma-separated metrics list while typical filters (date range, provider, platform_key, user, etc.) narrow the dataset. Results are paginated with page / limit. Required query parameters - group_by – provider | llm_model | username | mentor | platform - metrics – csv list of KPI names, e.g. total_cost, sessions Shared optional filters - start_date, end_date – ISO yyyy-mm-dd (ignored when all_time=true) - platform_key – tenant isolation - mentor_unique_id – filter to one mentor - username – filter to a learner - provider / llm_model – filter to LLM provider / model - all_time – true → lifetime totals - page (default 1), limit (default 50) Examples -------- 1. Cost by provider for the last week GET /api/v2/analytics/financial/details? group_by=provider& metrics=total_cost& start_date=2025-01-01& end_date=2025-01-07& page=1&limit=10 2. Lifetime cost per user with extra KPIs GET /api/v2/analytics/financial/details? group_by=username& metrics=total_cost,sessions& all_time=true&page=1&limit=50 3. Cost by LLM model with tenant filter GET /api/v2/analytics/financial/details? group_by=llm_model& metrics=total_cost& platform_key=web-app& start_date=2025-01-01&end_date=2025-01-31 Response structure ------------------- `` { "page": 1, "limit": 10, "total_pages": 1, "total_records": 3, "rows": [ {"provider": "openai", "total_cost": "2.50000"}, {"provider": "anthropic", "total_cost": "1.00000"}, {"provider": "azure", "total_cost": "0.50000"} ], "metrics": [ { "name": "total_cost", "unit": "$", "description": "Cost for this entity in period" } ], "total_cost": "4.00000" // optional grand-total when available } ` ## analytics_financial_invoice_retrieve - [GET /api/analytics/financial/invoice/](https://docs.ibl.ai/apis/ibl/analytics/analytics_financial_invoice_retrieve.md): Flexible Invoice Report API – Billing summary with username and platform filtering. This endpoint generates invoice reports with flexible filtering options: - Platform admins can view their platform's data and filter by username within their platform - Super admins can view any combination of username/platform or global summaries Key Features: - Flexible filtering by username and/or platform_key - Essential metrics: total cost, sessions, usage period - Provider breakdown (OpenAI, Anthropic, etc.) - Top mentors/actions by cost - Clean, invoice-ready format Query Parameters: - username: Filter by specific username (optional) - platform_key: Filter by platform (optional, but required for platform admins) - start_date, end_date: billing period (defaults to last 30 days) - include_breakdown: show provider/mentor details (default: true) Permission Logic: - Platform admins: Must include platform_key matching their permission scope - Super admins: Can use any combination of filters or none (global summary) Examples: # Platform admin viewing their platform GET /api/analytics/financial/invoice?platform_key=web-app # Platform admin viewing specific user in their platform GET /api/analytics/financial/invoice?platform_key=web-app&username=john.doe # Super admin viewing specific user across all platforms GET /api/analytics/financial/invoice?username=john.doe # Super admin viewing global summary GET /api/analytics/financial/invoice Response Structure: json { "entity": { "type": "user|platform|global", "username": "john.doe", "platform_key": "web-app", "platform_name": "Web Application", "display_name": "John Doe on Web Application" }, "billing_period": { "start_date": "2025-01-01", "end_date": "2025-01-31", "days": 31 }, "summary": { "total_cost": 245.750, "total_sessions": 1250, "active_users": 85, "cost_per_session": 0.196 }, "breakdown": { "by_provider": [...], "by_mentor": [...], "by_action": [...] } } ## analytics_learners_retrieve - [GET /api/analytics/learners/](https://docs.ibl.ai/apis/ibl/analytics/analytics_learners_retrieve.md): Unified API endpoint for learner analytics. This endpoint provides either: 1. Cross-platform summary (when only username is provided) 2. Platform-specific detailed data (when username + platform_key are provided) Query params: - username (required): Username of the learner - platform_key (optional): Platform key for platform-specific data - page (optional): Page number (default: 1) - limit (optional): Records per page (default: 20, max: 100) Returns: - If platform_key provided: Detailed platform metrics - If no platform_key: Cross-platform summary with pagination ## analytics_learners_list_retrieve - [GET /api/analytics/learners/list/](https://docs.ibl.ai/apis/ibl/analytics/analytics_learners_list_retrieve.md): Retrieve a paginated list of learners for a specific platform with their comprehensive metrics from the UserPlatformSummary materialized view. This endpoint is accessible only to platform administrators and supports search, sorting, and pagination. ## analytics_messages_retrieve - [GET /api/analytics/messages/](https://docs.ibl.ai/apis/ibl/analytics/analytics_messages_retrieve.md): Conversation list endpoint for analytics. Query params (all optional unless specified by permissions): - platform_key: filter by platform - mentor_unique_id: filter by mentor - page: page number (default 1) - limit: page size (default 20, max 100) - search: search in user name and first user message - min_messages, max_messages: message_count range - sentiment: positive|negative|neutral - topic: topic name contains - start_date, end_date: date filter on conversation date Returns: summary totals, results list (paginated), and pagination metadata. ## analytics_messages_details_retrieve - [GET /api/analytics/messages/details/](https://docs.ibl.ai/apis/ibl/analytics/analytics_messages_details_retrieve.md): Conversation detail endpoint for analytics. Query params: - session_id (required): UUID of the session to fetch - platform_key, mentor_unique_id (optional): further scope - start_date, end_date (optional): date filter on message timestamps Returns: summary metadata from conversation_list MV, and a list of human/ai message pairs in chronological order. ## analytics_ratings_retrieve - [GET /api/analytics/ratings/](https://docs.ibl.ai/apis/ibl/analytics/analytics_ratings_retrieve.md): Ratings overtime endpoint. Query params: - metric: only 'ratings' is supported (default) - platform_key, mentor_unique_id: optional filters - granularity: 'day' (default) or 'hour' (hour only for today) - start_date, end_date: optional date range; defaults applied if not provided Returns: { metric: 'ratings', points: [{date, value}, ...] } ## analytics_sessions_retrieve - [GET /api/analytics/sessions/](https://docs.ibl.ai/apis/ibl/analytics/analytics_sessions_retrieve.md) ## analytics_sessions_details_retrieve - [GET /api/analytics/sessions/details/](https://docs.ibl.ai/apis/ibl/analytics/analytics_sessions_details_retrieve.md) ## analytics_time_retrieve - [GET /api/analytics/time/](https://docs.ibl.ai/apis/ibl/analytics/analytics_time_retrieve.md): Time Analytics API - User activity patterns by time of day and day of week. Provides heatmap data showing when users are most active, useful for: - Understanding peak usage times - Capacity planning and resource allocation - User behavior analysis - Support scheduling optimization Key Features: - Day of week patterns (0=Sunday through 6=Saturday) - Hour of day activity levels (0-23) - Flexible date range filtering - Platform and mentor-specific filtering - Message count aggregation Data Structure: - day_of_week: 0-6 (Sunday-Saturday) - hour: 0-23 (24-hour format) - value: Message count for that time slot ## analytics_topics_retrieve - [GET /api/analytics/topics/](https://docs.ibl.ai/apis/ibl/analytics/analytics_topics_retrieve.md) ## analytics_topics_details_retrieve - [GET /api/analytics/topics/details/](https://docs.ibl.ai/apis/ibl/analytics/analytics_topics_details_retrieve.md) ## analytics_users_retrieve - [GET /api/analytics/users/](https://docs.ibl.ai/apis/ibl/analytics/analytics_users_retrieve.md): User Analytics API - Comprehensive user activity metrics and trends. Provides real-time and historical user analytics including: - Currently active users (last hour) - Active users over time periods (7d, 30d, 90d) - Registered user counts and growth - Time series charts with customizable granularity Key Features: - Real-time active user counting - Percentage change calculations vs previous periods - Flexible date filtering and granularity - Platform and mentor-specific filtering - Forward-filled time series data Supported Metrics: - currently_active: Users active in last hour - active_users: Unique users in specified period - registered_users: Total and new user counts ## analytics_users_details_retrieve - [GET /api/analytics/users/details/](https://docs.ibl.ai/apis/ibl/analytics/analytics_users_details_retrieve.md): User Details API - Comprehensive user activity details with search and filtering. Provides detailed user information including: - User contact information (email, full name) - Activity metrics (message count, last activity) - Search functionality across multiple fields - Flexible date range filtering - CSV export capability Key Features: - Full-text search across email, name, and user ID - Date range filtering for activity periods - Platform and mentor-specific filtering - Comprehensive pagination with metadata - CSV export for data analysis - User aggregation across platforms/mentors Search Capabilities: - Email address matching - Full name search - User ID lookup - Partial string matching (case-insensitive) Export Options: - JSON response (default) - CSV export (?export=csv) - Includes all user fields in export