← Back to Documentation

REST API Reference

Complete reference for Kalibr's backend REST API for querying traces, costs, and performance metrics.

Base URL

http://localhost:8001/api

All endpoints are prefixed with /api

GET /api/otel/spans

Query all recorded spans with optional filtering.

Query Parameters

Parameter Type Default Description
vendor string — Filter by provider (openai, anthropic, google)
model string — Filter by model name
trace_id string — Filter by trace ID
hours int 24 Look-back window (in hours)
limit int 100 Max number of results
offset int 0 Pagination offset

Example Request

curl "http://localhost:8001/api/otel/spans?vendor=openai&limit=10" | jq .

Example Response

{
  "spans": [
    {
      "trace_id": "dd88823c-745d-4ea1-bd17-0f8437f1b478",
      "span_id": "abc123def4567890",
      "name": "openai.chat.completions.create",
      "provider": "openai",
      "model": "gpt-4o-mini",
      "duration_ms": 450,
      "cost_usd": 0.000025,
      "status": "OK",
      "attributes": {
        "input_tokens": 120,
        "output_tokens": 80,
        "total_tokens": 200
      },
      "timestamp": "2025-11-07T10:30:00.000Z"
    }
  ],
  "count": 1,
  "source": "clickhouse"
}

GET /api/otel/metrics

Aggregated performance and cost metrics.

Query Parameters

  • vendor (string) – Filter by provider
  • model (string) – Filter by model
  • hours (int, default 24) – Look-back window

Example Request

curl "http://localhost:8001/api/otel/metrics?vendor=openai&hours=24" | jq .

Example Response

{
  "total_spans": 1250,
  "total_cost": 1.45,
  "avg_duration_ms": 380,
  "p95_duration_ms": 650,
  "by_vendor": {
    "openai": { "count": 800, "cost": 0.95 },
    "anthropic": { "count": 300, "cost": 0.35 }
  },
  "by_model": {
    "gpt-4o-mini": { "count": 500, "cost": 0.45 },
    "claude-3-haiku-20240307": { "count": 300, "cost": 0.35 }
  }
}

GET /api/health

Check Kalibr backend status and connected databases.

Example Request

curl http://localhost:8001/api/health

Response

{
  "status": "ok",
  "clickhouse": "connected",
  "mongodb": "connected",
  "version": "1.5.0"
}

Common Use Cases

Get all OpenAI spans from the last hour

curl "http://localhost:8001/api/otel/spans?vendor=openai&hours=1"

Get expensive spans (cost > $0.01)

curl "http://localhost:8001/api/otel/spans?min_cost=0.01"

View metrics for the last 7 days

curl "http://localhost:8001/api/otel/metrics?hours=168"

Authentication

Development: No authentication required by default.

Production: Use an API key header:

curl -H "X-API-Key: your-api-key" http://localhost:8001/api/otel/spans
← SDK Integration System Architecture →