OwlMetric provides several API endpoints for tracking AI usage, managing projects, and retrieving analytics. This reference covers all available endpoints with detailed examples.
https://owlmetric.com/apiAll API requests require authentication via API tokens:
x-owlmetric headerRoute OpenAI requests through OwlMetric for automatic tracking.
Base URL: https://owlmetric.com/api/proxy
POST /proxy/v1/chat/completions
Headers:
Content-Type: application/json
Authorization: Bearer YOUR_OPENAI_API_KEY
x-owlmetric: YOUR_OWLMETRIC_PROJECT_TOKEN
Request Body:
{
"model": "gpt-4",
"messages": [
{
"role": "user",
"content": "Hello, world!"
}
],
"max_tokens": 100,
"temperature": 0.7,
"stream": false
}
Response:
{
"id": "chatcmpl-123",
"object": "chat.completion",
"created": 1677652288,
"model": "gpt-4",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! How can I help you today?"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 9,
"completion_tokens": 12,
"total_tokens": 21
}
}
POST /proxy/v1/chat/completions
Request Body:
{
"model": "gpt-4",
"messages": [
{
"role": "user",
"content": "Count from 1 to 5"
}
],
"stream": true
}
Response: Server-Sent Events
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4","choices":[{"index":0,"delta":{"content":"1"},"finish_reason":null}]}
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4","choices":[{"index":0,"delta":{"content":" 2"},"finish_reason":null}]}
data: [DONE]
Base URL: https://owlmetric.com/api/proxy/anthropic
POST /proxy/anthropic/v1/messages
Headers:
Content-Type: application/json
x-api-key: YOUR_ANTHROPIC_API_KEY
x-owlmetric: YOUR_OWLMETRIC_PROJECT_TOKEN
anthropic-version: 2023-06-01
Request Body:
{
"model": "claude-3-sonnet-20240229",
"max_tokens": 1000,
"messages": [
{
"role": "user",
"content": "Hello, Claude!"
}
]
}
Response:
{
"id": "msg_123",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Hello! I'm Claude, an AI assistant. How can I help you today?"
}
],
"model": "claude-3-sonnet-20240229",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 10,
"output_tokens": 25
}
}
Base URL: https://owlmetric.com/api/proxy/gemini
POST /proxy/gemini/v1/models/{model}:generateContent
Headers:
Content-Type: application/json
x-goog-api-key: YOUR_GOOGLE_API_KEY
x-owlmetric: YOUR_OWLMETRIC_PROJECT_TOKEN
Request Body:
{
"contents": [
{
"parts": [
{
"text": "Explain quantum computing"
}
]
}
]
}
Submit usage metrics directly to OwlMetric without using the proxy.
POST /api/metrics
Headers:
Content-Type: application/json
Authorization: Bearer YOUR_TRACKING_TOKEN
Request Body:
{
"prompt_tokens": 150,
"completion_tokens": 75,
"total_tokens": 225,
"model": "gpt-4-turbo",
"timestamp": "2024-01-15T10:30:00Z",
"system": "openai",
"response_time_ms": 1200,
"status": "completed",
"prompt_tokens_details": {
"cached_tokens": 12,
"audio_tokens": 0
},
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0
}
}
Response:
{
"success": true,
"id": "usage_123456",
"cost": 0.045,
"timestamp": "2024-01-15T10:30:00Z"
}
Submit OpenTelemetry traces for AI SDK telemetry.
POST /api/trace/log
Headers:
Content-Type: application/json
Request Body:
OpenTelemetry trace format with embedded authentication:
{
"resourceSpans": [
{
"spans": [
{
"name": "ai.generate",
"attributes": {
"ai.telemetry.metadata.xOwlToken": "YOUR_TRACKING_TOKEN",
"ai.model.name": "gpt-4",
"ai.usage.prompt_tokens": 100,
"ai.usage.completion_tokens": 50
}
}
]
}
]
}
GET /api/v1/projects
Headers:
Authorization: Bearer YOUR_API_KEY
Response:
{
"projects": [
{
"id": "proj_123",
"name": "My AI App",
"description": "Customer support chatbot",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"organization_id": "org_456"
}
],
"total": 1,
"page": 1,
"per_page": 50
}
POST /api/v1/projects
Headers:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Request Body:
{
"name": "New AI Project",
"description": "Description of the project",
"organization_id": "org_456"
}
Response:
{
"id": "proj_789",
"name": "New AI Project",
"description": "Description of the project",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"organization_id": "org_456",
"api_keys": {
"proxy_key": "pk_new_project_key",
"tracking_tokens": {
"openai": "pt_openai_token",
"anthropic": "pt_anthropic_token"
}
}
}
GET /api/v1/projects/{project_id}/usage
Headers:
Authorization: Bearer YOUR_API_KEY
Query Parameters:
start_date (ISO 8601 date): Filter from dateend_date (ISO 8601 date): Filter to dateprovider (string): Filter by AI provider (openai, anthropic, google)model (string): Filter by specific modelgroup_by (string): Group results by hour, day, week, monthpage (integer): Page number (default: 1)per_page (integer): Items per page (default: 50, max: 1000)Example:
GET /api/v1/projects/proj_123/usage?start_date=2024-01-01&end_date=2024-01-31&group_by=day
Response:
{
"usage": [
{
"date": "2024-01-15",
"provider": "openai",
"model": "gpt-4",
"requests": 150,
"prompt_tokens": 45000,
"completion_tokens": 22500,
"total_tokens": 67500,
"cost": 2.25,
"avg_response_time_ms": 1200
}
],
"totals": {
"requests": 150,
"prompt_tokens": 45000,
"completion_tokens": 22500,
"total_tokens": 67500,
"cost": 2.25
},
"page": 1,
"per_page": 50,
"total": 1
}
POST /api/v1/projects/{project_id}/usage/export
Headers:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Request Body:
{
"format": "csv",
"start_date": "2024-01-01",
"end_date": "2024-01-31",
"filters": {
"provider": "openai",
"model": "gpt-4"
}
}
Response:
{
"export_id": "exp_123",
"status": "pending",
"estimated_completion": "2024-01-15T10:35:00Z"
}
GET /api/v1/exports/{export_id}
Response:
{
"id": "exp_123",
"status": "completed",
"download_url": "https://owlmetric.com/api/v1/exports/exp_123/download",
"expires_at": "2024-01-16T10:30:00Z",
"file_size": 1024000,
"record_count": 5000
}
GET /api/v1/projects/{project_id}/budgets
Response:
{
"budgets": [
{
"id": "bud_123",
"name": "Monthly Limit",
"amount": 100.00,
"period": "monthly",
"current_usage": 75.50,
"percentage_used": 75.5,
"alerts": [
{
"threshold": 80,
"triggered": false
},
{
"threshold": 95,
"triggered": false
}
],
"created_at": "2024-01-01T00:00:00Z"
}
]
}
POST /api/v1/projects/{project_id}/budgets
Request Body:
{
"name": "Development Budget",
"amount": 50.00,
"period": "monthly",
"alert_thresholds": [50, 80, 95],
"providers": ["openai", "anthropic"],
"models": ["gpt-4", "claude-3-sonnet-20240229"]
}
GET /api/v1/organizations
Response:
{
"organizations": [
{
"id": "org_123",
"name": "My Company",
"plan": "professional",
"members": 5,
"projects": 12,
"created_at": "2024-01-01T00:00:00Z"
}
]
}
All endpoints use consistent error response format:
{
"error": {
"code": "invalid_request",
"message": "The request is invalid",
"details": {
"field": "messages",
"issue": "required field missing"
}
},
"request_id": "req_123456789"
}
| Code | HTTP Status | Description |
|---|---|---|
invalid_request |
400 | Request format or parameters are invalid |
unauthorized |
401 | Invalid or missing authentication |
forbidden |
403 | Insufficient permissions |
not_found |
404 | Resource not found |
rate_limited |
429 | Too many requests |
server_error |
500 | Internal server error |
service_unavailable |
503 | Service temporarily unavailable |
| Endpoint Type | Requests per Minute | Requests per Hour |
|---|---|---|
| Proxy endpoints | 1000 | 50000 |
| Direct tracking | 5000 | 200000 |
| Management API | 100 | 2000 |
Rate limit headers are included in all responses:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
@owlmetric/trackerowlmetric-python (coming soon)owlmetric-go (coming soon)