Skip to main content

Agent Events API

Submit telemetry events via HTTP POST to track agent usage.

Endpoint

Request Body

Send either a single event object or an array of events (max 100).

Single Event

Batch Events

Event Fields

Response Formats

All Accepted (202)

Partially Accepted (207)

All Rejected (400)

Authentication Error (401)

Error Codes

Examples

cURL

Python

JavaScript

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:

Monitoring

Check the leaderboard to verify events are being tracked:
Or view via the web dashboard at ardenstats.com.