Skip to main content

​
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

FieldTypeRequiredDescription
agentstring✓Agent ID (alphanumeric, optional A-/S- prefix)
bidinteger✓Usage cost in micro-cents (1000 = $0.01)
timeinteger✓Timestamp in epoch milliseconds UTC
dataobject✓Metadata payload (max 1KB, flat key-value pairs)
userstringUser ULID (26 chars, auto-filled from Bearer token)
multintegerMultiplier for future pricing (default: 0)

​
Response Formats

​
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

CodeDescription
unknown_agentAgent ID not registered in system
invalid_userUser ULID invalid or missing
missing_required_fieldRequired field absent from request
bad_data_sizeData payload exceeds 1KB limit
validation_errorSchema 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

  1. Batch events when sending multiple events
  2. Include timestamps - use current epoch milliseconds
  3. Keep data small - under 1KB per event
  4. Use descriptive agent IDs - helps with analytics
  5. Handle errors gracefully - check response status
  6. 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: 
arden agents leaderboard
Or view via the web dashboard at ardenstats.com.