REST API

The tael CLI is a thin client over this REST API, so anything the CLI does, you can do directly over HTTP — useful for tool-use integrations and custom dashboards. The base URL defaults to http://127.0.0.1:7701.

All responses are JSON. Errors return a non-2xx status with a {"error": "..."} body.

Health

Name
GET /healthz
Description
Liveness check; returns ok.
Name
GET /readyz
Description
Readiness check including storage.

curl http://127.0.0.1:7701/healthz

Traces

Name
GET /api/v1/traces
Description
Filter spans. Query params: service, operation, min_duration_ms, max_duration_ms, status, attribute (repeatable, key=value), text, last, limit. Response: {"spans": [...]}.
Name
GET /api/v1/traces/{trace_id}
Description
Full trace. Response: {"trace_id", "span_count", "spans": [...]}.
Name
GET /api/v1/traces/live
Description
SSE stream of trace batches. Query params: service, status.

curl 'http://127.0.0.1:7701/api/v1/traces?status=error&last=1h'
curl http://127.0.0.1:7701/api/v1/traces/abc123def456

Services

Name
GET /api/v1/services
Description
Response: {"services": [{name, span_count, trace_count, avg_duration_ms, error_rate}, ...]}.

Logs

Name
GET /api/v1/logs
Description
Query params: service, severity, body_contains, trace_id, last, limit. Response: {"logs": [...], "count": N}.
Name
GET /api/v1/logs/live
Description
SSE stream of log records. Query params: service, severity.

Metrics

Name
GET /api/v1/metrics
Description
Simple filter. Query params: service, name, type, last, limit. Response: {"metrics": [...], "count": N}.
Name
GET /api/v1/metrics/query
Description
PromQL subset. Query params: query, last. Response: {"query", "series": [...], "count": N}.

Summary, anomalies, correlate

Name
GET /api/v1/summary
Description
Query params: last, service. Response: {"window_seconds", "traces", "top_services", "top_error_operations", "logs", "metrics"}.
Name
GET /api/v1/anomalies
Description
Query params: last, baseline, service. Response: {"current_seconds", "baseline_seconds", "anomalies": [...]}.
Name
GET /api/v1/correlate
Description
Query param: trace. Response: {"trace_id", "span_count", "services", "start_time", "end_time", "duration_ms", "error_count", "logs": [...], "metrics": [...]}.

SQL

Name
GET /api/v1/sql
Description
Query param: query (SELECT / WITH only). Response: {"rows": [...], "count": N}.

Comments

Name
GET /api/v1/traces/{trace_id}/comments
Description
Response: {"comments": [...], "count": N}.
Name
POST /api/v1/traces/{trace_id}/comments
Description
Body: {"body": "...", "author": "...", "span_id": "..."} (span_id optional). Response: {"id", "created_at"}.

curl -X POST http://127.0.0.1:7701/api/v1/traces/abc123def456/comments \
  -H 'content-type: application/json' \
  -d '{"body":"Root cause: expired DB pool","author":"oncall-bot"}'

Blobs

Content-addressed storage for LLM payloads and oversized log bodies (see Storage & Blobs).

Name
GET /api/v1/blobs/{sha256}
Description
Retrieve a blob by hash. 200 with raw bytes, or 404.
Name
POST /api/v1/blobs
Description
Store raw bytes. Response: {"sha256", "size"}.

Evals

Name
GET /api/v1/evals/runs
Description
List recent runs. Response: {"runs": [...], "count": N}.
Name
GET /api/v1/evals/runs/{run_id}
Description
One run summary.
Name
GET /api/v1/evals/runs/{run_id}/cases
Description
Cases in a run.
Name
GET /api/v1/evals/runs/{run_id}/scores
Description
Scores in a run.
Name
GET /api/v1/evals/runs/{run_id}/compare?baseline={run_id}
Description
Compare two runs.
Name
POST /api/v1/evals/scores
Description
Ingest JSONL score records.

Ingest

Name
POST /api/v1/write
Description
Prometheus remote-write v1 (snappy-compressed protobuf). Points are stored with metric_type = unknown (v1 carries no type info). Labels map __name__ → metric name, service.name/job → service, the rest → attributes.

OTLP traces, logs, and metrics are ingested over gRPC on :4317, not this REST API. The REST API on :7701 is the query and management surface.