Events API

The Events API is the core of CLIMeter. Every tool invocation generates an event that drives metering, analytics, and billing. The SDK calls these endpoints automatically — use the raw API only if you need custom integration.

POST /v1/events

Record a single metering event. Requires a valid JWT in the Authorization header.

curl

Bash

curl -X POST https://api.climeter.ai/v1/events \
  -H "Authorization: Bearer <your-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_id": "code-search",
    "duration_ms": 142,
    "success": true,
    "metadata": {
      "query_length": 42,
      "results_count": 8
    }
  }'

example.py

Python

import os
import requests

# Get a JWT via POST /v1/auth/login first
response = requests.post(
    "https://api.climeter.ai/v1/events",
    headers={
        "Authorization": f"Bearer {jwt_token}",
        "Content-Type": "application/json",
    },
    json={
        "tool_id": "code-search",
        "duration_ms": 142,
        "success": True,
        "metadata": {"query_length": 42, "results_count": 8},
    },
)
print(response.json())

Use the SDK

The Python SDK handles authentication and event batching automatically. Use the raw API only for custom integrations or languages without an official SDK.

Schema

Field	Type	Required	Description
tool_id	string	Yes	Tool slug (e.g., "code-search")
duration_ms	integer	No	Execution time in milliseconds
success	boolean	No	Whether the call succeeded (default: true)
metadata	object	No	Custom key-value pairs (max 10 keys, 256 chars per value)
timestamp	ISO 8601 string	No	Event time (default: server time)
idempotency_key	string	No	Unique key to prevent duplicate recording

Timestamp limits

Events older than 24 hours are rejected with 422 Unprocessable Entity. Future timestamps are normalized to the current server time.

Response format

JSON

{
  "event_id": "evt_01HXZ9M3K7P8Q2R4T5V6W7X8Y",
  "tool_id": "code-search",
  "status": "recorded",
  "timestamp": "2025-03-07T12:34:56.789Z"
}

Error codes

HTTP status	Code	Description
400	invalid_request	Missing required fields or malformed JSON
401	unauthorized	Invalid or expired JWT token
404	tool_not_found	tool_id does not match any registered tool
422	event_expired	Event timestamp older than 24 hours
429	rate_limit_exceeded	Exceeded 100 req/sec per API key. See X-RateLimit-Remaining header. Retry after Retry-After seconds.
500	server_error	Transient error — retry with backoff