Documentation

API Reference

REST API endpoints for traces, analytics, projects, and health.

API Reference

The TraceLLM backend exposes a REST API at http://127.0.0.1:8000with endpoints for traces, analytics, failures, projects, and health checks. All endpoints return JSON responses. The OpenAPI docs are available at /docs.

Health

Method	Path	Description
GET	/	Health check — returns {message: 'TraceLLM backend running'}

Health checkCopy

bash

GET /
Response 200:
{
  "message": "TraceLLM backend running"
}

Traces

Method	Path	Description
GET	/traces	List traces with filtering (status, model, project, latency, tokens)
GET	/traces/{trace_id}	Get a single trace by ID

GET /tracesCopy

bash

GET /traces?status=failed&limit=10&project_id=default
Response 200:
{
  "total": 3,
  "items": [
    {
      "trace_id": "tr_2kf9q3m1",
      "prompt": "Explain transformers",
      "latency": 3420.0,
      "token_count": 1247,
      "status": "failed",
      "steps": [...]
    }
  ]
}

Info

The GET /traces/{trace_id} endpoint returns a single TraceSchema object. A 404 is returned if the trace does not exist.

Analytics

Method	Path	Description
GET	/analytics	Aggregated analytics with summary, charts, and breakdowns

GET /analyticsCopy

bash

GET /analytics?project_id=default
Response 200:
{
  "summary": {
    "total_traces": 50,
    "success_rate": 92.0,
    "average_latency": 1240.5,
    "p95_latency": 3420.0,
    "total_token_usage": 62350,
    "failed_traces": 2,
    "warning_traces": 2,
    "retries": 5,
    "slow_requests": 8
  },
  "charts": [
    { "label": "14:00", "latency": 1100.0, "tokens": 4500, "traces": 5 }
  ],
  "status_breakdown": [
    { "key": "success", "count": 46 },
    { "key": "failed", "count": 2 }
  ],
  "model_breakdown": [
    { "key": "gpt-4o", "count": 30 },
    { "key": "gpt-4.1-mini", "count": 20 }
  ],
  "project_breakdown": [
    { "key": "default", "count": 50 }
  ],
  "recent_failures": [...]
}

Failures

Method	Path	Description
GET	/failures	Get categorized failures: failed traces, retries, and slow requests

GET /failuresCopy

bash

GET /failures?limit=10&project_id=default
Response 200:
{
  "failed_traces": [...],
  "retries": [...],
  "slow_requests": [...],
  "totals": {
    "failed_traces": 2,
    "retries": 3,
    "slow_requests": 8
  }
}

Projects

Method	Path	Description
GET	/projects	List all projects
POST	/projects	Create a new project with an API key
GET	/api-keys	List API keys, optionally filtered by project_id

POST /projectsCopy

bash

POST /projects?name=my-project&environment=production&description=My%20project
Response 201:
{
  "project": {
    "project_id": "my-project",
    "name": "my-project",
    "description": "My project",
    "created_at": "2026-05-31T14:22:10"
  },
  "api_key": {
    "key": "tlm_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "project_id": "my-project",
    "environment": "production",
    "created_at": "2026-05-31T14:22:10"
  }
}

Tip

API keys are shown only once at creation. Save them securely — they cannot be retrieved later.

WebSocket

Protocol	Path	Description
WS	/ws	Real-time trace event stream

Connect via WebSocket to receive trace.created events in real time. See the WebSocket documentation for the full protocol reference.