The PersonaMonitors REST API provides comprehensive quality assurance and performance monitoring for AI personas. Monitor conversation quality, response accuracy, customer satisfaction, and identify areas for persona improvement through automated monitoring jobs and detailed analytics.
Base URL: https://your-api-name.mercury.ratiomachina.com Authentication: x-mercury-api-key: YOUR_API_KEY
limit - Number of results (default: 50, max: 100)offset - Skip results for paginationpersonaId - Filter by persona IDstatus - Filter by status (active, paused, inactive)monitorType - Filter by monitor typepriority - Filter by priority levelsortBy - Sort field (createdAt, name, lastRun)sortOrder - Sort direction (asc, desc){
"personaMonitors": [
{
"id": "uuid-monitor-123",
"externalId": "sales-quality-monitor-v1",
"name": "Sales Persona Quality Monitor",
"description": "Monitors conversation quality and response accuracy for sales personas",
"personaId": "uuid-persona-sales-alex",
"personaName": "Sales Assistant Alex",
"monitorType": "conversation_quality",
"status": "active",
"priority": "high",
"configuration": {
"metrics": ["response_accuracy", "customer_satisfaction", "conversion_rate"],
"thresholds": {
"response_accuracy": 0.85,
"customer_satisfaction": 0.8,
"conversion_rate": 0.15
},
"sampling": {
"rate": 0.1,
"method": "random",
"min_conversations_per_day": 5
},
"schedule": {
"frequency": "daily",
"time": "02:00",
"timezone": "UTC"
}
},
"alerts": {
"enabled": true,
"channels": ["email", "slack"],
"threshold_violations": 3,
"escalation_enabled": true
},
"lastRun": {
"timestamp": "2024-01-15T02:00:00Z",
"status": "completed",
"conversationsAnalyzed": 47,
"issuesDetected": 2,
"overallScore": 0.87
},
"statistics": {
"totalRuns": 156,
"averageScore": 0.89,
"trendsLastWeek": "improving",
"alertsTriggered": 8
},
"createdAt": "2024-01-01T10:00:00Z",
"updatedAt": "2024-01-15T02:00:00Z"
}
],
"pagination": {
"total": 23,
"limit": 50,
"offset": 0,
"hasNext": false,
"hasPrev": false
},
"summary": {
"totalMonitors": 23,
"activeMonitors": 19,
"pausedMonitors": 4,
"criticalAlerts": 2,
"monitorTypes": {
"conversation_quality": 8,
"response_accuracy": 6,
"performance": 5,
"compliance": 4
}
}
}{
"externalId": "support-accuracy-monitor-v2",
"name": "Support Response Accuracy Monitor",
"description": "Monitors technical support persona for response accuracy and resolution effectiveness",
"personaId": "uuid-persona-support-specialist",
"monitorType": "response_accuracy",
"priority": "high",
"configuration": {
"metrics": [
"technical_accuracy",
"response_completeness",
"issue_resolution_rate",
"customer_satisfaction",
"first_response_time"
],
"thresholds": {
"technical_accuracy": 0.92,
"response_completeness": 0.88,
"issue_resolution_rate": 0.75,
"customer_satisfaction": 0.85,
"first_response_time": 300
},
"sampling": {
"rate": 0.15,
"method": "stratified",
"stratification": "issue_complexity",
"min_conversations_per_day": 10,
"max_conversations_per_day": 100
},
"analysis_criteria": {
"include_conversation_types": ["technical_support", "troubleshooting"],
"exclude_conversation_types": ["billing", "sales"],
"min_message_count": 3,
"require_resolution": false,
"analysis_window_hours": 168
},
"schedule": {
"frequency": "daily",
"time": "03:00",
"timezone": "UTC",
"retry_on_failure": true,
"max_retries": 3
}
},
"alerts": {
"enabled": true,
"channels": ["email", "slack", "webhook"],
"recipients": ["support-manager@company.com"],
"webhook_url": "https://company.com/webhooks/monitor-alerts",
"threshold_violations": 2,
"escalation_enabled": true,
"escalation_after_hours": 4,
"escalation_recipients": ["vp-support@company.com"]
},
"reporting": {
"generate_reports": true,
"report_frequency": "weekly",
"report_recipients": ["support-team@company.com"],
"include_recommendations": true,
"include_conversation_samples": true
},
"status": "active"
}{
"personaMonitor": {
"id": "uuid-monitor-456",
"externalId": "support-accuracy-monitor-v2",
"name": "Support Response Accuracy Monitor",
"description": "Monitors technical support persona for response accuracy and resolution effectiveness",
"personaId": "uuid-persona-support-specialist",
"personaName": "Customer Support Specialist",
"monitorType": "response_accuracy",
"status": "active",
"priority": "high",
"configuration": {
"metrics": [
"technical_accuracy",
"response_completeness",
"issue_resolution_rate",
"customer_satisfaction",
"first_response_time"
],
"thresholds": {
"technical_accuracy": 0.92,
"response_completeness": 0.88,
"issue_resolution_rate": 0.75
},
"sampling": {
"rate": 0.15,
"method": "stratified",
"min_conversations_per_day": 10
},
"schedule": {
"frequency": "daily",
"time": "03:00",
"timezone": "UTC"
}
},
"alerts": {
"enabled": true,
"channels": ["email", "slack", "webhook"],
"threshold_violations": 2,
"escalation_enabled": true
},
"nextScheduledRun": "2024-01-16T03:00:00Z",
"statistics": {
"totalRuns": 0,
"averageScore": null,
"alertsTriggered": 0
},
"createdAt": "2024-01-15T16:30:00Z",
"updatedAt": "2024-01-15T16:30:00Z"
}
}id - Monitor UUID or external IDincludeResults - Include recent monitoring resultsincludeAlerts - Include alert historyincludeTrends - Include performance trendsresultsLimit - Limit number of results returnedtimeframe - Time range for trends (7d, 30d, 90d){
"personaMonitor": {
"id": "uuid-monitor-456",
"externalId": "support-accuracy-monitor-v2",
"name": "Support Response Accuracy Monitor",
"description": "Monitors technical support persona for response accuracy and resolution effectiveness",
"personaId": "uuid-persona-support-specialist",
"monitorType": "response_accuracy",
"status": "active",
"priority": "high",
"configuration": { ... },
"alerts": { ... },
"recentResults": [
{
"runId": "uuid-run-789",
"timestamp": "2024-01-15T03:00:00Z",
"status": "completed",
"metrics": {
"technical_accuracy": 0.94,
"response_completeness": 0.89,
"issue_resolution_rate": 0.78,
"customer_satisfaction": 0.87,
"first_response_time": 285
},
"conversationsAnalyzed": 23,
"issuesDetected": 1,
"overallScore": 0.91,
"thresholdViolations": []
},
{
"runId": "uuid-run-012",
"timestamp": "2024-01-14T03:00:00Z",
"status": "completed",
"metrics": {
"technical_accuracy": 0.91,
"response_completeness": 0.86,
"issue_resolution_rate": 0.73,
"customer_satisfaction": 0.82
},
"conversationsAnalyzed": 29,
"issuesDetected": 3,
"overallScore": 0.86,
"thresholdViolations": ["customer_satisfaction"]
}
],
"alertHistory": [
{
"alertId": "uuid-alert-345",
"triggeredAt": "2024-01-14T03:15:00Z",
"alertType": "threshold_violation",
"severity": "warning",
"metric": "customer_satisfaction",
"value": 0.82,
"threshold": 0.85,
"resolved": true,
"resolvedAt": "2024-01-15T03:00:00Z"
}
],
"performanceTrends": {
"timeframe": "30d",
"trendData": [
{
"date": "2024-01-15",
"overallScore": 0.91,
"conversationsAnalyzed": 23
},
{
"date": "2024-01-14",
"overallScore": 0.86,
"conversationsAnalyzed": 29
}
],
"trendAnalysis": {
"overall_direction": "improving",
"significant_changes": [],
"recommendations": [
"Continue current training approach",
"Focus on customer satisfaction improvements"
]
}
},
"statistics": {
"totalRuns": 45,
"averageScore": 0.88,
"bestScore": 0.95,
"worstScore": 0.78,
"alertsTriggered": 12,
"uptimePercentage": 98.9
}
}
}Update monitor configuration, thresholds, or alerting settings. Changes take effect on the next scheduled run.
{
"name": "Enhanced Support Accuracy Monitor",
"description": "Enhanced monitoring with expanded metrics and improved thresholds",
"configuration": {
"metrics": [
"technical_accuracy",
"response_completeness",
"issue_resolution_rate",
"customer_satisfaction",
"first_response_time",
"escalation_rate",
"knowledge_base_usage"
],
"thresholds": {
"technical_accuracy": 0.94,
"response_completeness": 0.90,
"issue_resolution_rate": 0.80,
"customer_satisfaction": 0.88,
"first_response_time": 240,
"escalation_rate": 0.15,
"knowledge_base_usage": 0.70
},
"sampling": {
"rate": 0.20,
"method": "stratified",
"min_conversations_per_day": 15
},
"schedule": {
"frequency": "daily",
"time": "02:30",
"timezone": "America/New_York"
}
},
"alerts": {
"enabled": true,
"channels": ["email", "slack", "webhook", "sms"],
"threshold_violations": 1,
"escalation_enabled": true,
"escalation_after_hours": 2,
"custom_conditions": [
{
"name": "critical_accuracy_drop",
"condition": "technical_accuracy < 0.85",
"severity": "critical",
"immediate_notification": true
},
{
"name": "high_escalation_rate",
"condition": "escalation_rate > 0.25",
"severity": "warning",
"requires_human_review": true
}
]
},
"priority": "critical"
}{
"personaMonitor": {
"id": "uuid-monitor-456",
"externalId": "support-accuracy-monitor-v2",
"name": "Enhanced Support Accuracy Monitor",
"description": "Enhanced monitoring with expanded metrics and improved thresholds",
"personaId": "uuid-persona-support-specialist",
"monitorType": "response_accuracy",
"status": "active",
"priority": "critical",
"configuration": {
"metrics": [
"technical_accuracy",
"response_completeness",
"issue_resolution_rate",
"customer_satisfaction",
"first_response_time",
"escalation_rate",
"knowledge_base_usage"
],
"thresholds": {
"technical_accuracy": 0.94,
"response_completeness": 0.90,
"customer_satisfaction": 0.88
},
"sampling": {
"rate": 0.20,
"method": "stratified",
"min_conversations_per_day": 15
},
"schedule": {
"frequency": "daily",
"time": "02:30",
"timezone": "America/New_York"
}
},
"alerts": {
"enabled": true,
"channels": ["email", "slack", "webhook", "sms"],
"threshold_violations": 1,
"escalation_enabled": true,
"custom_conditions": [
{
"name": "critical_accuracy_drop",
"condition": "technical_accuracy < 0.85",
"severity": "critical"
}
]
},
"nextScheduledRun": "2024-01-16T07:30:00Z",
"configurationChanges": [
"Added escalation_rate and knowledge_base_usage metrics",
"Updated thresholds for improved accuracy",
"Changed timezone to America/New_York",
"Added custom alert conditions"
],
"updatedAt": "2024-01-15T17:15:00Z"
}
}⚠️ Warning: Deleting a monitor will stop all scheduled runs and remove historical data. Consider pausing the monitor instead to preserve data while stopping execution.
id - Monitor UUID or external IDpreserveData - Archive data before deletioncancelActiveJobs - Cancel any running monitoring jobsnotifyStakeholders - Send deletion notifications{
"message": "Persona monitor deleted successfully",
"deletedMonitor": {
"id": "uuid-monitor-456",
"externalId": "support-accuracy-monitor-v2",
"name": "Enhanced Support Accuracy Monitor",
"personaName": "Customer Support Specialist"
},
"impactSummary": {
"scheduledJobsCancelled": 1,
"historicalRunsArchived": 45,
"alertsDeactivated": 3,
"dataPreserved": true,
"archiveLocation": "s3://monitoring-archives/persona-monitor-456-20240115.json"
},
"cleanup": {
"webhookUnregistered": true,
"notificationsSent": true,
"stakeholdersNotified": ["support-manager@company.com"],
"dependentJobsHandled": true
}
}Retrieve detailed results from monitor runs including metrics, analysis, and recommendations.
limit - Number of results to returnstartDate - Filter results after dateendDate - Filter results before datestatus - Filter by run statusincludeDetails - Include detailed analysisincludeConversationSamples - Include conversation examples{
"monitorResults": [
{
"runId": "uuid-run-789",
"monitorId": "uuid-monitor-456",
"timestamp": "2024-01-15T03:00:00Z",
"status": "completed",
"executionTime": "4m 32s",
"metrics": {
"technical_accuracy": 0.94,
"response_completeness": 0.89,
"issue_resolution_rate": 0.78,
"customer_satisfaction": 0.87,
"first_response_time": 285,
"escalation_rate": 0.12,
"knowledge_base_usage": 0.73
},
"analysis": {
"conversationsAnalyzed": 23,
"issuesDetected": 1,
"overallScore": 0.91,
"performanceGrade": "A-",
"strengths": [
"Excellent technical accuracy",
"Strong knowledge base utilization",
"Consistent response times"
],
"improvementAreas": [
"Customer satisfaction could be higher",
"Issue resolution rate below target"
],
"recommendations": [
"Review conversation samples with low satisfaction scores",
"Provide additional training on complex issue resolution",
"Consider expanding knowledge base with common issues"
]
},
"thresholdViolations": [],
"conversationSamples": [
{
"conversationId": "uuid-conv-sample-1",
"score": 0.95,
"strengths": ["accurate_diagnosis", "clear_explanation"],
"sample_type": "high_performing"
},
{
"conversationId": "uuid-conv-sample-2",
"score": 0.72,
"issues": ["incomplete_response", "customer_confusion"],
"sample_type": "needs_improvement"
}
],
"trends": {
"compared_to_previous": {
"overall_score": "+0.05",
"technical_accuracy": "+0.03",
"customer_satisfaction": "+0.05"
},
"7_day_trend": "improving",
"30_day_trend": "stable"
}
}
],
"summary": {
"totalResults": 45,
"timeRange": "2024-01-01 to 2024-01-15",
"averageScore": 0.88,
"trendDirection": "improving",
"criticalIssues": 0,
"recommendationsCount": 12
}
}Activate a paused or inactive monitor to resume scheduled monitoring runs.
{
"immediate_run": true,
"reset_alerts": false,
"activation_note": "Resuming monitoring after persona updates"
}{
"message": "Monitor activated successfully",
"monitor": {
"id": "uuid-monitor-456",
"name": "Enhanced Support Accuracy Monitor",
"status": "active",
"nextScheduledRun": "2024-01-16T07:30:00Z"
},
"activation": {
"activatedAt": "2024-01-15T17:45:00Z",
"immediateRunScheduled": true,
"immediateRunId": "uuid-run-immediate-123"
}
}