Analytics API

GET /api/analytics

Bucketed metrics over time. Returns event counts, tool call counts, error counts, average latency, and cost grouped by time bucket.

Query Parameters

Parameter	Type	Default	Description
from	string	24h ago	Start of time range (ISO 8601)
to	string	now	End of time range (ISO 8601)
granularity	string	hour	Bucket size: hour, day, or week
agentId	string	—	Filter to a specific agent

Response (200)

{
  "buckets": [
    {
      "bucket": "2026-02-08T10:00:00Z",
      "eventCount": 150,
      "toolCallCount": 45,
      "errorCount": 2,
      "avgLatencyMs": 234,
      "totalCostUsd": 1.23
    }
  ],
  "totals": {
    "eventCount": 1500,
    "toolCallCount": 450,
    "errorCount": 12,
    "avgLatencyMs": 218,
    "totalCostUsd": 12.34
  }
}

curl Example

curl "http://localhost:3400/api/analytics?from=2026-02-01&to=2026-02-08&granularity=day" \
  -H "Authorization: Bearer als_your_key"

---

GET /api/analytics/llm

LLM-specific analytics: aggregate metrics by model, provider, and time. Includes summary statistics, per-model breakdown, and time-bucketed series.

Query Parameters

Parameter	Type	Default	Description
from	string	24h ago	Start of time range (ISO 8601)
to	string	now	End of time range (ISO 8601)
granularity	string	hour	Bucket size: hour, day, or week
agentId	string	—	Filter to a specific agent
model	string	—	Filter to a specific model
provider	string	—	Filter to a specific provider

Response (200)

{
  "summary": {
    "totalCalls": 42,
    "totalCostUsd": 12.34,
    "totalInputTokens": 150000,
    "totalOutputTokens": 50000,
    "avgLatencyMs": 1250,
    "avgCostPerCall": 0.29
  },
  "byModel": [
    {
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514",
      "calls": 20,
      "costUsd": 8.50,
      "inputTokens": 100000,
      "outputTokens": 30000,
      "avgLatencyMs": 1500
    }
  ],
  "byTime": [
    {
      "bucket": "2026-02-08T10:00:00Z",
      "calls": 5,
      "costUsd": 1.20,
      "inputTokens": 15000,
      "outputTokens": 5000,
      "avgLatencyMs": 900
    }
  ]
}

curl Example

curl "http://localhost:3400/api/analytics/llm?from=2026-02-01&granularity=day&model=claude-sonnet-4-20250514" \
  -H "Authorization: Bearer als_your_key"

SDK Example

const analytics = await client.getLlmAnalytics({
  from: '2026-02-01',
  to: '2026-02-08',
  granularity: 'day',
});

console.log(analytics.summary);
// { totalCalls: 42, totalCostUsd: 12.34, ... }

console.log(analytics.byModel);
// [{ provider: "anthropic", model: "claude-sonnet-4-20250514", calls: 20, ... }]

---

GET /api/analytics/costs

Cost breakdown by agent and time period.

Query Parameters

Parameter	Type	Default	Description
from	string	24h ago	Start of time range (ISO 8601)
to	string	now	End of time range (ISO 8601)
granularity	string	day	Bucket size: hour, day, or week

Response (200)

{
  "byAgent": [
    {
      "agentId": "my-agent",
      "totalCostUsd": 5.67,
      "totalInputTokens": 125000,
      "totalOutputTokens": 42000,
      "totalTokens": 167000,
      "eventCount": 89
    }
  ],
  "overTime": [
    {
      "bucket": "2026-02-08T00:00:00Z",
      "totalCostUsd": 2.34,
      "eventCount": 45
    }
  ],
  "totals": {
    "totalCostUsd": 12.34,
    "totalInputTokens": 250000,
    "totalOutputTokens": 84000,
    "totalTokens": 334000
  }
}

curl Example

curl "http://localhost:3400/api/analytics/costs?from=2026-02-01&granularity=day" \
  -H "Authorization: Bearer als_your_key"

---

GET /api/analytics/agents

Per-agent metrics: session count, error rate, average duration, total cost.

Query Parameters

Parameter	Type	Default	Description
from	string	24h ago	Start of time range (ISO 8601)
to	string	now	End of time range (ISO 8601)

Response (200)

{
  "agents": [
    {
      "agentId": "my-agent",
      "sessionCount": 42,
      "totalEvents": 1500,
      "totalErrors": 12,
      "errorRate": 0.008,
      "totalCostUsd": 5.67,
      "avgDurationMs": 45000
    }
  ]
}

curl Example

curl "http://localhost:3400/api/analytics/agents?from=2026-02-01" \
  -H "Authorization: Bearer als_your_key"

---

GET /api/analytics/tools

Tool usage statistics: call frequency, error rate, and average duration per tool.

Query Parameters

Parameter	Type	Default	Description
from	string	24h ago	Start of time range (ISO 8601)
to	string	now	End of time range (ISO 8601)

Response (200)

{
  "tools": [
    {
      "toolName": "search_database",
      "callCount": 250,
      "errorCount": 3,
      "errorRate": 0.012,
      "avgDurationMs": 342
    },
    {
      "toolName": "send_email",
      "callCount": 15,
      "errorCount": 0,
      "errorRate": 0,
      "avgDurationMs": 1200
    }
  ]
}

curl Example

curl "http://localhost:3400/api/analytics/tools?from=2026-02-01" \
  -H "Authorization: Bearer als_your_key"