Skip to content
UltimateTeam.ai Docs

Get Agent Metrics

GET
/api/v1/accountability/metrics/{agent_role}
curl --request GET \
  --url 'https://api.ultimateteam.ai/api/v1/accountability/metrics/example?period_days=30' \
  --header 'X-API-Key: <X-API-Key>'

Get performance metrics for a single agent.

Validates the agent role against the canonical C-suite list and returns computed metrics for the given period. Best-effort syncs results to Firestore for real-time dashboard display.

Args: agent_role: The agent role to query (e.g. ‘ceo’). period_days: Number of days to look back. user: The authenticated user context. svc: The agent metrics service (injected).

Returns: Performance metrics for the specified agent.

Raises: HTTPException: 404 if agent_role is not a valid C-suite role.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
agent_role
required
Agent Role
string

Query Parameters

Section titled “Query Parameters”
period_days
Period Days

Number of days to look back

integer
default: 30 >= 1 <= 365

Number of days to look back

Responses

Section titled “ Responses ”

200

Section titled “200”

Successful Response

Media typeapplication/json
AgentPerformanceMetrics

Performance metrics for a single agent over a time period.

Attributes: agent_role: The agent role these metrics describe. total_tasks: Total tasks assigned in the period. completed_tasks: Tasks completed successfully. failed_tasks: Tasks that failed. success_rate: Ratio of completed to total (0.0-1.0). avg_completion_time_ms: Average task completion time in ms. escalation_count: Number of escalations (input-required). quality_gate_pass_rate: Ratio of quality gate passes (0.0-1.0). period_start: Start of the measurement period. period_end: End of the measurement period.

object
agent_role
required
Agent Role
string
avg_completion_time_ms
required
Avg Completion Time Ms
number
completed_tasks
required
Completed Tasks
integer
escalation_count
required
Escalation Count
integer
failed_tasks
required
Failed Tasks
integer
period_end
required
Period End
string format: date-time
period_start
required
Period Start
string format: date-time
quality_gate_pass_rate
required
Quality Gate Pass Rate
number
<= 1
success_rate
required
Success Rate
number
<= 1
total_tasks
required
Total Tasks
integer
Examplegenerated
{
  "agent_role": "example",
  "avg_completion_time_ms": 1,
  "completed_tasks": 1,
  "escalation_count": 1,
  "failed_tasks": 1,
  "period_end": "2026-04-15T12:00:00Z",
  "period_start": "2026-04-15T12:00:00Z",
  "quality_gate_pass_rate": 1,
  "success_rate": 1,
  "total_tasks": 1
}

422

Section titled “422”

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
ctx
Context
object
input
Input
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Examplegenerated
{
  "detail": [
    {
      "ctx": {},
      "input": "example",
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}