Metrics API - SO1 Field Manual

Overview

The Metrics API provides comprehensive analytics for agents, workflows, orchestrations, and system health. Query performance data, track resource usage, and analyze trends across your SO1 automation infrastructure.

Base URL: https://api.so1.io/v1/control-plane/metrics

Agent Metrics

Retrieve performance metrics for agent executions.

Endpoint

GET /v1/control-plane/metrics/agents

Query Parameters

agentId

string

Filter by specific agent (optional)

startDate

string

required

ISO 8601 date - metrics start date

endDate

string

required

ISO 8601 date - metrics end date

granularity

string

default:"day"

Data granularity: hour, day, week, month

Example Request

curl -X GET "https://api.so1.io/v1/control-plane/metrics/agents?agentId=mintlify-author&startDate=2024-03-01&endDate=2024-03-10&granularity=day" \
  -H "Authorization: Bearer so1_key_abc123xyz"

Response

{
  "success": true,
  "data": {
    "agentId": "mintlify-author",
    "period": {
      "start": "2024-03-01T00:00:00Z",
      "end": "2024-03-10T23:59:59Z",
      "granularity": "day"
    },
    "summary": {
      "totalExecutions": 247,
      "successfulExecutions": 243,
      "failedExecutions": 4,
      "successRate": 98.4,
      "averageDuration": 42.3,
      "p50Duration": 38.1,
      "p95Duration": 67.2,
      "p99Duration": 89.5,
      "totalProcessingTime": 10448.1
    },
    "timeseries": [
      {
        "timestamp": "2024-03-01T00:00:00Z",
        "executions": 23,
        "successful": 23,
        "failed": 0,
        "averageDuration": 41.2,
        "totalDuration": 947.6
      },
      {
        "timestamp": "2024-03-02T00:00:00Z",
        "executions": 28,
        "successful": 27,
        "failed": 1,
        "averageDuration": 44.8,
        "totalDuration": 1209.6
      }
      // ... more days
    ],
    "taskTypeBreakdown": [
      {
        "taskType": "create-agent-reference",
        "executions": 156,
        "successRate": 99.4,
        "averageDuration": 39.7
      },
      {
        "taskType": "create-runbook",
        "executions": 67,
        "successRate": 97.0,
        "averageDuration": 51.2
      },
      {
        "taskType": "update-navigation",
        "executions": 24,
        "successRate": 95.8,
        "averageDuration": 28.4
      }
    ],
    "errorBreakdown": [
      {
        "errorCode": "GATE_VALIDATION_FAILED",
        "count": 2,
        "percentage": 50.0
      },
      {
        "errorCode": "CONTEXT_VALIDATION_FAILED",
        "count": 2,
        "percentage": 50.0
      }
    ]
  }
}

Workflow Metrics

Retrieve performance metrics for workflow executions.

Endpoint

GET /v1/control-plane/metrics/workflows

Query Parameters

workflowId

string

Filter by specific workflow (optional)

startDate

string

required

ISO 8601 date - metrics start date

endDate

string

required

ISO 8601 date - metrics end date

granularity

string

default:"day"

Data granularity: hour, day, week, month

Example Request

curl -X GET "https://api.so1.io/v1/control-plane/metrics/workflows?workflowId=deployment-pipeline&startDate=2024-03-01&endDate=2024-03-10" \
  -H "Authorization: Bearer so1_key_abc123xyz"

Response

{
  "success": true,
  "data": {
    "workflowId": "deployment-pipeline",
    "period": {
      "start": "2024-03-01T00:00:00Z",
      "end": "2024-03-10T23:59:59Z"
    },
    "summary": {
      "totalExecutions": 342,
      "successfulExecutions": 336,
      "failedExecutions": 6,
      "successRate": 98.2,
      "averageDuration": 142.7,
      "p50Duration": 138.3,
      "p95Duration": 187.4,
      "p99Duration": 245.8
    },
    "timeseries": [
      {
        "timestamp": "2024-03-01T00:00:00Z",
        "executions": 38,
        "successful": 37,
        "failed": 1,
        "averageDuration": 145.2
      }
      // ... more data points
    ],
    "nodePerformance": [
      {
        "nodeName": "Validate Version",
        "averageDuration": 0.4,
        "failureRate": 0.0
      },
      {
        "nodeName": "Railway Deploy",
        "averageDuration": 125.8,
        "failureRate": 1.2
      },
      {
        "nodeName": "Health Check",
        "averageDuration": 5.3,
        "failureRate": 0.6
      }
    ]
  }
}

Orchestration Metrics

Retrieve performance metrics for multi-agent orchestrations.

Endpoint

GET /v1/control-plane/metrics/orchestrations

Query Parameters

startDate

string

required

ISO 8601 date - metrics start date

endDate

string

required

ISO 8601 date - metrics end date

stage

string

Filter by FORGE stage (optional)

Example Request

curl -X GET "https://api.so1.io/v1/control-plane/metrics/orchestrations?startDate=2024-03-01&endDate=2024-03-10" \
  -H "Authorization: Bearer so1_key_abc123xyz"

Response

{
  "success": true,
  "data": {
    "period": {
      "start": "2024-03-01T00:00:00Z",
      "end": "2024-03-10T23:59:59Z"
    },
    "summary": {
      "totalOrchestrations": 47,
      "completed": 43,
      "failed": 2,
      "cancelled": 2,
      "successRate": 91.5,
      "averageDuration": 852.4,
      "averageStagesCompleted": 5.7,
      "averageTasksPerOrchestration": 11.3
    },
    "stagePerformance": [
      {
        "stage": "RESEARCH",
        "completionRate": 100.0,
        "averageDuration": 87.2
      },
      {
        "stage": "DESIGN",
        "completionRate": 97.9,
        "averageDuration": 142.8
      },
      {
        "stage": "IMPLEMENT",
        "completionRate": 95.7,
        "averageDuration": 387.5
      },
      {
        "stage": "VERIFY",
        "completionRate": 93.6,
        "averageDuration": 156.3
      },
      {
        "stage": "DEPLOY",
        "completionRate": 91.5,
        "averageDuration": 67.4
      },
      {
        "stage": "MONITOR",
        "completionRate": 100.0,
        "averageDuration": 11.2
      }
    ],
    "gateValidationMetrics": {
      "totalValidations": 282,
      "passed": 267,
      "failed": 15,
      "passRate": 94.7,
      "commonFailures": [
        { "criteria": "testsPass", "failures": 7 },
        { "criteria": "securityScan", "failures": 4 },
        { "criteria": "codeReviewed", "failures": 4 }
      ]
    }
  }
}

System Health

Retrieve overall system health and resource usage.

Endpoint

GET /v1/control-plane/metrics/system/health

Example Request

curl -X GET https://api.so1.io/v1/control-plane/metrics/system/health \
  -H "Authorization: Bearer so1_key_abc123xyz"

Response

{
  "success": true,
  "data": {
    "status": "healthy",
    "timestamp": "2024-03-10T15:30:00Z",
    "services": {
      "controlPlane": {
        "status": "healthy",
        "responseTime": 42,
        "uptime": 99.98
      },
      "agents": {
        "status": "healthy",
        "activeExecutions": 23,
        "queuedTasks": 7,
        "capacityUtilization": 46.0
      },
      "workflows": {
        "status": "healthy",
        "activeExecutions": 12,
        "n8nStatus": "operational"
      },
      "database": {
        "status": "healthy",
        "connections": 47,
        "queryLatencyP95": 23.4
      },
      "redis": {
        "status": "healthy",
        "memoryUsage": 34.2,
        "operations": 1247
      }
    },
    "resources": {
      "cpu": {
        "usage": 42.3,
        "available": 8000
      },
      "memory": {
        "usage": 67.8,
        "available": 32000
      },
      "storage": {
        "usage": 23.4,
        "available": 500000
      }
    },
    "rateLimits": {
      "tier": "professional",
      "requestsPerMinute": {
        "limit": 300,
        "current": 47,
        "utilizationPercentage": 15.7
      },
      "concurrentExecutions": {
        "limit": 50,
        "current": 23,
        "utilizationPercentage": 46.0
      }
    }
  }
}

Resource Usage

Retrieve detailed resource usage metrics.

Endpoint

GET /v1/control-plane/metrics/system/resources

Query Parameters

startDate

string

required

ISO 8601 date - start date

endDate

string

required

ISO 8601 date - end date

granularity

string

default:"hour"

Data granularity: minute, hour, day

Example Request

curl -X GET "https://api.so1.io/v1/control-plane/metrics/system/resources?startDate=2024-03-10T00:00:00Z&endDate=2024-03-10T23:59:59Z&granularity=hour" \
  -H "Authorization: Bearer so1_key_abc123xyz"

Response

{
  "success": true,
  "data": {
    "period": {
      "start": "2024-03-10T00:00:00Z",
      "end": "2024-03-10T23:59:59Z",
      "granularity": "hour"
    },
    "timeseries": [
      {
        "timestamp": "2024-03-10T00:00:00Z",
        "cpu": { "usage": 38.4, "peak": 52.1 },
        "memory": { "usage": 64.2, "peak": 71.3 },
        "storage": { "usage": 23.4, "growth": 0.02 },
        "network": { "inbound": 1247.8, "outbound": 892.3 },
        "requests": { "total": 1823, "successful": 1807, "failed": 16 }
      }
      // ... more hours
    ],
    "summary": {
      "averageCpuUsage": 42.1,
      "peakCpuUsage": 78.3,
      "averageMemoryUsage": 67.2,
      "peakMemoryUsage": 84.7,
      "totalRequests": 43752,
      "totalDataTransferred": 47832.4
    }
  }
}

Cost Analytics

Retrieve cost breakdown and usage-based billing metrics.

Endpoint

GET /v1/control-plane/metrics/costs

Query Parameters

startDate

string

required

ISO 8601 date - billing period start

endDate

string

required

ISO 8601 date - billing period end

groupBy

string

default:"service"

Group costs by: service, agent, workflow, day

Example Request

curl -X GET "https://api.so1.io/v1/control-plane/metrics/costs?startDate=2024-03-01&endDate=2024-03-31&groupBy=service" \
  -H "Authorization: Bearer so1_key_abc123xyz"

Response

{
  "success": true,
  "data": {
    "period": {
      "start": "2024-03-01T00:00:00Z",
      "end": "2024-03-31T23:59:59Z"
    },
    "summary": {
      "totalCost": 847.32,
      "currency": "USD",
      "tier": "professional",
      "baseFee": 299.00,
      "usageFee": 548.32
    },
    "breakdown": [
      {
        "category": "agents",
        "cost": 412.45,
        "executions": 8247,
        "costPerExecution": 0.05
      },
      {
        "category": "workflows",
        "cost": 187.23,
        "executions": 3421,
        "costPerExecution": 0.055
      },
      {
        "category": "orchestrations",
        "cost": 248.64,
        "orchestrations": 247,
        "costPerOrchestration": 1.007
      }
    ],
    "topAgents": [
      { "agentId": "hono-backend", "cost": 124.56, "executions": 2487 },
      { "agentId": "mintlify-author", "cost": 98.32, "executions": 1964 },
      { "agentId": "railway-deployer", "cost": 87.41, "executions": 1423 }
    ],
    "forecast": {
      "projectedMonthlyTotal": 912.45,
      "basedOnDaysOfData": 10,
      "confidenceLevel": "medium"
    }
  }
}

Custom Metrics Query

Execute custom metrics queries with flexible filtering and aggregation.

Endpoint

POST /v1/control-plane/metrics/query

Request Body

metric

string

required

Metric to query: agent_duration, workflow_success_rate, orchestration_stage_time, etc.

filters

object

Filters to apply (agentId, workflowId, stage, status, etc.)

aggregation

string

required

Aggregation function: avg, sum, count, min, max, p50, p95, p99

groupBy

array

Fields to group by (e.g., ["agentId", "taskType"])

timeRange

object

required

Start and end dates for query

Example Request

curl -X POST https://api.so1.io/v1/control-plane/metrics/query \
  -H "Authorization: Bearer so1_key_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "metric": "agent_duration",
    "filters": {
      "status": "completed",
      "forge.stage": "IMPLEMENT"
    },
    "aggregation": "p95",
    "groupBy": ["agentId"],
    "timeRange": {
      "start": "2024-03-01T00:00:00Z",
      "end": "2024-03-10T23:59:59Z"
    }
  }'

Response

{
  "success": true,
  "data": {
    "metric": "agent_duration",
    "aggregation": "p95",
    "results": [
      { "agentId": "hono-backend", "value": 187.4 },
      { "agentId": "nextjs-frontend", "value": 142.8 },
      { "agentId": "mintlify-author", "value": 67.2 },
      { "agentId": "railway-deployer", "value": 245.8 }
    ],
    "timeRange": {
      "start": "2024-03-01T00:00:00Z",
      "end": "2024-03-10T23:59:59Z"
    }
  }
}

Common Patterns

Track Agent Performance Over Time

async function trackAgentPerformance(agentId: string, days: number = 30) {
  const endDate = new Date();
  const startDate = new Date(endDate.getTime() - days * 24 * 60 * 60 * 1000);
  
  const response = await fetch(
    `https://api.so1.io/v1/control-plane/metrics/agents?` +
    `agentId=${agentId}&` +
    `startDate=${startDate.toISOString()}&` +
    `endDate=${endDate.toISOString()}&` +
    `granularity=day`,
    {
      headers: { 'Authorization': `Bearer ${process.env.SO1_API_KEY}` }
    }
  );
  
  const { data } = await response.json();
  
  console.log(`${agentId} Performance (Last ${days} days):`);
  console.log(`  Success Rate: ${data.summary.successRate}%`);
  console.log(`  Avg Duration: ${data.summary.averageDuration}s`);
  console.log(`  P95 Duration: ${data.summary.p95Duration}s`);
  
  return data;
}

Monitor System Health

async function monitorHealth() {
  const response = await fetch(
    'https://api.so1.io/v1/control-plane/metrics/system/health',
    { headers: { 'Authorization': `Bearer ${process.env.SO1_API_KEY}` } }
  );
  
  const { data } = await response.json();
  
  if (data.status !== 'healthy') {
    console.error('⚠️ System health degraded:', data.status);
    
    // Check individual services
    for (const [service, metrics] of Object.entries(data.services)) {
      if (metrics.status !== 'healthy') {
        console.error(`  ${service}: ${metrics.status}`);
      }
    }
  }
  
  // Check capacity utilization
  const { agents } = data.services;
  if (agents.capacityUtilization > 80) {
    console.warn(`⚠️ High capacity utilization: ${agents.capacityUtilization}%`);
  }
  
  return data;
}

Cost Tracking and Alerts

async function checkMonthlyCosts() {
  const now = new Date();
  const startOfMonth = new Date(now.getFullYear(), now.getMonth(), 1);
  
  const response = await fetch(
    `https://api.so1.io/v1/control-plane/metrics/costs?` +
    `startDate=${startOfMonth.toISOString()}&` +
    `endDate=${now.toISOString()}&` +
    `groupBy=service`,
    { headers: { 'Authorization': `Bearer ${process.env.SO1_API_KEY}` } }
  );
  
  const { data } = await response.json();
  
  console.log(`Monthly Costs (${startOfMonth.toLocaleDateString()} - ${now.toLocaleDateString()}):`);
  console.log(`  Total: $${data.summary.totalCost}`);
  console.log(`  Projected: $${data.forecast.projectedMonthlyTotal}`);
  
  // Alert if projected cost exceeds budget
  const budget = 1000.00;
  if (data.forecast.projectedMonthlyTotal > budget) {
    console.error(`⚠️ Projected monthly cost ($${data.forecast.projectedMonthlyTotal}) exceeds budget ($${budget})`);
  }
  
  return data;
}

Rate Limits

Metrics API endpoints have specific rate limits to protect database performance:

Endpoint	Rate Limit	Notes
Agent Metrics	10 req/min	Database-intensive queries
Workflow Metrics	10 req/min	Database-intensive queries
Orchestration Metrics	10 req/min	Database-intensive queries
System Health	60 req/min	Lightweight endpoint
Resource Usage	10 req/min	Time-series data queries
Cost Analytics	10 req/min	Billing data aggregation
Custom Query	5 req/min	Most resource-intensive

Agents API

Execute and monitor agents

Workflows API

Trigger and track workflows

Monitoring Runbook

Monitoring best practices and procedures

Rate Limits

API rate limiting policies

API Reference

Control Plane API

Veritas API

n8n API

​Overview

​Agent Metrics

​Endpoint

​Query Parameters

​Example Request

​Response

​Workflow Metrics

​Endpoint

​Query Parameters

​Example Request

​Response

​Orchestration Metrics

​Endpoint

​Query Parameters

​Example Request

​Response

​System Health

​Endpoint

​Example Request

​Response

​Resource Usage

​Endpoint

​Query Parameters

​Example Request

​Response

​Cost Analytics

​Endpoint

​Query Parameters

​Example Request

​Response

​Custom Metrics Query

​Endpoint

​Request Body

​Example Request

​Response

​Common Patterns

​Track Agent Performance Over Time

​Monitor System Health

​Cost Tracking and Alerts

​Rate Limits

​Related Resources

Agents API

Workflows API

Monitoring Runbook

Rate Limits

Overview

Agent Metrics

Endpoint

Query Parameters

Example Request

Response

Workflow Metrics

Endpoint

Query Parameters

Example Request

Response

Orchestration Metrics

Endpoint

Query Parameters

Example Request

Response

System Health

Endpoint

Example Request

Response

Resource Usage

Endpoint

Query Parameters

Example Request

Response

Cost Analytics

Endpoint

Query Parameters

Example Request

Response

Custom Metrics Query

Endpoint

Request Body

Example Request

Response

Common Patterns

Track Agent Performance Over Time

Monitor System Health

Cost Tracking and Alerts

Rate Limits

Related Resources