Skip to main content

Unified Metrics

The Unified Metrics API consolidates metrics from multiple sources into a single endpoint, replacing scattered metrics endpoints across the API.

Endpoint​

GET /v1/metrics

Get metrics from health, analytics, monitoring, and usage systems in one request.

Query Parameters​

ParameterTypeDefaultDescription
typestringallMetric type: health, analytics, monitoring, usage, all
hoursint24Time range in hours
detailstringfullDetail level: full or summary

Response​

{
  "type": "all",
  "time_range": {
    "start": "2026-01-14T10:30:00Z",
    "end": "2026-01-15T10:30:00Z",
    "hours": 24
  },
  "metrics": {
    "health": {
      "overall": {
        "total_services": 12,
        "healthy_services": 10,
        "degraded_services": 1,
        "critical_services": 1
      },
      "services": {
        "database": {
          "uptime_percentage": 99.9,
          "total_checks": 1440,
          "healthy_checks": 1438
        },
        "cache": {
          "uptime_percentage": 100.0,
          "total_checks": 1440,
          "healthy_checks": 1440
        }
      }
    },
    "analytics": {
      "period": "24h",
      "requests": {
        "total": 125000,
        "successful": 124750,
        "failed": 250
      },
      "performance": {
        "avg_response_time_ms": 185,
        "p95_response_time_ms": 320,
        "p99_response_time_ms": 450
      },
      "chains": {
        "ethereum": {"requests": 45000, "avg_latency_ms": 120},
        "polygon": {"requests": 32000, "avg_latency_ms": 95},
        "arbitrum": {"requests": 28000, "avg_latency_ms": 110}
      }
    },
    "monitoring": {
      "overall_health_score": 0.95,
      "performance_factor": 1.2,
      "is_healthy": true,
      "components": {
        "questdb": {
          "status": "healthy",
          "writes_per_sec": 15000,
          "latency_ms": 2
        },
        "dragonfly": {
          "status": "healthy",
          "ops_per_sec": 250000,
          "latency_ms": 0.5,
          "hit_ratio": 0.95
        },
        "clickhouse": {
          "status": "healthy",
          "queries_per_sec": 500,
          "latency_ms": 15
        }
      }
    },
    "usage": {
      "period": "24h",
      "requests": {
        "total": 50000,
        "authenticated": 42500,
        "anonymous": 7500
      },
      "endpoints": {
        "blockchain": 22500,
        "analytics": 12500,
        "auth": 7500,
        "other": 7500
      },
      "rate_limits": {
        "hits": 1000,
        "percentage": 2.0
      }
    }
  },
  "collected_at": "2026-01-15T10:30:00Z",
  "metric_count": 4
}

Metric Types​

Health Metrics​

System health across all services.

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.axol.io/api/v1/metrics?type=health"

Response fields:

  • overall.total_services - Total monitored services
  • overall.healthy_services - Services with 95%+ uptime
  • overall.degraded_services - Services with 80-95% uptime
  • overall.critical_services - Services below 80% uptime
  • services.* - Per-service uptime details (when detail=full)

Analytics Metrics​

Request statistics and performance data.

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.axol.io/api/v1/metrics?type=analytics&hours=48"

Response fields:

  • requests.total - Total API requests
  • requests.successful - Successful requests
  • requests.failed - Failed requests
  • performance.avg_response_time_ms - Average response time
  • performance.p95_response_time_ms - 95th percentile latency
  • chains.* - Per-chain request statistics

Monitoring Metrics​

Infrastructure and performance monitoring.

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.axol.io/api/v1/metrics?type=monitoring"

Response fields:

  • overall_health_score - System health score (0-1)
  • performance_factor - Performance improvement factor
  • components.questdb - Time-series database metrics
  • components.dragonfly - Cache layer metrics
  • components.clickhouse - Analytics database metrics

Usage Metrics​

API consumption and rate limit statistics.

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.axol.io/api/v1/metrics?type=usage"

Response fields:

  • requests.total - Total requests in period
  • requests.authenticated - Requests with API key
  • endpoints.* - Request distribution by endpoint
  • rate_limits.hits - Rate limit violations
  • bandwidth.total_mb - Total bandwidth consumed

Summary vs Full Detail​

Use detail=summary for high-level statistics:

# Summary (replaces deprecated /stats endpoints)
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.axol.io/api/v1/metrics?type=analytics&detail=summary"
{
  "metrics": {
    "analytics": {
      "total_chains": 12,
      "active_chains": 8,
      "total_addresses": 1500000,
      "total_transactions": 50000000,
      "gas_analytics_enabled": true,
      "blockchain_analytics_enabled": true
    }
  }
}

List Metric Types​

GET /v1/metrics/types

Returns all available metric types with descriptions.

{
  "types": [
    {
      "name": "health",
      "description": "System health metrics across all services",
      "deprecated_endpoints": ["/health/metrics", "/api/v1/health-dashboard/metrics"]
    },
    {
      "name": "analytics",
      "description": "Analytics service metrics and statistics",
      "deprecated_endpoints": ["/api/v1/analytics/metrics"]
    },
    {
      "name": "monitoring",
      "description": "Ultra-performance stack monitoring metrics",
      "deprecated_endpoints": ["/api/v1/monitoring/ultra-stack/metrics"]
    },
    {
      "name": "usage",
      "description": "API usage and consumption metrics",
      "deprecated_endpoints": ["/api/v1/usage/metrics"]
    },
    {
      "name": "all",
      "description": "All available metrics combined",
      "deprecated_endpoints": []
    }
  ]
}

Migration from Deprecated Endpoints​

Old EndpointNew Endpoint
/health/metrics/v1/metrics?type=health
/v1/analytics/metrics/v1/metrics?type=analytics
/v1/analytics/stats/v1/metrics?type=analytics&detail=summary
/v1/monitoring/ultra-stack/metrics/v1/metrics?type=monitoring
/v1/usage/metrics/v1/metrics?type=usage
/v1/usage/stats/v1/metrics?type=usage&detail=summary
/v1/health-dashboard/metrics/v1/metrics?type=health

Code Examples​

Python - Metrics Dashboard​

import requests
from dataclasses import dataclass

@dataclass
class SystemHealth:
    healthy_services: int
    total_services: int
    health_percentage: float

class MetricsClient:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.axol.io/api/v1/metrics"
        self.headers = {"X-API-Key": api_key}

    def get_metrics(
        self,
        metric_type: str = "all",
        hours: int = 24,
        detail: str = "full"
    ) -> dict:
        response = requests.get(
            self.base_url,
            headers=self.headers,
            params={
                "type": metric_type,
                "hours": hours,
                "detail": detail
            }
        )
        return response.json()

    def get_health_summary(self) -> SystemHealth:
        data = self.get_metrics("health", detail="summary")
        health = data["metrics"]["health"]["overall"]
        return SystemHealth(
            healthy_services=health["healthy_services"],
            total_services=health["total_services"],
            health_percentage=(
                health["healthy_services"] / health["total_services"] * 100
            )
        )

    def is_system_healthy(self) -> bool:
        health = self.get_health_summary()
        return health.health_percentage >= 90

# Usage
client = MetricsClient(api_key="YOUR_KEY")

# Check overall health
if client.is_system_healthy():
    print("System is healthy")
else:
    print("System degraded - check metrics")

# Get detailed analytics metrics
analytics = client.get_metrics("analytics", hours=48)
print(f"Requests (48h): {analytics['metrics']['analytics']['requests']['total']}")
print(f"Avg latency: {analytics['metrics']['analytics']['performance']['avg_response_time_ms']}ms")

TypeScript - Real-time Monitoring​

interface MetricsResponse {
  type: string;
  time_range: {
    start: string;
    end: string;
    hours: number;
  };
  metrics: {
    health?: HealthMetrics;
    analytics?: AnalyticsMetrics;
    monitoring?: MonitoringMetrics;
    usage?: UsageMetrics;
  };
}

interface HealthMetrics {
  overall: {
    total_services: number;
    healthy_services: number;
    degraded_services: number;
    critical_services: number;
  };
}

interface MonitoringMetrics {
  overall_health_score: number;
  is_healthy: boolean;
  components: Record<string, ComponentMetrics>;
}

interface ComponentMetrics {
  status: string;
  latency_ms: number;
}

class MetricsMonitor {
  private apiKey: string;
  private baseUrl = 'https://api.axol.io/api/v1/metrics';
  private intervalId?: NodeJS.Timeout;
  private onUpdate?: (metrics: MetricsResponse) => void;

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  async fetchMetrics(type = 'all', hours = 24): Promise<MetricsResponse> {
    const url = new URL(this.baseUrl);
    url.searchParams.set('type', type);
    url.searchParams.set('hours', hours.toString());

    const response = await fetch(url.toString(), {
      headers: { 'X-API-Key': this.apiKey }
    });
    return response.json();
  }

  startMonitoring(
    intervalMs = 60000,
    callback: (metrics: MetricsResponse) => void
  ): void {
    this.onUpdate = callback;

    // Initial fetch
    this.fetchMetrics().then(this.onUpdate);

    // Poll periodically
    this.intervalId = setInterval(async () => {
      const metrics = await this.fetchMetrics();
      this.onUpdate?.(metrics);
    }, intervalMs);
  }

  stopMonitoring(): void {
    if (this.intervalId) {
      clearInterval(this.intervalId);
    }
  }

  async getHealthScore(): Promise<number> {
    const metrics = await this.fetchMetrics('monitoring');
    return metrics.metrics.monitoring?.overall_health_score ?? 0;
  }
}

// Usage
const monitor = new MetricsMonitor(process.env.AXOL_API_KEY!);

// Start monitoring with 1-minute intervals
monitor.startMonitoring(60000, (metrics) => {
  const health = metrics.metrics.health?.overall;
  if (health) {
    console.log(`Healthy: ${health.healthy_services}/${health.total_services}`);
  }

  if (metrics.metrics.monitoring?.is_healthy === false) {
    console.log('WARNING: System health degraded');
  }
});

// Get current health score
const score = await monitor.getHealthScore();
console.log(`Health score: ${(score * 100).toFixed(1)}%`);

Best Practices​

1. Cache Metrics Responses​

Metrics don't change frequently. Cache for 30-60 seconds:

from functools import lru_cache
import time

@lru_cache(maxsize=10)
def get_cached_metrics(metric_type: str, ttl_hash: int) -> dict:
    return client.get_metrics(metric_type)

def get_metrics_cached(metric_type: str, cache_seconds: int = 60) -> dict:
    ttl_hash = int(time.time() / cache_seconds)
    return get_cached_metrics(metric_type, ttl_hash)

2. Use Summary for Dashboards​

For dashboards, use detail=summary to reduce payload size:

# For dashboard tiles
summary = client.get_metrics("all", detail="summary")

# For detailed investigation
full = client.get_metrics("health", detail="full")

3. Set Appropriate Time Ranges​

Use CaseRecommended hours
Real-time dashboard1-6
Daily reports24
Weekly trends168
Debugging issues1-4

See Also​