Skip to main content

Telemetry Endpoints

Usage metrics, logging, and performance monitoring endpoints.

Authentication Required

All telemetry endpoints require JWT authentication and x-tenant-id header.

Headers:

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

GET /api/telemetry/health​

Health check for the telemetry service.

Authentication: Not required

Response:

{
  "status": "healthy",
  "version": "v2",
  "timestamp": "2025-12-19T02:53:28.063Z",
  "endpoints": [
    "/metrics",
    "/logs",
    "/graph",
    "/sessions",
    "/usage-by-hour",
    "/dashboard",
    "/loopgraph",
    "/cache",
    "/call-sources"
  ]
}

GET /api/telemetry/metrics​

Get aggregated telemetry metrics for a specific period.

Authentication: JWT + x-tenant-id required

Query Parameters:

ParamTypeRequiredDescription
start_dateISO dateYesStart date
end_dateISO dateYesEnd date
agent_idUUIDNoFilter by agent
providerstringNoFilter by provider
modelstringNoFilter by model
statusstringNosuccess or error

Example:

curl "http://localhost:3001/api/telemetry/metrics?start_date=2025-12-01T00:00:00Z&end_date=2025-12-31T23:59:59Z" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-tenant-id: $TENANT_ID"

Response:

{
  "data": {
    "totalRequests": 118,
    "totalTokens": 166225,
    "averageLatency": 3488,
    "successRate": 96.6,
    "successCount": 114,
    "errorCount": 4,
    "topModels": [
      {
        "model": "claude-3-5-haiku-20241022",
        "requests": 113,
        "tokens": 161861
      }
    ],
    "topAgents": [
      {
        "agent_id": "72bfe7d2-cc41-48c7-9ec3-52863cee2f9f",
        "requests": 118,
        "tokens": 166225
      }
    ]
  }
}

GET /api/telemetry/logs​

Get paginated log entries.

Authentication: JWT + x-tenant-id required

Query Parameters:

ParamTypeDefaultDescription
pagenumber1Page number
limitnumber50Records per page (max: 100)
start_dateISO date-Start date
end_dateISO date-End date
agent_idUUID-Filter by agent
providerstring-Filter by provider
modelstring-Filter by model
statusstring-success or error
order_bystringtimestampField to order by
order_dirstringdescasc or desc

Response:

{
  "data": [
    {
      "id": "353843ef-0d2b-4a29-bba6-6da920c74d86",
      "user_id": "469c99dc-6021-4aa8-9a88-d0e18a481545",
      "agent_id": "72bfe7d2-cc41-48c7-9ec3-52863cee2f9f",
      "provider": "anthropic",
      "model": "claude-3-5-haiku-20241022",
      "input_tokens": 1495,
      "output_tokens": 770,
      "total_tokens": 2265,
      "response_time_ms": 13161,
      "timestamp": "2025-12-19T01:27:31.736694+00:00",
      "call_source": "agent.tool-loop",
      "metadata": {
        "source": "api_response",
        "input_preview": "# Assistente Financeiro...",
        "output_preview": "Vou realizar uma análise..."
      }
    }
  ],
  "total": 118,
  "pagination": {
    "page": 1,
    "limit": 50,
    "pages": 24
  }
}

GET /api/telemetry/usage-by-hour​

Get usage aggregated by hour.

Authentication: JWT + x-tenant-id required

Query Parameters:

ParamTypeDefaultDescription
hoursnumber24Number of hours (max: 168)
agent_idUUID-Filter by agent

Example:

curl "http://localhost:3001/api/telemetry/usage-by-hour?hours=24" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-tenant-id: $TENANT_ID"

Response:

{
  "data": [
    {
      "hour": "2025-12-18 19:00",
      "requests": 59,
      "tokens": 98094
    },
    {
      "hour": "2025-12-18 20:00",
      "requests": 29,
      "tokens": 28609
    }
  ]
}

GET /api/telemetry/sessions​

Get metrics aggregated by session.

Authentication: JWT + x-tenant-id required

Query Parameters:

ParamTypeDefaultDescription
limitnumber50Number of sessions (max: 100)
start_dateISO date-Start date
end_dateISO date-End date
agent_idUUID-Filter by agent

Response:

{
  "data": [
    {
      "session_id": "abc123",
      "agent_id": "72bfe7d2-cc41-48c7-9ec3-52863cee2f9f",
      "first_interaction": "2025-12-18T22:08:17.949555+00:00",
      "last_interaction": "2025-12-19T01:27:31.736694+00:00",
      "total_calls": 118,
      "total_tokens": 166225,
      "total_latency_ms": 411561,
      "errors": 4,
      "avg_latency_ms": 3488,
      "duration_ms": 11953787
    }
  ],
  "total": 1
}

GET /api/telemetry/dashboard​

Get a complete dashboard with all aggregated metrics.

Authentication: JWT + x-tenant-id required

Query Parameters:

ParamTypeDefaultDescription
start_dateISO date7 days agoStart date
end_dateISO datenowEnd date

Example:

curl "http://localhost:3001/api/telemetry/dashboard" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-tenant-id: $TENANT_ID"

Response:

{
  "data": {
    "summary": {
      "period_days": 7,
      "total_calls": 118,
      "total_tokens": 166225,
      "avg_latency_ms": 3487.81,
      "success_rate_pct": 96.61
    },
    "cache": {
      "calls_with_cache": 74,
      "cache_hit_rate_pct": 151.83,
      "total_cached_tokens": 222215
    },
    "fallback": {
      "total_errors": 4,
      "total_fallbacks": 0,
      "fallback_rate_pct": 0
    },
    "top_models": [
      {
        "model": "claude-3-5-haiku-20241022",
        "provider": "anthropic",
        "calls": 113,
        "avg_latency_ms": 3554.64
      }
    ],
    "by_provider": [
      {
        "provider": "anthropic",
        "calls": 114
      }
    ],
    "hourly_usage": [
      {
        "hour": "2025-12-18T22:00:00+00:00",
        "calls": 59,
        "tokens": 98094
      }
    ],
    "by_call_source": [
      {
        "call_source": "agent.tool-loop",
        "calls": 77,
        "avg_latency_ms": 3888.31
      }
    ]
  }
}

GET /api/telemetry/cache​

Get detailed cache performance report (Prompt Caching).

Authentication: JWT + x-tenant-id required

Query Parameters:

ParamTypeDefaultDescription
start_dateISO date30 days agoStart date
end_dateISO datenowEnd date

Response:

{
  "data": {
    "summary": {
      "total_calls": 118,
      "calls_with_cache_hit": 74,
      "total_cached_tokens": 222215,
      "total_cache_creation_tokens": 40894,
      "cache_hit_rate_pct": 151.83
    },
    "by_day": [
      {
        "day": "2025-12-19",
        "cache_hits": 11,
        "cached_tokens": 28876
      }
    ],
    "by_model": [
      {
        "model": "claude-3-5-haiku-20241022",
        "provider": "anthropic",
        "total_calls": 113,
        "cache_hits": 74,
        "cached_tokens": 222215
      }
    ]
  }
}
Prompt Caching

Prompt Caching allows reusing tokens from previous prompts, significantly reducing latency in subsequent calls. The cache hit rate indicates cache efficiency for your workload.

GET /api/telemetry/loopgraph​

Get detailed metrics from the agent execution system (LoopGraph).

Authentication: JWT + x-tenant-id required

Query Parameters:

ParamTypeDescription
start_dateISO dateStart date
end_dateISO dateEnd date
agent_idUUIDFilter by agent

Response:

{
  "data": {
    "summary": {
      "total_executions": 118,
      "avg_latency_ms": 3487.81,
      "total_tokens": 166225,
      "unique_sessions": 0
    },
    "nodes": [
      {
        "node": "agent",
        "executions": 99,
        "total_tokens": 141297,
        "avg_latency_ms": 3416.75,
        "error_rate_pct": 0
      }
    ],
    "edges": []
  }
}

GET /api/telemetry/call-sources​

Get metrics aggregated by call source.

Authentication: JWT + x-tenant-id required

Response:

{
  "data": [
    {
      "call_source": "agent.tool-loop",
      "total_calls": 77,
      "total_tokens": 135007,
      "avg_latency_ms": 3888.31,
      "success_rate_pct": 100
    },
    {
      "call_source": "agent.intent-check",
      "total_calls": 16,
      "total_tokens": 4286,
      "avg_latency_ms": 1398.75,
      "success_rate_pct": 100
    },
    {
      "call_source": "agent.light-response",
      "total_calls": 6,
      "total_tokens": 2004,
      "avg_latency_ms": 2746.33,
      "success_rate_pct": 100
    }
  ]
}

Call Sources:

SourceDescription
agent.tool-loopTool execution in agent loop
agent.intent-checkUser intent classification
agent.light-responseLight responses (greetings, help)
Central.LLM.ControllerDirect controller calls

GET /api/telemetry/graph​

Get execution graph metrics.

Authentication: JWT + x-tenant-id required

Query Parameters:

ParamTypeDescription
start_dateISO dateStart date
end_dateISO dateEnd date
agent_idUUIDFilter by agent

Response:

{
  "data": {
    "nodes": [],
    "edges": [],
    "summary": {
      "total_executions": 118,
      "unique_nodes": 0,
      "unique_edges": 0
    }
  }
}

Error Codes​

CodeDescription
TELEMETRY_MISSING_DATE_RANGEstart_date and end_date are required
INTERNAL_ERRORInternal server error
UNAUTHORIZEDInvalid or missing JWT token
TENANT_NOT_FOUNDTenant ID not found

Error Response:

{
  "error": {
    "code": "TELEMETRY_MISSING_DATE_RANGE",
    "message": "start_date e end_date são obrigatórios"
  }
}

Caching Recommendations​

EndpointRecommended TTL
/dashboard5 minutes
/cache5 minutes
/loopgraph5 minutes
/usage-by-hour1 minute
/logs30 seconds