API Reference
claude-telemetry has three main components, each with its own interface. This section documents all commands, endpoints, and data formats.
Components
Agent CLI
The Python agent that runs on each PC. It reads Claude Code's JSONL logs and syncs data to Supabase.
Worker Endpoints
The Cloudflare Worker that proxies requests between the dashboard and Supabase. Handles authentication, authorization, and data access.
Supabase Schema
The PostgreSQL database schema used to store usage data. Managed through Supabase with Row-Level Security.
Tables:
| Table | Description |
|---|---|
usage_data | Core table storing all session and token data |
auth.users | Supabase-managed user authentication table |
Key columns in usage_data:
| Column | Type | Description |
|---|---|---|
id | UUID | Primary key |
machine_id | TEXT | Unique identifier for the source machine |
machine_name | TEXT | Human-friendly machine label |
session_id | TEXT | Claude Code session identifier |
timestamp | TIMESTAMPTZ | When the session occurred |
model | TEXT | Model used (e.g., "opus-4", "sonnet-4") |
input_tokens | BIGINT | Input tokens consumed |
output_tokens | BIGINT | Output tokens consumed |
cache_read_tokens | BIGINT | Cache read tokens |
cache_write_tokens | BIGINT | Cache write tokens |
cost_usd | NUMERIC(10,6) | Calculated cost in USD |
project_path | TEXT | Directory where Claude Code was run |
duration_seconds | INTEGER | Session duration |
metadata | JSONB | Additional session metadata |
created_at | TIMESTAMPTZ | Record creation timestamp |