> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics & Monitoring

> Track your agent's performance, monitor costs, review conversations, and gain insights into usage patterns with real-time analytics.

# Analytics & Monitoring

thinnestAI provides comprehensive analytics to help you understand how your agents are performing, what they're costing, and where they can improve.

## Dashboard Overview

The main **Dashboard** shows aggregated metrics across all your agents:

| Metric                    | Description                                        |
| ------------------------- | -------------------------------------------------- |
| **Total Conversations**   | Number of chat and voice sessions                  |
| **Total Messages**        | Messages exchanged across all agents               |
| **Total Cost**            | USD spent on LLM tokens and voice minutes          |
| **Average Response Time** | Mean latency from message to response              |
| **Success Rate**          | Percentage of conversations completed successfully |
| **Active Agents**         | Number of agents handling traffic                  |

### Time Range Filters

View metrics for different periods:

* Last 24 hours
* Last 7 days
* Last 30 days
* Custom date range

## Agent Performance

Each agent has a dedicated **Performance** tab with detailed metrics:

### Response Metrics

| Metric                  | Description                               |
| ----------------------- | ----------------------------------------- |
| **Avg Response Time**   | Mean time to generate a response          |
| **p50 Latency**         | Median latency (50th percentile)          |
| **p95 Latency**         | 95th percentile latency                   |
| **Tokens per Response** | Average input + output tokens per message |

### Cost Metrics

| Metric                    | Description                   |
| ------------------------- | ----------------------------- |
| **Total Cost**            | Total USD spent by this agent |
| **Cost per Conversation** | Average cost per session      |
| **Input Tokens**          | Total input tokens consumed   |
| **Output Tokens**         | Total output tokens consumed  |
| **Voice Minutes**         | Total minutes of voice calls  |

### Quality Metrics

| Metric               | Description                                    |
| -------------------- | ---------------------------------------------- |
| **Success Rate**     | Conversations completed without errors         |
| **Error Rate**       | Percentage of failed conversations             |
| **Tool Call Rate**   | How often the agent uses tools                 |
| **Evaluation Score** | Average score from evaluations (if configured) |

### Via the API

```bash theme={null}
curl "https://api.thinnest.ai/agents/agent_abc123/summary?period=7d" \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

```json theme={null}
{
  "period": "7d",
  "total_sessions": 342,
  "total_messages": 1845,
  "total_cost_usd": 12.47,
  "avg_response_time_ms": 1240,
  "p50_latency_ms": 980,
  "p95_latency_ms": 2850,
  "success_rate": 0.97,
  "total_input_tokens": 485000,
  "total_output_tokens": 192000,
  "voice_minutes": 28.5,
  "avg_evaluation_score": 4.2
}
```

## Agent Tracing

Every agent interaction is traced for debugging and analysis:

### Trace Data

Each trace includes:

* **Input message** — What the user said
* **Agent reasoning** — The LLM's internal processing
* **Tool calls** — Which tools were called, with what arguments, and what they returned
* **Output message** — The agent's response
* **Token usage** — Input and output tokens
* **Latency** — Time for each step
* **Cost** — USD cost of this interaction
* **Errors** — Any errors that occurred

### Viewing Traces

```bash theme={null}
curl "https://api.thinnest.ai/agents/agent_abc123/traces?limit=20" \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

```json theme={null}
{
  "traces": [
    {
      "id": "trace_xyz",
      "session_id": "sess_123",
      "input": "What are your hours?",
      "output": "We're open Monday to Friday, 9 AM to 5 PM EST.",
      "tool_calls": [],
      "input_tokens": 145,
      "output_tokens": 28,
      "latency_ms": 890,
      "cost_usd": 0.0012,
      "status": "success",
      "created_at": "2026-03-06T14:30:00Z"
    }
  ]
}
```

## Voice Metrics

For voice agents, additional real-time metrics are available:

| Metric                     | Description                                  |
| -------------------------- | -------------------------------------------- |
| **Active Calls**           | Currently ongoing voice sessions             |
| **Call Duration**          | Average and total call length                |
| **Voice Latency**          | Time from speech end to agent response start |
| **Transcription Accuracy** | Quality of speech-to-text                    |
| **Interruption Rate**      | How often the user interrupts the agent      |

### Real-Time Voice Metrics (WebSocket)

Subscribe to live voice metrics during active calls:

```javascript theme={null}
const ws = new WebSocket('wss://api.thinnest.ai/voice/metrics/agent_abc123/ws');

ws.onmessage = (event) => {
  const metrics = JSON.parse(event.data);
  console.log('Active calls:', metrics.active_calls);
  console.log('Avg latency:', metrics.avg_latency_ms);
};
```

## Channel Analytics

Track message volume and quality per channel:

```bash theme={null}
curl "https://api.thinnest.ai/analytics/channels?agent_id=agent_abc123&period=30d" \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

```json theme={null}
{
  "channels": {
    "voice": {
      "total_sessions": 180,
      "total_messages": 1200,
      "success_rate": 0.96,
      "avg_response_time_ms": 1500
    },
    "chat": {
      "total_sessions": 420,
      "total_messages": 2800,
      "success_rate": 0.99,
      "avg_response_time_ms": 850
    },
    "widget": {
      "total_sessions": 95,
      "total_messages": 380,
      "success_rate": 0.98,
      "avg_response_time_ms": 920
    }
  }
}
```

## Usage & Billing Metrics

Monitor your spending in real-time:

```bash theme={null}
curl "https://api.thinnest.ai/metrics/usage" \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

```json theme={null}
{
  "balance_usd": 47.23,
  "usage_today_usd": 3.12,
  "usage_this_month_usd": 89.45,
  "top_agents_by_cost": [
    { "agent_id": "agent_abc123", "name": "Support Agent", "cost_usd": 45.20 },
    { "agent_id": "agent_def456", "name": "Sales Caller", "cost_usd": 32.10 }
  ],
  "breakdown": {
    "llm_tokens": 72.30,
    "voice_minutes": 15.50,
    "scraping": 1.65
  }
}
```

## Audit Logging

For compliance and security, all platform actions are logged:

| Event                          | Data Captured                          |
| ------------------------------ | -------------------------------------- |
| Agent created/updated/deleted  | Who, when, what changed                |
| Tool configuration changes     | Old and new config (keys redacted)     |
| Phone number assigned/released | Agent, number, timestamp               |
| Team member changes            | Invitations, role changes, removals    |
| Billing events                 | Top-ups, subscription changes, refunds |

### View Audit Logs

```bash theme={null}
curl "https://api.thinnest.ai/admin/audit/logs?limit=50" \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

```json theme={null}
{
  "logs": [
    {
      "id": 1234,
      "user_id": "auth0|abc123",
      "action": "agent.update",
      "resource_type": "agent",
      "resource_id": "agent_abc123",
      "details": {
        "changed_fields": ["instructions", "temperature"]
      },
      "ip_address": "203.0.113.42",
      "created_at": "2026-03-06T15:00:00Z"
    }
  ]
}
```

## Deployment History

Track all deployments and version changes:

```bash theme={null}
curl "https://api.thinnest.ai/deployments/agent_abc123/history" \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

```json theme={null}
{
  "deployments": [
    {
      "id": 5,
      "version": "v3",
      "status": "active",
      "deployed_at": "2026-03-06T12:00:00Z",
      "deployed_by": "user@example.com",
      "changes": "Updated system prompt and added Gmail tool"
    },
    {
      "id": 4,
      "version": "v2",
      "status": "superseded",
      "deployed_at": "2026-03-04T09:00:00Z"
    }
  ]
}
```

### Rollback

If a deployment causes issues, roll back to a previous version:

```bash theme={null}
curl -X POST "https://api.thinnest.ai/deployments/agent_abc123/rollback" \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "version_id": 4 }'
```

## Alerts & Notifications

Configure alerts for important metrics:

* **Error rate spike** — Get notified when error rate exceeds a threshold
* **High latency** — Alert when response time degrades
* **Budget threshold** — Warning when spending approaches a limit
* **Low balance** — Alert before your balance runs out

## Best Practices

* **Check analytics weekly** — Spot trends before they become problems.
* **Use traces for debugging** — When an agent misbehaves, traces show exactly what happened.
* **Monitor cost per conversation** — Ensure your agents are cost-effective.
* **Set up alerts** — Don't wait for users to report issues.
* **Compare agent versions** — After deploying changes, compare metrics to the previous version.
* **Review audit logs** — Track who changed what, especially in team environments.