Metrics API

The Metrics API provides programmatic access to all Factory analytics data: executive summary KPIs, per-station metrics, cost breakdown, provider benchmarking, handoff quality, DevOps metrics, and phase-based analytics. Use it to build custom dashboards, integrate with business intelligence tools, or drive automated decisions.

API Endpoint

GET /api/factory/metrics

Query aggregated factory metrics.

Required parameters:

Authorization: Bearer $RENSEI_API_KEY (header)

Query parameters:

Param	Type	Default	Notes
`metricType`	enum	`aggregate`	See Metric Types table
`timeRange`	enum	`30d`	`7d`, `30d`, or `90d`

Response: Returns metric object(s) scoped to the selected metric type.

Metric Types

1. aggregate

Executive summary KPIs: total issues, total cost, avg cycle time, avg yield, throughput, cost trend.

curl -H "Authorization: Bearer $RENSEI_API_KEY" \
  "https://app.rensei.ai/api/factory/metrics?metricType=aggregate&timeRange=30d"

Response:

{
  "metrics": {
    "totalIssues": 47,
    "totalCost": 256.82,
    "avgCycleTimeMs": 50400000,
    "avgYield": 92.1,
    "throughputPerDay": 1.57,
    "costTrend": [12.5, 13.2, 11.8, 14.1, ...]
  }
}

Fields:

Field	Type	Notes
`totalIssues`	int	Count of completed work items
`totalCost`	float	Sum of all issue costs (USD)
`avgCycleTimeMs`	int	Median cycle time (milliseconds)
`avgYield`	float	First-pass completion rate (0-100)
`throughputPerDay`	float	Issues completed per day
`costTrend`	float[]	Daily cost for each day in window (sparkline data)

2. station

Per-station metrics: WIP, throughput, cycle time, yield.

curl -H "Authorization: Bearer $RENSEI_API_KEY" \
  "https://app.rensei.ai/api/factory/metrics?metricType=station&timeRange=30d"

Response:

{
  "metrics": [
    {
      "station": "research",
      "wipCount": 1,
      "throughput": 2,
      "cycleTimeMs": 10800000,
      "yield": 95.0
    },
    {
      "station": "development",
      "wipCount": 3,
      "throughput": 3,
      "cycleTimeMs": 18000000,
      "yield": 92.0
    },
    ...
  ]
}

Fields:

Field	Type	Notes
`station`	string	research, development, security, qa, acceptance, deploy
`wipCount`	int	Items currently in this station
`throughput`	int	Items completed in time window
`cycleTimeMs`	int	Median time in station (milliseconds)
`yield`	float	First-pass rate for this station (0-100)

3. cost

Cost breakdown: avg cost per issue, cost per station, cost trend, human-vs-agent split.

curl -H "Authorization: Bearer $RENSEI_API_KEY" \
  "https://app.rensei.ai/api/factory/metrics?metricType=cost&timeRange=30d"

Response:

{
  "metrics": {
    "avgCostPerIssue": 1.23,
    "costPerStation": [
      { "station": "development", "cost": 0.62 },
      { "station": "qa", "cost": 0.38 },
      { "station": "security", "cost": 0.15 },
      { "station": "research", "cost": 0.05 },
      { "station": "acceptance", "cost": 0.02 },
      { "station": "deploy", "cost": 0.01 }
    ],
    "costTrend": [
      { "date": "2026-05-03", "cost": 1.18 },
      { "date": "2026-05-04", "cost": 1.25 },
      { "date": "2026-05-05", "cost": 1.20 }
    ],
    "humanTimePct": 25.0,
    "agentTimePct": 75.0
  }
}

Fields:

Field	Type	Notes
`avgCostPerIssue`	float	Total cost ÷ total issues (USD)
`costPerStation`	object[]	Cost breakdown by SDLC station
`costTrend`	object[]	Daily cost with ISO date
`humanTimePct`	float	Percentage of time spent on human review (0-100)
`agentTimePct`	float	Percentage of time spent on agent work (0-100)

4. provider

Provider benchmarking: success rate, avg cost, avg duration, cost efficiency by agent/model.

curl -H "Authorization: Bearer $RENSEI_API_KEY" \
  "https://app.rensei.ai/api/factory/metrics?metricType=provider&timeRange=30d"

Response:

{
  "metrics": [
    {
      "provider": "anthropic",
      "successRate": 89.0,
      "avgCost": 1.45,
      "avgDurationMs": 1800000,
      "totalRuns": 23,
      "costEfficiency": 61.4
    },
    {
      "provider": "openai",
      "successRate": 76.0,
      "avgCost": 2.10,
      "avgDurationMs": 2400000,
      "totalRuns": 18,
      "costEfficiency": 36.2
    }
  ]
}

Fields:

Field	Type	Notes
`provider`	string	Provider name extracted from `factory_metrics.metadata.provider`
`successRate`	float	Percentage (0-100): completed ÷ (completed + rework) events
`avgCost`	float	Average cost per run (USD)
`avgDurationMs`	int	Average execution time (milliseconds)
`totalRuns`	int	Total runs in window
`costEfficiency`	float	successRate ÷ avgCost (higher is better)

5. handoff

Handoff quality: review latency, acceptance rate, override frequency, friction score.

curl -H "Authorization: Bearer $RENSEI_API_KEY" \
  "https://app.rensei.ai/api/factory/metrics?metricType=handoff&timeRange=30d"

Response:

{
  "metrics": {
    "avgReviewLatencyMs": 3600000,
    "acceptanceRate": 0.92,
    "overrideFrequency": 0.08,
    "handoffFrictionScore": 0.12,
    "overrideTimeline": [
      { "date": "2026-05-10", "count": 1 },
      { "date": "2026-05-15", "count": 2 },
      { "date": "2026-05-22", "count": 1 }
    ]
  }
}

Fields:

Field	Type	Notes
`avgReviewLatencyMs`	int	Time from handoff to decision (milliseconds)
`acceptanceRate`	float	% of handoffs approved (0-1)
`overrideFrequency`	float	% of decisions overridden by humans (0-1)
`handoffFrictionScore`	float	0-1; lower is better; calculated as (1 - acceptanceRate) × (1 - overrideFrequency)
`overrideTimeline`	object[]	Daily override counts

6. phase

Phase-based metrics: cycle time, cost, throughput by SDLC phase.

curl -H "Authorization: Bearer $RENSEI_API_KEY" \
  "https://app.rensei.ai/api/factory/metrics?metricType=phase&timeRange=30d"

Response:

{
  "metrics": {
    "phases": [
      {
        "phase": "research",
        "avgCycleTimeMs": 28800000,
        "avgCostUsd": 0.15,
        "throughput": 47
      },
      {
        "phase": "development",
        "avgCycleTimeMs": 57600000,
        "avgCostUsd": 0.62,
        "throughput": 47
      },
      ...
    ],
    "reworkLoops": {
      "avgCyclesPerIssue": 1.08,
      "totalReworks": 4,
      "totalCompleted": 47
    },
    "escalationDistribution": [
      { "strategy": "auto_escalate", "count": 3, "percentage": 6.4 },
      { "strategy": "human_review", "count": 44, "percentage": 93.6 }
    ]
  }
}

Fields:

Field	Type	Notes
`phases[].phase`	string	research, development, security, qa, acceptance, deploy
`phases[].avgCycleTimeMs`	int	Time to complete this phase (milliseconds)
`phases[].avgCostUsd`	float	Cost per issue in this phase
`phases[].throughput`	int	Issues completed in this phase
`reworkLoops.avgCyclesPerIssue`	float	Average times an issue cycles through rework
`reworkLoops.totalReworks`	int	Number of rework events
`reworkLoops.totalCompleted`	int	Number of completed issues
`escalationDistribution`	object[]	Breakdown of escalation strategies

7. devops

DevOps/DORA metrics: deployment frequency, lead time, change failure rate, recovery time.

curl -H "Authorization: Bearer $RENSEI_API_KEY" \
  "https://app.rensei.ai/api/factory/metrics?metricType=devops&timeRange=30d"

Response:

{
  "metrics": {
    "infra": {
      "uptimePct": 99.5,
      "activeDeployments": 12,
      "openIncidents": 0,
      "deploymentFrequency": "2.5/day",
      "changeFailureRate": "5.2%",
      "leadTimeForChanges": "4.5h",
      "meanTimeToRecovery": "15m"
    },
    "pipelines": [
      {
        "name": "main",
        "status": "success",
        "duration": "12m",
        "trigger": "push",
        "branch": "main",
        "commit": "abc123...",
        "startedAt": "2026-06-02T14:00:00Z"
      }
    ],
    "deployments": [
      {
        "id": "dep_xyz",
        "version": "v1.2.3",
        "environment": "production",
        "status": "success",
        "deployedAt": "2026-06-02T14:15:00Z",
        "deployedBy": "agent-claude-sonnet",
        "isRollback": false
      }
    ],
    "incidents": []
  }
}

Error Handling

All endpoints return errors with a standard format:

{
  "error": {
    "code": "INVALID_TIME_RANGE",
    "message": "Invalid timeRange. Must be one of: 7d, 30d, 90d",
    "status": 400
  }
}

Common errors:

Status	Code	Meaning
400	`INVALID_METRIC_TYPE`	Unknown metricType
400	`INVALID_TIME_RANGE`	timeRange not in [7d, 30d, 90d]
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	User lacks permission for this org
500	`DATABASE_ERROR`	Transient DB failure; retry

Rate Limiting

1,000 requests/minute per API key
Burst limit: 10,000 requests/minute (then throttled)
Retry-After: Included in 429 response headers

Examples

Build a Custom Dashboard

async function fetchDashboard(apiKey: string, timeRange: '7d' | '30d' | '90d') {
  const [aggregate, station, cost] = await Promise.all([
    fetch(`https://app.rensei.ai/api/factory/metrics?metricType=aggregate&timeRange=${timeRange}`, {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    }).then(r => r.json()),
    fetch(`https://app.rensei.ai/api/factory/metrics?metricType=station&timeRange=${timeRange}`, {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    }).then(r => r.json()),
    fetch(`https://app.rensei.ai/api/factory/metrics?metricType=cost&timeRange=${timeRange}`, {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    }).then(r => r.json())
  ])

  return { aggregate: aggregate.metrics, stations: station.metrics, costs: cost.metrics }
}

Alert on Low Yield

#!/bin/bash

API_KEY="rsk_live_..."
YIELD_THRESHOLD=70

yield=$(curl -s -H "Authorization: Bearer $API_KEY" \
  "https://app.rensei.ai/api/factory/metrics?metricType=aggregate&timeRange=7d" \
  | jq '.metrics.avgYield')

if (( $(echo "$yield < $YIELD_THRESHOLD" | bc -l) )); then
  echo "⚠️  Alert: Yield is ${yield}% (threshold: ${YIELD_THRESHOLD}%)"
  # Send Slack notification, trigger escalation, etc.
fi

Cost Forecasting

import requests
from datetime import datetime, timedelta

API_KEY = "rsk_live_..."

# Fetch last 90 days of cost trend
response = requests.get(
    "https://app.rensei.ai/api/factory/metrics",
    params={"metricType": "cost", "timeRange": "90d"},
    headers={"Authorization": f"Bearer {API_KEY}"}
)

trend = response.json()["metrics"]["costTrend"]
daily_costs = [t["cost"] for t in trend]
avg_daily = sum(daily_costs) / len(daily_costs)
monthly_forecast = avg_daily * 30

print(f"Forecasted monthly cost: ${monthly_forecast:.2f}")

Next Steps

For real-time event streaming, see Events API
For individual issue details, see Sessions API
To understand metric calculations, see Executive Summary
For custom workflows using metrics, see Workflows

On this page