RATIO MACHINA STARTER logo

MERCURY

PersonaMonitorJobs REST API

The PersonaMonitorJobs REST API manages the configuration and scheduling of monitoring tasks for AI personas. Define monitoring parameters, schedules, and alert conditions for continuous performance tracking.

Base URL & Authentication

Base URL: https://your-api-name.mercury.ratiomachina.com
Authentication: x-mercury-api-key: YOUR_API_KEY

List Monitor Jobs

GET /persona-monitor-jobs

Query Parameters

  • limit - Number of results (default: 50, max: 100)
  • offset - Skip results for pagination
  • personaId - Filter by persona ID
  • status - Filter by job status (active, paused, stopped)
  • monitorId - Filter by monitor configuration ID

Response Example

{
  "jobs": [
    {
      "id": "uuid-job-123",
      "monitorId": "uuid-monitor-456",
      "personaId": "uuid-persona-789",
      "personaName": "Sales Assistant Alex",
      "name": "Daily Performance Monitor",
      "description": "Monitor sales conversations for response quality and conversion rates",
      "status": "active",
      "schedule": {
        "type": "cron",
        "expression": "0 9 * * 1-5",
        "timezone": "UTC",
        "nextRun": "2024-01-16T09:00:00Z"
      },
      "configuration": {
        "metrics": ["response_time", "satisfaction_score", "conversion_rate"],
        "alertThresholds": {
          "maxResponseTime": 30000,
          "minSatisfactionScore": 4.0,
          "minConversionRate": 0.15
        },
        "dataRetentionDays": 90,
        "includeTranscripts": false
      },
      "lastRun": {
        "id": "uuid-run-345",
        "startedAt": "2024-01-15T09:00:00Z",
        "completedAt": "2024-01-15T09:45:00Z",
        "status": "completed",
        "summary": "Processed 89 conversations, all metrics within thresholds"
      },
      "createdAt": "2024-01-01T12:00:00Z",
      "updatedAt": "2024-01-15T09:45:00Z"
    }
  ],
  "pagination": {
    "total": 23,
    "limit": 50,
    "offset": 0,
    "hasNext": false,
    "hasPrev": false
  }
}

Create Monitor Job

POST /persona-monitor-jobs

Request Body

{
  "monitorId": "uuid-monitor-456",
  "personaId": "uuid-persona-789",
  "name": "Customer Support Quality Monitor",
  "description": "Monitor support conversations for resolution time and customer satisfaction",
  "schedule": {
    "type": "interval",
    "intervalMinutes": 60,
    "timezone": "America/New_York"
  },
  "configuration": {
    "metrics": [
      "response_time",
      "resolution_time", 
      "satisfaction_score",
      "escalation_rate"
    ],
    "alertThresholds": {
      "maxResponseTime": 120000,
      "maxResolutionTime": 3600000,
      "minSatisfactionScore": 3.5,
      "maxEscalationRate": 0.10
    },
    "filters": {
      "conversationTypes": ["support_ticket", "live_chat"],
      "priorities": ["medium", "high", "critical"],
      "timeRange": "last_24_hours"
    },
    "notifications": {
      "email": ["support-manager@company.com"],
      "webhook": "https://your-system.com/webhooks/monitoring-alerts",
      "slack": "#support-alerts"
    },
    "dataRetentionDays": 365,
    "includeTranscripts": true,
    "detailedReports": true
  },
  "isActive": true
}

Response Example

{
  "job": {
    "id": "uuid-job-890",
    "monitorId": "uuid-monitor-456",
    "personaId": "uuid-persona-789",
    "personaName": "Customer Support Specialist",
    "name": "Customer Support Quality Monitor",
    "description": "Monitor support conversations for resolution time and customer satisfaction",
    "status": "active",
    "schedule": {
      "type": "interval",
      "intervalMinutes": 60,
      "timezone": "America/New_York",
      "nextRun": "2024-01-15T16:00:00Z"
    },
    "configuration": {
      "metrics": ["response_time", "resolution_time", "satisfaction_score", "escalation_rate"],
      "alertThresholds": {
        "maxResponseTime": 120000,
        "maxResolutionTime": 3600000,
        "minSatisfactionScore": 3.5,
        "maxEscalationRate": 0.10
      }
    },
    "createdAt": "2024-01-15T15:30:00Z",
    "updatedAt": "2024-01-15T15:30:00Z"
  }
}

Get Monitor Job

GET /persona-monitor-jobs/{id}

Path Parameters

  • id - Monitor job UUID

Query Parameters

  • includeHistory - Include recent run history
  • includeMetrics - Include performance metrics

Response Example

{
  "job": {
    "id": "uuid-job-890",
    "monitorId": "uuid-monitor-456",
    "personaId": "uuid-persona-789",
    "personaName": "Customer Support Specialist",
    "name": "Customer Support Quality Monitor",
    "status": "active",
    "schedule": {
      "type": "interval",
      "intervalMinutes": 60,
      "timezone": "America/New_York",
      "nextRun": "2024-01-15T17:00:00Z",
      "lastRun": "2024-01-15T16:00:00Z"
    },
    "performance": {
      "totalRuns": 145,
      "successfulRuns": 142,
      "failedRuns": 3,
      "averageRunTime": 2400,
      "lastFailure": "2024-01-12T14:30:00Z"
    },
    "recentRuns": [
      {
        "id": "uuid-run-123",
        "startedAt": "2024-01-15T16:00:00Z",
        "completedAt": "2024-01-15T16:42:00Z",
        "status": "completed",
        "conversationsProcessed": 67,
        "alertsTriggered": 0
      }
    ],
    "createdAt": "2024-01-01T12:00:00Z",
    "updatedAt": "2024-01-15T16:42:00Z"
  }
}

PersonaMonitorJobs API Best Practices

Job Configuration

  • Set appropriate monitoring intervals based on conversation volume
  • Configure meaningful alert thresholds for proactive monitoring
  • Use descriptive names and descriptions for job management
  • Consider timezone settings for scheduled monitoring

Performance & Maintenance

  • Monitor job performance and adjust configurations as needed
  • Set up proper notification channels for alerts
  • Archive old jobs and clean up unused configurations
  • Review and update alert thresholds regularly
← PersonaMonitors APIPersonaMonitorRuns API →
Transcend the hype with MERCURY by Ratio Machina