Omni Usage Logs

---
name: omni-usage-logs
description: Access detailed call logs and usage analytics. Filter by provider, model, time range, status, and cost. Export logs and aggregate token usage across all connections.
---
<!-- generated by src/lib/agentSkills/generator.ts; manual edits will be overwritten -->

## Overview

Access detailed call logs and usage analytics. Filter by provider, model, time range, status, and cost. Export logs and aggregate token usage across all connections.

## Authentication

All requests require a valid Bearer token or session cookie. Obtain a token via `POST /api/auth/login` or configure `REQUIRE_API_KEY=false` for local development.

## Endpoints

### GET /api/usage/analytics

Get usage analytics

```bash
curl https://localhost:20128/api/usage/analytics \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
```

### GET /api/usage/call-logs

Get call logs

```bash
curl https://localhost:20128/api/usage/call-logs \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
```

### GET /api/usage/call-logs/{id}

Get a specific call log

```bash
curl https://localhost:20128/api/usage/call-logs/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
```

### GET /api/usage/{connectionId}

Get usage for a specific connection

```bash
curl https://localhost:20128/api/usage/{connectionId} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
```

### GET /api/usage/history

Get usage history

```bash
curl https://localhost:20128/api/usage/history \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
```

### GET /api/usage/logs

Get usage logs

```bash
curl https://localhost:20128/api/usage/logs \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
```

### GET /api/usage/proxy-logs

Get proxy logs

```bash
curl https://localhost:20128/api/usage/proxy-logs \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
```

### GET /api/usage/request-logs

Get request logs

```bash
curl https://localhost:20128/api/usage/request-logs \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
```

### GET /api/usage/budget

Get usage budget status

Returns current budget limits and consumption.

```bash
curl https://localhost:20128/api/usage/budget \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
```

### POST /api/usage/budget

Configure usage budget

Set or update budget limits for usage tracking.

```bash
curl -X POST https://localhost:20128/api/usage/budget \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### GET /api/usage/cache-health

Get prompt-cache health summary

Summarizes the `write/read` cache ratio from `call_logs` for a time window:
distribution (p50/p90/p99/max of cache-write tokens), warm/cold/rewrite/uncached
call counts, the "heavy write" outlier share (10x the window median, floored at
1024 tokens — Anthropic's cache-creation minimum), and a per-model breakdown.
Only successful (`status = 200`) calls with a non-null cache column are counted.


```bash
curl https://localhost:20128/api/usage/cache-health \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
```

### GET /api/usage/model-latency-stats

Get per-model/provider latency statistics

Aggregates `usage_history` rows into per-(provider, model) latency stats (avg/p50/p95/p99, std-dev, TTFT, tokens/sec) over a rolling window. Falls back from successful-only to all-sample rows when the successful count is below `minSamples`.

```bash
curl https://localhost:20128/api/usage/model-latency-stats \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
```

## Payloads

See the full OpenAPI specification at `GET /api/openapi/spec` or `docs/openapi.yaml` for detailed request/response schemas.