Telemetry

Performance monitoring, usage metrics, and execution logs for agents.

Authentication

All telemetry endpoints require JWT authentication:

Authorization: Bearer <jwt-token>
x-tenant-id: <uuid>

---

Endpoints Overview

Endpoint	Description	Use Case
/metrics	Aggregated metrics	Main dashboard
/logs	Paginated logs	Audit and debugging
/sessions	Session metrics	Conversation analysis
/sessions/:id	Session details	Specific conversation debug
/usage-by-hour	Hourly usage	Trend charts
/dashboard	Complete dashboard	Executive view
/cache	Cache performance	Prompt optimization
/loopgraph	Agent loop metrics	Agent loop debugging
/call-sources	Metrics by source	Channel analysis
/tools-usage	Tool usage	Tool optimization
/routing-analysis	Routing analysis	Auto-routing tuning
/latency-analysis	Latency analysis	Bottleneck identification
/summary	Complete summary	Main dashboard

---

GET /api/telemetry/metrics

Aggregated telemetry metrics for a period.

Query Parameters:

Param	Type	Required	Description
start_date	ISO date	Yes	Start date
end_date	ISO date	Yes	End date
agent_id	UUID	No	Filter by agent
provider	string	No	Filter by provider
model	string	No	Filter by model
status	string	No	success or error

Response:

{
  "data": {
    "totalRequests": 5000,
    "totalTokens": 2500000,
    "averageLatency": 1250,
    "successRate": 97.5,
    "topModels": [
      { "model": "claude-haiku-4-5-20251001", "requests": 3500, "tokens": 1750000 }
    ],
    "topAgents": [
      { "agent_id": "uuid", "requests": 3000, "tokens": 1500000 }
    ]
  }
}

---

GET /api/telemetry/logs

Paginated telemetry logs with advanced filters.

Query Parameters:

Param	Type	Default	Description
page	number	1	Page number
limit	number	50	Records per page (max: 100)
start_date	ISO date	-	Start date
end_date	ISO date	-	End date
agent_id	UUID	-	Filter by agent
api_key_id	UUID	-	Filter by API Key
provider	string	-	Filter by provider
status	string	-	success or error

Response:

{
  "data": [
    {
      "id": "uuid",
      "agent_id": "uuid",
      "provider": "anthropic",
      "model": "claude-haiku-4-5-20251001",
      "input_tokens": 1495,
      "output_tokens": 770,
      "total_tokens": 2265,
      "response_time_ms": 1350,
      "timestamp": "2026-01-07T14:30:00.000Z",
      "call_source": "agent.tool-loop"
    }
  ],
  "total": 5000,
  "pagination": { "page": 1, "limit": 50, "pages": 100 }
}

---

GET /api/telemetry/sessions

Aggregated metrics per conversation session.

Query Parameters:

Param	Type	Default	Description
limit	number	50	Number of sessions (max: 100)
start_date	ISO date	-	Start date
end_date	ISO date	-	End date
agent_id	UUID	-	Filter by agent

Response:

{
  "data": [
    {
      "session_id": "uuid",
      "agent_id": "uuid",
      "agent_name": "Sales Agent",
      "source": "trigger.webhook",
      "total_calls": 3,
      "total_tokens": 1890,
      "total_cost_usd": 0.033,
      "avg_latency_ms": 4166,
      "duration_ms": 207000,
      "errors": 0,
      "trigger_name": "eBarn Chat Integration",
      "user_query": "What is the price of urea?",
      "has_tool_calls": false
    }
  ],
  "total": 150
}

---

GET /api/telemetry/sessions/:sessionId

Detailed session view for debugging, including conversation history, execution logs, and routing decisions.

Response:

{
  "data": {
    "session": {
      "session_id": "uuid",
      "agent_id": "uuid",
      "total_calls": 3,
      "total_tokens": 1890,
      "total_cost_usd": 0.033
    },
    "executions": [
      {
        "id": "uuid",
        "status": "success",
        "execution_time_ms": 5980,
        "query": "What is the price of urea?",
        "agent_response": "Let me check the prices...",
        "resolved_context": { "city": "Goiania", "company": "Farm QW" },
        "tokens_used": 627
      }
    ],
    "conversation_history": [
      { "role": "user", "content": "What is the price of urea?" },
      { "role": "assistant", "content": "Let me check..." }
    ],
    "logs": [
      {
        "id": "uuid",
        "model": "claude-haiku-4-5-20251001",
        "provider": "anthropic",
        "total_tokens": 627,
        "cost_usd": 0.011,
        "response_time_ms": 4351,
        "call_source": "agent.tool-loop",
        "routing_decision": {
          "reasoning": "Economical model selected",
          "confidence": 0.9,
          "is_auto_routed": true,
          "selected_model": "anthropic.claude-haiku-4-5-20251001"
        },
        "fallback_chain": ["anthropic.claude-haiku-4-5-20251001", "openai.gpt-4.1-nano"]
      }
    ],
    "metrics": {
      "total_calls": 3,
      "total_tokens": 1890,
      "avg_response_time_ms": 4166
    }
  }
}

---

GET /api/telemetry/dashboard

Complete dashboard with all aggregated metrics.

Query Parameters:

Param	Type	Default	Description
start_date	ISO date	7 days ago	Start date
end_date	ISO date	now	End date

Response includes: summary, cache, fallback, top_models, by_provider, hourly_usage, by_call_source

---

GET /api/telemetry/tools-usage

Tool usage analysis across agents.

Response:

{
  "data": {
    "summary": {
      "total_tool_calls": 8500,
      "unique_tools": 15,
      "avg_tools_per_request": 1.7
    },
    "by_tool": [
      {
        "tool_name": "query_database",
        "total_calls": 3200,
        "success_rate": 99.2,
        "avg_latency_ms": 1800,
        "agents_using": 5
      }
    ]
  }
}

---

GET /api/telemetry/routing-analysis

Auto-routing decision analysis.

Response includes: summary (total_routed, auto_routed, fallback_triggered, avg_confidence), by_task_type, by_tier, score_distribution, fallback_reasons

---

GET /api/telemetry/latency-analysis

Latency analysis with percentiles.

Response:

{
  "data": {
    "summary": {
      "avg_latency_ms": 1250,
      "p50_ms": 800,
      "p95_ms": 3500,
      "p99_ms": 8000,
      "total_requests": 5000
    },
    "by_provider": {},
    "by_model_tier": {},
    "slow_requests": [],
    "hourly_trend": []
  }
}

Percentile	Meaning
p50	50% of requests are faster (median)
p95	95% of requests are faster
p99	99% of requests are faster

tip

Use p95 for realistic SLAs. Requests above p95 are typically outliers caused by cold starts, rate limits, or very long prompts.

---

Other Endpoints

Endpoint	Description
GET /api/telemetry/usage-by-hour	Hourly usage for trend charts (param: hours, default 24, max 168)
GET /api/telemetry/cache	Prompt caching performance report
GET /api/telemetry/loopgraph	Agent loop execution metrics (nodes, edges)
GET /api/telemetry/call-sources	Metrics by call origin (agent.tool-loop, api_key_public, etc.)
GET /api/telemetry/summary	Complete summary for dashboard widgets
GET /api/telemetry/graph	Execution graph metrics

---

Cache Recommendations

Endpoint	Recommended TTL
/summary, /dashboard	5 minutes
/cache, /tools-usage, /routing-analysis	5 minutes
/latency-analysis	2 minutes
/usage-by-hour	1 minute
/sessions	1 minute
/logs	30 seconds
/sessions/:id	30 seconds
/sessions/active	3 seconds

---

Error Codes

Code	Description
TELEMETRY_MISSING_DATE_RANGE	start_date and end_date are required
UNAUTHORIZED	Invalid or missing JWT
TENANT_NOT_FOUND	Tenant ID not found
INTERNAL_ERROR	Internal server error