get_analytics_timeseries
Retrieve time-series analytics data for creating charts, dashboards, and tracking trends over time in Kaltura media platforms.
Instructions
Get time-series analytics data optimized for charts and visualizations. Use this when creating graphs, dashboards, or tracking trends over time.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| from_date | Yes | Start date in YYYY-MM-DD format (e.g., '2024-01-01') | |
| to_date | Yes | End date in YYYY-MM-DD format (e.g., '2024-01-31') | |
| report_type | No | Report type (default: 'content') | |
| metrics | No | Metrics to include (e.g., ['plays', 'views']) | |
| entry_id | No | Optional: Track single video's performance over time (e.g., '1_abc123'). Leave empty for platform-wide trends. | |
| interval | No | Time grouping for data points (default: 'days'). Use 'hours' for <7 day ranges, 'days' for monthly, 'weeks' for quarterly, 'months' for yearly views. Affects data granularity. |
Implementation Reference
- Main handler function that implements the tool logic: validates inputs, sets default metrics based on report_type, calls the core get_analytics_graph function, reformats the response into a time-series 'series' structure optimized for charts and visualizations.
async def get_analytics_timeseries( manager: KalturaClientManager, from_date: str, to_date: str, report_type: str = "content", metrics: Optional[List[str]] = None, entry_id: Optional[str] = None, interval: str = "days", dimension: Optional[str] = None, ) -> str: """ Get time-series analytics data optimized for charts and visualizations. This function returns analytics data as time-series with consistent intervals, perfect for creating line charts, area charts, and trend visualizations. USE WHEN: - Creating charts or graphs showing trends over time - Building dashboards with visual analytics - Comparing metrics across different time periods - Showing growth or decline patterns - Visualizing seasonal trends Args: manager: Kaltura client manager from_date: Start date (YYYY-MM-DD) to_date: End date (YYYY-MM-DD) report_type: Type of report (default: "content") metrics: List of metrics to include (e.g., ["plays", "views", "avg_time"]) entry_id: Optional specific entry ID interval: Time interval - "hours", "days", "weeks", "months" (default: "days") dimension: Optional dimension for grouping Returns: JSON with time-series data formatted for visualization: { "series": [ { "metric": "count_plays", "data": [{"date": "2024-01-01", "value": 150}, ...] }, { "metric": "unique_viewers", "data": [{"date": "2024-01-01", "value": 89}, ...] } ], "metadata": {...} } Examples: # Daily play counts for a video get_analytics_timeseries(manager, from_date, to_date, entry_id="1_abc", metrics=["plays"]) # Monthly platform trends get_analytics_timeseries(manager, from_date, to_date, interval="months", report_type="platforms") """ from .analytics_core import get_analytics_graph # If no metrics specified, use common ones based on report type if not metrics: metrics_map = { "content": ["count_plays", "unique_viewers", "avg_time_viewed"], "user_engagement": ["count_plays", "unique_known_users", "avg_completion_rate"], "geographic": ["count_plays", "unique_viewers"], "platforms": ["count_plays", "unique_viewers"], } metrics = metrics_map.get(report_type, ["count_plays", "unique_viewers"]) result = await get_analytics_graph( manager=manager, from_date=from_date, to_date=to_date, report_type=report_type, entry_id=entry_id, interval=interval, dimension=dimension, ) # Reformat to emphasize time-series nature data = json.loads(result) if "graphs" in data: # Rename "graphs" to "series" for clarity data["series"] = data.pop("graphs") # Add interval metadata data["metadata"] = { "interval": interval, "report_type": report_type, "date_range": data.get("dateRange", {}), } return json.dumps(data, indent=2) - src/kaltura_mcp/server.py:147-181 (schema)MCP tool schema registration defining input parameters, types, descriptions, enums, and required fields for get_analytics_timeseries.
name="get_analytics_timeseries", description="Get time-series analytics data optimized for charts and visualizations. Use this when creating graphs, dashboards, or tracking trends over time.", inputSchema={ "type": "object", "properties": { "from_date": { "type": "string", "description": "Start date in YYYY-MM-DD format (e.g., '2024-01-01')", }, "to_date": { "type": "string", "description": "End date in YYYY-MM-DD format (e.g., '2024-01-31')", }, "report_type": { "type": "string", "description": "Report type (default: 'content')", }, "metrics": { "type": "array", "items": {"type": "string"}, "description": "Metrics to include (e.g., ['plays', 'views'])", }, "entry_id": { "type": "string", "description": "Optional: Track single video's performance over time (e.g., '1_abc123'). Leave empty for platform-wide trends.", }, "interval": { "type": "string", "enum": ["hours", "days", "weeks", "months"], "description": "Time grouping for data points (default: 'days'). Use 'hours' for <7 day ranges, 'days' for monthly, 'weeks' for quarterly, 'months' for yearly views. Affects data granularity.", }, }, "required": ["from_date", "to_date"], }, ), - src/kaltura_mcp/server.py:32-49 (registration)Import statement registering the get_analytics_timeseries handler function from tools module into the MCP server.
from .tools import ( get_analytics, get_analytics_timeseries, get_attachment_content, get_caption_content, get_download_url, get_geographic_breakdown, get_media_entry, get_quality_metrics, get_realtime_metrics, get_thumbnail_url, get_video_retention, list_analytics_capabilities, list_attachment_assets, list_caption_assets, list_categories, search_entries_intelligent, ) - src/kaltura_mcp/server.py:497-530 (registration)Dispatch logic in MCP server's call_tool method that routes calls to the get_analytics_timeseries handler when the tool name matches.
if name == "get_media_entry": result = await get_media_entry(kaltura_manager, **arguments) elif name == "list_categories": result = await list_categories(kaltura_manager, **arguments) elif name == "get_analytics": result = await get_analytics(kaltura_manager, **arguments) elif name == "get_analytics_timeseries": result = await get_analytics_timeseries(kaltura_manager, **arguments) elif name == "get_video_retention": result = await get_video_retention(kaltura_manager, **arguments) elif name == "get_realtime_metrics": result = await get_realtime_metrics(kaltura_manager, **arguments) elif name == "get_quality_metrics": result = await get_quality_metrics(kaltura_manager, **arguments) elif name == "get_geographic_breakdown": result = await get_geographic_breakdown(kaltura_manager, **arguments) elif name == "list_analytics_capabilities": result = await list_analytics_capabilities(kaltura_manager, **arguments) elif name == "get_download_url": result = await get_download_url(kaltura_manager, **arguments) elif name == "get_thumbnail_url": result = await get_thumbnail_url(kaltura_manager, **arguments) elif name == "search_entries": result = await search_entries_intelligent(kaltura_manager, **arguments) elif name == "list_caption_assets": result = await list_caption_assets(kaltura_manager, **arguments) elif name == "get_caption_content": result = await get_caption_content(kaltura_manager, **arguments) elif name == "list_attachment_assets": result = await list_attachment_assets(kaltura_manager, **arguments) elif name == "get_attachment_content": result = await get_attachment_content(kaltura_manager, **arguments) else: return [types.TextContent(type="text", text=f"Unknown tool: {name}")] - Helper metadata in list_analytics_capabilities describing the tool's purpose, use cases, and example usage for LLM discovery.
"function": "get_analytics_timeseries", "purpose": "Time-series data for visualization", "use_cases": [ "Creating charts and graphs", "Trend analysis over time", "Dashboard visualizations", "Growth tracking", ], "example": "get_analytics_timeseries(manager, from_date, to_date, interval='days')", },