> ## 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.

# Events

# 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

```json
{
  "agent": "my-agent",
  "bid": 1000,
  "time": 1642781234567,
  "data": {"task": "code_review"}
}
```

### Batch Events

```json
[
  {
    "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)          |

## Response Formats

### All Accepted (202)

```json
{
  "status": "accepted",
  "accepted_count": 2,
  "event_ids": ["uuid-1", "uuid-2"]
}
```

### Partially Accepted (207)

```json
{
  "status": "partial",
  "accepted_count": 1,
  "rejected_count": 1,
  "rejected": [
    {"index": 1, "error": "unknown_agent"}
  ],
  "event_ids": ["uuid-1"]
}
```

### All Rejected (400)

```json
{
  "status": "rejected",
  "accepted_count": 0,
  "rejected_count": 2,
  "rejected": [
    {"index": 0, "error": "unknown_agent"},
    {"index": 1, "error": "invalid_user"}
  ]
}
```

### Authentication Error (401)

```json
{
  "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

```bash
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

```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

```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:

```bash
# 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:

```bash
arden agents leaderboard
```

Or view via the web dashboard at [ardenstats.com](https://ardenstats.com).