---
title: "Agent Observability"
description: "Query traces, metrics, and cost breakdowns for deployed agents"
canonical: "https://docs.ainative.studio/docs/agent-cloud/observability"
last-updated: "2026-10-03T21:47:10.764Z"
---

# Agent Observability

Source: https://docs.ainative.studio/docs/agent-cloud/observability

> Query traces, metrics, and cost breakdowns for deployed agents

# 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.

```bash
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:**
```json
{
  "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.

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

**Response:**
```json
{
  "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.

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

**Response:**
```json
{
  "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 |