Documentation Index
Fetch the complete documentation index at: https://docs.ardenstats.com/llms.txt
Use this file to discover all available pages before exploring further.
Agent Events API
Submit telemetry events via HTTP POST to track agent usage.
Endpoint
POST /api/events
Content-Type: application/json
[Optional] Authorization: Bearer <token>
Request Body
Send either a single event object or an array of events (max 100).
Single Event
{
"agent": "my-agent",
"bid": 1000,
"time": 1642781234567,
"data": {"task": "code_review"}
}
Batch Events
[
{
"agent": "my-agent",
"bid": 1000,
"time": 1642781234567,
"data": {"task": "code_review"}
},
{
"agent": "my-agent",
"bid": 1500,
"time": 1642781234890,
"data": {"task": "bug_fix"}
}
]
Event Fields
| Field | Type | Required | Description |
|---|
agent | string | ✓ | Agent ID (alphanumeric, optional A-/S- prefix) |
bid | integer | ✓ | Usage cost in micro-cents (1000 = $0.01) |
time | integer | ✓ | Timestamp in epoch milliseconds UTC |
data | object | ✓ | Metadata payload (max 1KB, flat key-value pairs) |
user | string | | User ULID (26 chars, auto-filled from Bearer token) |
mult | integer | | Multiplier for future pricing (default: 0) |
All Accepted (202)
{
"status": "accepted",
"accepted_count": 2,
"event_ids": ["uuid-1", "uuid-2"]
}
Partially Accepted (207)
{
"status": "partial",
"accepted_count": 1,
"rejected_count": 1,
"rejected": [
{"index": 1, "error": "unknown_agent"}
],
"event_ids": ["uuid-1"]
}
All Rejected (400)
{
"status": "rejected",
"accepted_count": 0,
"rejected_count": 2,
"rejected": [
{"index": 0, "error": "unknown_agent"},
{"index": 1, "error": "invalid_user"}
]
}
Authentication Error (401)
{
"error": "invalid_token"
}
Error Codes
| Code | Description |
|---|
unknown_agent | Agent ID not registered in system |
invalid_user | User ULID invalid or missing |
missing_required_field | Required field absent from request |
bad_data_size | Data payload exceeds 1KB limit |
validation_error | Schema validation failed |
Examples
cURL
curl -X POST https://api.ardenstats.com/api/events \
-H "Content-Type: application/json" \
-d '{
"agent": "my-agent",
"bid": 1000,
"time": 1642781234567,
"data": {"task": "code_review"}
}'
Python
import requests
import time
def send_event(agent_id, bid, data):
event = {
"agent": agent_id,
"bid": bid,
"time": int(time.time() * 1000),
"data": data
}
response = requests.post(
"https://api.ardenstats.com/api/events",
json=event
)
return response.json()
# Usage
result = send_event("my-agent", 1000, {"task": "code_review"})
print(result)
JavaScript
async function sendEvent(agentId, bid, data) {
const event = {
agent: agentId,
bid: bid,
time: Date.now(),
data: data
};
const response = await fetch('https://api.ardenstats.com/api/events', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(event)
});
return response.json();
}
// Usage
sendEvent('my-agent', 1000, { task: 'code_review' });
Rate Limits
- Batch size: Maximum 100 events per request
- Payload size: Maximum 1KB per event data field
- Frequency: No explicit rate limits, but use batching for high volumes
Authentication
Bearer tokens are optional. If provided:
- Token must be valid and active
- User field auto-filled from token if missing
- Invalid tokens return 401 error
Without authentication, events are logged anonymously.
Best Practices
- Batch events when sending multiple events
- Include timestamps - use current epoch milliseconds
- Keep data small - under 1KB per event
- Use descriptive agent IDs - helps with analytics
- Handle errors gracefully - check response status
- Retry on network failures - implement exponential backoff
Testing
Use the CLI for quick testing:
# Test single event
arden events send --agent "test-agent" --bid 1000 --dry-run
# Test batch events
arden events send --file events.json --dry-run
Monitoring
Check the leaderboard to verify events are being tracked:
Or view via the web dashboard at ardenstats.com.