Skip to content
Acenta Docs

Observability API

Endpoints for observability features.

Traces

Section titled “Traces”

Create Span

Section titled “Create Span”
POST /api/v1/observe/traces

Request:

{
  "trace_id": "tr_xxx",
  "span_id": "sp_xxx",
  "parent_span_id": "sp_parent",
  "name": "process_document",
  "start_time": "2026-01-01T12:00:00Z",
  "end_time": "2026-01-01T12:00:01Z",
  "status": "ok",
  "attributes": {
    "document_id": "doc-123",
    "pages": 10
  }
}

Query Traces

Section titled “Query Traces”
GET /api/v1/observe/traces

Query parameters:

  • start_time - Start of time range (ISO 8601)
  • end_time - End of time range
  • agent_id - Filter by agent
  • status - Filter by status (ok, error)
  • min_duration_ms - Minimum duration
  • limit - Max results

Get Trace

Section titled “Get Trace”
GET /api/v1/observe/traces/{trace_id}

Response:

{
  "data": {
    "trace_id": "tr_xxx",
    "spans": [
      {
        "span_id": "sp_xxx",
        "name": "process_document",
        "start_time": "...",
        "end_time": "...",
        "duration_ms": 1000,
        "status": "ok",
        "attributes": {...}
      }
    ],
    "duration_ms": 1500
  }
}

Logs

Section titled “Logs”

Write Log

Section titled “Write Log”
POST /api/v1/observe/logs

Request:

{
  "level": "info",
  "message": "Document processed",
  "timestamp": "2026-01-01T12:00:00Z",
  "trace_id": "tr_xxx",
  "span_id": "sp_xxx",
  "attributes": {
    "document_id": "doc-123"
  }
}

Query Logs

Section titled “Query Logs”
GET /api/v1/observe/logs

Query parameters:

  • start_time - Start of time range
  • end_time - End of time range
  • level - Filter by level (debug, info, warn, error)
  • search - Full-text search
  • trace_id - Filter by trace
  • limit - Max results

Costs

Section titled “Costs”

Record Cost

Section titled “Record Cost”
POST /api/v1/observe/costs

Request:

{
  "span_id": "sp_xxx",
  "model": "gpt-4",
  "input_tokens": 1500,
  "output_tokens": 500,
  "cost_usd": 0.045
}

Query Costs

Section titled “Query Costs”
GET /api/v1/observe/costs

Query parameters:

  • start_time - Start of time range
  • end_time - End of time range
  • group_by - Group by fields (agent_id, model, date)

Response:

{
  "data": {
    "items": [
      {
        "agent_id": "doc-processor",
        "model": "gpt-4",
        "total_cost": 45.50,
        "total_input_tokens": 150000,
        "total_output_tokens": 50000
      }
    ],
    "total_cost": 45.50
  }
}

Alerts

Section titled “Alerts”

Create Alert

Section titled “Create Alert”
POST /api/v1/observe/alerts

Threshold alert:

{
  "name": "High Error Rate",
  "condition": {
    "type": "threshold",
    "metric": "error_count",
    "operator": ">",
    "threshold": 10,
    "window": "5m"
  },
  "channels": [
    {"type": "email", "to": "ops@example.com"}
  ]
}

Anomaly alert:

{
  "name": "Latency Anomaly",
  "condition": {
    "type": "anomaly",
    "metric": "request_latency_ms",
    "sensitivity": 2.0,
    "baseline_window": "24h"
  },
  "channels": [...]
}

Absence alert:

{
  "name": "Missing Data",
  "condition": {
    "type": "absence",
    "metric": "heartbeat_count",
    "missing_for": "5m"
  },
  "channels": [...]
}

List Alerts

Section titled “List Alerts”
GET /api/v1/observe/alerts

Get Alert

Section titled “Get Alert”
GET /api/v1/observe/alerts/{alert_id}

Update Alert

Section titled “Update Alert”
PUT /api/v1/observe/alerts/{alert_id}

Delete Alert

Section titled “Delete Alert”
DELETE /api/v1/observe/alerts/{alert_id}

Get Alert History

Section titled “Get Alert History”
GET /api/v1/observe/alerts/{alert_id}/history

Dashboard

Section titled “Dashboard”

Get Dashboard Data

Section titled “Get Dashboard Data”
GET /api/v1/observe/dashboard?time_range={range}

Time range: 1h, 6h, 24h, 7d, 30d

Response:

{
  "data": {
    "total_requests": 10000,
    "error_count": 50,
    "error_rate": 0.005,
    "p50_latency_ms": 25,
    "p95_latency_ms": 100,
    "p99_latency_ms": 250,
    "total_cost": 123.45
  }
}

Metrics

Section titled “Metrics”

Query Metrics

Section titled “Query Metrics”
GET /api/v1/observe/metrics

Query parameters:

  • metric - Metric name
  • start_time - Start of time range
  • end_time - End of time range
  • aggregation - avg, sum, min, max, p50, p95, p99
  • interval - Bucket interval (1m, 5m, 1h, 1d)
  • group_by - Group by fields

OTLP

Section titled “OTLP”

Configure Export

Section titled “Configure Export”
POST /api/v1/observe/otlp/config

Request:

{
  "endpoint": "https://otel-collector.example.com:4318",
  "headers": {"Authorization": "Bearer xxx"},
  "export_traces": true,
  "export_logs": true,
  "sample_rate": 0.1
}

OTLP Trace Ingestion

Section titled “OTLP Trace Ingestion”
POST /api/v1/observe/otlp/v1/traces

Standard OTLP format.

OTLP Log Ingestion

Section titled “OTLP Log Ingestion”
POST /api/v1/observe/otlp/v1/logs

Standard OTLP format.