Monitoring API

GET

/v1/usage

GET

/v1/health

GET

/v1/audit

The Monitoring API provides comprehensive analytics, usage tracking, and system health monitoring for your Cortex integration.

📊 Usage Analytics

GET
`/v1/usage`

Get detailed usage statistics and analytics for your API key.

curl -X GET "https://api.usecortex.co/v1/usage" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Parameter	Type	Default	Description
`period`	string	`month`	Time period: hour, day, week, month, year
`start_date`	string	`null`	Start date (ISO 8601)
`end_date`	string	`null`	End date (ISO 8601)
`breakdown`	string	`day`	Breakdown by: hour, day, week
`include_details`	boolean	`false`	Include detailed metrics

Response

{
  "success": true,
  "data": {
    "current_period": {
      "requests_used": 1847,
      "requests_limit": 10000,
      "usage_percentage": 18.47,
      "reset_date": "2025-02-01T00:00:00Z",
      "days_until_reset": 23
    },
    "usage_breakdown": [
      {
        "date": "2025-01-09",
        "requests": 156,
        "success_rate": 0.94,
        "avg_response_time": 2.3,
        "cache_hit_rate": 0.67
      },
      {
        "date": "2025-01-08", 
        "requests": 203,
        "success_rate": 0.91,
        "avg_response_time": 2.8,
        "cache_hit_rate": 0.72
      }
    ],
    "endpoint_usage": {
      "/v1/search": {
        "requests": 1205,
        "percentage": 65.3,
        "avg_response_time": 2.4,
        "success_rate": 0.93
      },
      "/v1/extract": {
        "requests": 387,
        "percentage": 21.0,
        "avg_response_time": 1.8,
        "success_rate": 0.96
      },
      "/v1/validate": {
        "requests": 255,
        "percentage": 13.8,
        "avg_response_time": 3.2,
        "success_rate": 0.89
      }
    },
    "performance_metrics": {
      "avg_response_time": 2.34,
      "p95_response_time": 4.12,
      "p99_response_time": 6.78,
      "success_rate": 0.932,
      "error_rate": 0.068,
      "cache_hit_rate": 0.694
    }
  }
}

🏥 Health Monitoring

GET
`/v1/health`

Check system health and service status.

curl -X GET "https://api.usecortex.co/v1/health" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "status": "healthy",
    "timestamp": "2025-01-09T15:30:00Z",
    "version": "v1.2.3",
    "uptime": 99.97,
    "services": {
      "search_engine": {
        "status": "healthy",
        "response_time": 1.23,
        "last_check": "2025-01-09T15:29:00Z"
      },
      "validation_service": {
        "status": "healthy", 
        "response_time": 2.45,
        "last_check": "2025-01-09T15:29:00Z"
      },
      "cache_layer": {
        "status": "healthy",
        "hit_rate": 0.78,
        "last_check": "2025-01-09T15:29:00Z"
      },
      "database": {
        "status": "healthy",
        "connection_pool": "85% utilized",
        "last_check": "2025-01-09T15:29:00Z"
      }
    },
    "regions": {
      "us-east": {
        "status": "healthy",
        "latency": 45,
        "load": 0.67
      },
      "us-west": {
        "status": "healthy", 
        "latency": 38,
        "load": 0.54
      },
      "europe": {
        "status": "healthy",
        "latency": 52,
        "load": 0.71
      }
    },
    "recent_incidents": []
  }
}

📋 Audit Logs

GET
`/v1/audit`

Access detailed audit logs for compliance and debugging.

curl -X GET "https://api.usecortex.co/v1/audit?limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	`50`	Number of entries to return (1-1000)
`offset`	integer	`0`	Pagination offset
`start_date`	string	`null`	Filter by start date
`end_date`	string	`null`	Filter by end date
`endpoint`	string	`null`	Filter by endpoint
`status`	string	`null`	Filter by status (success, error)
`request_id`	string	`null`	Specific request ID

Response

{
  "success": true,
  "data": {
    "entries": [
      {
        "request_id": "req_8f3a2b1c9d4e5f67",
        "timestamp": "2025-01-09T15:30:15Z",
        "endpoint": "/v1/search",
        "method": "POST",
        "status": 200,
        "response_time": 2.34,
        "ip_address": "192.168.1.100",
        "user_agent": "cortex-python-sdk/1.0.0",
        "request_size": 156,
        "response_size": 3420,
        "cache_hit": true,
        "region": "us-east",
        "query_hash": "sha256:abc123...",
        "sources_analyzed": 8,
        "confidence_score": 0.91
      },
      {
        "request_id": "req_7d2c1a9b8e7f6543",
        "timestamp": "2025-01-09T15:28:42Z",
        "endpoint": "/v1/validate",
        "method": "POST", 
        "status": 200,
        "response_time": 3.12,
        "ip_address": "192.168.1.100",
        "validation_result": "VERIFIED",
        "sources_checked": 5,
        "consensus_level": "STRONG"
      }
    ],
    "pagination": {
      "total": 5643,
      "limit": 100,
      "offset": 0,
      "has_more": true
    },
    "summary": {
      "total_requests": 5643,
      "success_rate": 0.943,
      "avg_response_time": 2.67,
      "unique_ips": 12,
      "top_endpoints": [
        "/v1/search",
        "/v1/extract",
        "/v1/validate"
      ]
    }
  }
}

📈 Real-time Metrics

GET
`/v1/metrics/live`

Get real-time performance metrics and alerts.

curl -X GET "https://api.usecortex.co/v1/metrics/live" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "current_load": {
      "requests_per_minute": 45,
      "active_connections": 12,
      "queue_depth": 3,
      "cpu_usage": 0.67,
      "memory_usage": 0.54
    },
    "last_5_minutes": {
      "total_requests": 225,
      "successful_requests": 210,
      "failed_requests": 15,
      "avg_response_time": 2.1,
      "cache_hits": 156,
      "cache_misses": 69
    },
    "alerts": [
      {
        "level": "warning",
        "message": "Response time elevated (3.2s avg)",
        "timestamp": "2025-01-09T15:25:00Z",
        "duration": 300
      }
    ],
    "trending": {
      "response_time": "stable",
      "error_rate": "decreasing", 
      "cache_hit_rate": "increasing",
      "request_volume": "increasing"
    }
  }
}

🚨 Error Analytics

GET
`/v1/errors`

Analyze error patterns and troubleshoot issues.

curl -X GET "https://api.usecortex.co/v1/errors?period=day" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "error_summary": {
      "total_errors": 67,
      "error_rate": 0.036,
      "most_common_error": "TIMEOUT_EXCEEDED",
      "error_trend": "decreasing"
    },
    "error_breakdown": [
      {
        "error_code": "TIMEOUT_EXCEEDED",
        "count": 23,
        "percentage": 34.3,
        "avg_response_time": 15.2,
        "affected_endpoints": ["/v1/search", "/v1/validate"]
      },
      {
        "error_code": "RATE_LIMITED",
        "count": 18,
        "percentage": 26.9,
        "peak_times": ["09:00-10:00", "14:00-15:00"]
      },
      {
        "error_code": "INVALID_QUERY",
        "count": 15,
        "percentage": 22.4,
        "common_patterns": ["empty query", "special characters"]
      }
    ],
    "recommendations": [
      {
        "issue": "High timeout rate",
        "suggestion": "Reduce max_results parameter or increase timeout",
        "priority": "high"
      },
      {
        "issue": "Rate limiting",
        "suggestion": "Implement exponential backoff or upgrade plan", 
        "priority": "medium"
      }
    ]
  }
}

📊 Custom Dashboards

Create Custom Metrics

curl -X POST https://api.usecortex.co/v1/dashboards \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "My Custom Dashboard",
    "metrics": [
      {"type": "requests_per_hour", "period": "24h"},
      {"type": "success_rate", "period": "7d"}, 
      {"type": "response_time", "percentile": 95}
    ],
    "alerts": [
      {"metric": "error_rate", "threshold": 0.05, "condition": "greater_than"}
    ]
  }'

📱 Monitoring SDKs

Python Monitoring

from cortex import CortexClient

client = CortexClient(api_key="your_key")

# Get usage stats
usage = client.monitoring.usage(period="week")
print(f"Used: {usage.requests_used}/{usage.requests_limit}")
print(f"Success rate: {usage.performance_metrics.success_rate:.2%}")

# Check health
health = client.monitoring.health()
if health.status != "healthy":
    print("System issues detected!")
    for service, status in health.services.items():
        if status.status != "healthy":
            print(f"{service}: {status.status}")

# Monitor specific request
request_id = "req_123abc"
audit_entry = client.monitoring.audit(request_id=request_id)
print(f"Request took {audit_entry.response_time}s")

JavaScript Monitoring

import Cortex from '@cortex/sdk';

const cortex = new Cortex({ apiKey: 'your_key' });

// Real-time monitoring
const monitor = cortex.monitoring.live();

monitor.on('metrics', (data) => {
  console.log(`RPM: ${data.currentLoad.requestsPerMinute}`);
  console.log(`Response time: ${data.last5Minutes.avgResponseTime}s`);
});

monitor.on('alert', (alert) => {
  console.warn(`Alert: ${alert.message}`);
});

// Usage analytics
const usage = await cortex.monitoring.usage({ period: 'month' });
console.log(`Usage: ${usage.currentPeriod.usagePercentage}%`);

🔔 Alerting

Set Up Alerts

{
  "alerts": [
    {
      "name": "High Error Rate",
      "condition": "error_rate > 0.05",
      "duration": "5m",
      "channels": ["email", "webhook"]
    },
    {
      "name": "Usage Limit Warning", 
      "condition": "usage_percentage > 80",
      "channels": ["email"]
    },
    {
      "name": "Slow Response Time",
      "condition": "avg_response_time > 5.0",
      "duration": "10m",
      "channels": ["slack"]
    }
  ]
}

Webhook Notifications

{
  "webhook": {
    "url": "https://your-app.com/cortex-alerts",
    "payload": {
      "alert_name": "{{alert_name}}",
      "message": "{{message}}",
      "timestamp": "{{timestamp}}",
      "severity": "{{severity}}",
      "metrics": "{{metrics}}"
    }
  }
}

💡 Best Practices

Performance Monitoring

Track Key Metrics
- Response time percentiles (p95, p99)
- Error rates by endpoint
- Cache hit rates
- Request volume trends
Set Appropriate Alerts
- Error rate > 5%
- Response time > 5 seconds
- Usage > 80% of limit
- Cache hit rate < 50%

Regular Health Checks

# Health check in your application
def check_cortex_health():
    try:
        health = client.monitoring.health()
        return health.status == "healthy"
    except Exception:
        return False

Usage Optimization

Monitor Usage Patterns
- Peak usage times
- Most common endpoints
- Cache effectiveness
- Query complexity
Optimize Based on Data
- Increase caching for repeated queries
- Adjust timeouts based on performance
- Implement retries for transient errors
- Scale up during peak times

Next: Error Codes → - Complete error reference guide

📊 Usage Analytics​

GET /v1/usage​

Query Parameters​

Response​

🏥 Health Monitoring​

GET /v1/health​

Response​

📋 Audit Logs​

GET /v1/audit​

Query Parameters​

Response​

📈 Real-time Metrics​

GET /v1/metrics/live​

Response​

🚨 Error Analytics​

GET /v1/errors​

Response​

📊 Custom Dashboards​

Create Custom Metrics​

📱 Monitoring SDKs​

Python Monitoring​

JavaScript Monitoring​

🔔 Alerting​

Set Up Alerts​

Webhook Notifications​

💡 Best Practices​

Performance Monitoring​

Usage Optimization​

📊 Usage Analytics

GET
`/v1/usage`

Query Parameters

Response

🏥 Health Monitoring

GET
`/v1/health`

Response

📋 Audit Logs

GET
`/v1/audit`

Query Parameters

Response

📈 Real-time Metrics

GET
`/v1/metrics/live`

Response

🚨 Error Analytics

GET
`/v1/errors`

Response

📊 Custom Dashboards

Create Custom Metrics

📱 Monitoring SDKs

Python Monitoring

JavaScript Monitoring

🔔 Alerting

Set Up Alerts

Webhook Notifications

💡 Best Practices

Performance Monitoring

Usage Optimization