Usage Tracking

Per-request logging with cost calculation and analytics.

Overview

Artemis logs every API request with detailed metrics for cost tracking, usage analysis, and debugging.

URL: https://artemis.meetrhea.com/logs

What's Tracked

Every request logs:

Field	Description
request_id	Unique identifier
api_key_id	Which Artemis key was used
provider_key_id	Which provider key was used
provider	Provider name (openai, anthropic, etc.)
model	Model used
endpoint	API endpoint called
prompt_tokens	Input token count
completion_tokens	Output token count
total_tokens	Sum of tokens
input_cost	Cost of input tokens
output_cost	Cost of output tokens
total_cost	Total request cost
duration_ms	Request duration
status_code	HTTP status
error_message	Error if any
created_at	Timestamp

Cost Calculation

Costs are calculated using model pricing data:

input_cost = prompt_tokens * (input_price_per_1m / 1_000_000)
output_cost = completion_tokens * (output_price_per_1m / 1_000_000)
total_cost = input_cost + output_cost

Pricing Sources

1. Database: provider_models.input_price_per_1m and output_price_per_1m
2. Fallback: Hardcoded pricing in app/providers/pricing.py
3. OpenRouter: Synced from OpenRouter API

Viewing Logs

Web UI

Go to https://artemis.meetrhea.com/logs to view:

• Recent requests
• Filter by model, provider, API key
• Cost summaries

API

# Get usage logs
GET /api/v1/logs?limit=100&offset=0

# Filter by date
GET /api/v1/logs?start_date=2025-01-01&end_date=2025-01-31

# Filter by model
GET /api/v1/logs?model=claude-sonnet-4-20250514

Analytics

Dashboard

The analytics dashboard shows:

• Total spend by period
• Token usage trends
• Cost by model
• Cost by provider
• Top API keys by usage

Aggregations

# Usage by model
GET /api/v1/analytics/by-model

# Usage by provider
GET /api/v1/analytics/by-provider

# Daily totals
GET /api/v1/analytics/daily

Database Schema

usage_logs

Column	Type	Description
id	uuid	Primary key
request_id	text	Unique request ID
api_key_id	uuid	FK to api_keys
provider_key_id	uuid	FK to provider_keys
provider	text	Provider slug
model	text	Model used
endpoint	text	API endpoint
prompt_tokens	int	Input tokens
completion_tokens	int	Output tokens
total_tokens	int	Total tokens
input_cost	decimal	Input cost USD
output_cost	decimal	Output cost USD
total_cost	decimal	Total cost USD
duration_ms	int	Request duration
status_code	int	HTTP status
error_message	text	Error if failed
metadata	jsonb	Custom metadata
created_at	timestamp	When logged

model_pricing

Historical pricing data:

Column	Type	Description
id	uuid	Primary key
model_id	text	Model identifier
input_price_per_1m	decimal	$/1M input tokens
output_price_per_1m	decimal	$/1M output tokens
effective_from	timestamp	When pricing started
effective_to	timestamp	When pricing ended

Custom Metadata

Add your own tracking data to requests:

response = client.chat.completions.create(
    model="claude-sonnet-4-20250514",
    messages=[...],
    extra_body={
        "metadata": {
            "session_id": "sess-123",
            "user_id": "user-456",
            "feature": "chat",
            "environment": "production"
        }
    }
)

This metadata is stored in usage_logs.metadata for filtering and analysis.

Retention

Usage logs are retained indefinitely by default. Configure retention via environment:

USAGE_LOG_RETENTION_DAYS=90  # Delete logs older than 90 days

Export

Export usage data for external analysis:

# CSV export
GET /api/v1/logs/export?format=csv&start_date=2025-01-01

# JSON export
GET /api/v1/logs/export?format=json&start_date=2025-01-01

Alerts

Set up cost alerts (coming soon):

• Daily spend threshold
• Per-key spend limits
• Anomaly detection