Agent Observability

Monitor deployed agents with traces, aggregated metrics, and cost breakdowns.

Base path: /api/v1/cloud/observability

GET /traces

Query agent execution traces with filtering and pagination.

curl "https://api.ainative.studio/api/v1/cloud/observability/traces?agent_id=agent-abc&trace_type=llm&page=1&page_size=20" \
  -H "Authorization: Bearer $TOKEN"

Query Parameters:

Parameter	Type	Default	Description
agent_id	string	required	Agent to query traces for
start_time	datetime	—	Start of time range (ISO 8601)
end_time	datetime	—	End of time range (ISO 8601)
trace_type	string	—	Filter: tool, llm, memory, a2a
page	int	1	Page number
page_size	int	20	Results per page (max 100)

Response:

{
  "traces": [
    {
      "trace_id": "trc-abc123",
      "agent_id": "agent-abc",
      "trace_type": "llm",
      "operation": "chat.completions",
      "start_time": "2026-04-03T12:00:00Z",
      "duration_ms": 845,
      "status": "success",
      "metadata": {
        "model": "llama-3.3-70b-instruct",
        "tokens_in": 150,
        "tokens_out": 320
      }
    }
  ],
  "total": 1250,
  "page": 1,
  "page_size": 20
}

GET /metrics/{agent_id}

Aggregated metrics: request count, latency percentiles, error rates, and token usage.

curl "https://api.ainative.studio/api/v1/cloud/observability/metrics/agent-abc?period=24h" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "agent_id": "agent-abc",
  "period": "24h",
  "request_count": 1542,
  "error_count": 12,
  "error_rate": 0.0078,
  "latency": {
    "p50_ms": 120,
    "p95_ms": 450,
    "p99_ms": 890
  },
  "llm_tokens": {
    "input_tokens": 245000,
    "output_tokens": 180000,
    "total_tokens": 425000
  },
  "memory_operations": {
    "reads": 3200,
    "writes": 890
  }
}

GET /costs/{agent_id}

Cost breakdown by resource type for billing insights.

curl "https://api.ainative.studio/api/v1/cloud/observability/costs/agent-abc?period=7d" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "agent_id": "agent-abc",
  "period": "7d",
  "total_cost_usd": 12.45,
  "breakdown": [
    {"resource": "llm_inference", "cost_usd": 8.20, "units": "425K tokens"},
    {"resource": "compute", "cost_usd": 2.80, "units": "168 vCPU-hours"},
    {"resource": "memory_ops", "cost_usd": 0.95, "units": "4,090 operations"},
    {"resource": "a2a_messages", "cost_usd": 0.50, "units": "100 messages"}
  ]
}

Trace Types

Type	Description	Tracked Fields
tool	Agent tool execution	tool name, duration, success/failure
llm	LLM API calls	model, tokens in/out, latency
memory	ZeroDB/ZeroMemory operations	operation type, vector count
a2a	Agent-to-agent interactions	target agent, message type, latency