Skip to main content

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.

​
Custom Integration

Integrate any agent or application with Arden telemetry tracking.

​
Overview

Send telemetry events from your custom agents using either the CLI or direct API calls. Perfect for tracking usage of your own AI agents, tools, or applications.

​
Using the CLI

The simplest way to send events from any application: 
arden events send --agent "my-agent" --bid 1000

​
Basic Event

arden events send --agent "my-agent" --bid 1000 --data '{"task": "code_review"}'

​
Batch Events

Create a JSON file with multiple events: 
[
  {
    "agent": "my-agent",
    "bid": 1000,
    "data": {"task": "code_review"}
  },
  {
    "agent": "my-agent", 
    "bid": 1500,
    "data": {"task": "bug_fix"}
  }
]
Send the batch: 
arden events send --file events.json

​
Using the API

For direct integration without the CLI: 
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"}
  }'

​
Language Examples

​
Python

import requests
import time

def send_telemetry(agent_id, bid, data=None):
    event = {
        "agent": agent_id,
        "bid": bid,
        "time": int(time.time() * 1000),
        "data": data or {}
    }
    
    response = requests.post(
        "https://api.ardenstats.com/api/events",
        json=event,
        headers={"Content-Type": "application/json"}
    )
    
    return response.json()

# Usage
send_telemetry("my-python-agent", 1000, {"task": "data_analysis"})

​
JavaScript/Node.js

async function sendTelemetry(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
sendTelemetry('my-js-agent', 1000, { task: 'code_generation' });

​
Go

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
    "time"
)

type Event struct {
    Agent string                 `json:"agent"`
    Bid   int                    `json:"bid"`
    Time  int64                  `json:"time"`
    Data  map[string]interface{} `json:"data"`
}

func sendTelemetry(agentId string, bid int, data map[string]interface{}) error {
    event := Event{
        Agent: agentId,
        Bid:   bid,
        Time:  time.Now().UnixMilli(),
        Data:  data,
    }

    jsonData, _ := json.Marshal(event)
    
    resp, err := http.Post(
        "https://api.ardenstats.com/api/events",
        "application/json",
        bytes.NewBuffer(jsonData),
    )
    
    return err
}

​
Best Practices

​
Agent Naming

  • Use descriptive agent IDs: "my-company.code-reviewer"
  • Keep it consistent across sessions
  • Avoid special characters (use hyphens or dots)

​
Bid Values

  • Use micro-cents (1000 = $0.01)
  • Track actual usage costs when possible
  • Be consistent with your pricing model

​
Data Payload

  • Keep under 1KB total size
  • Include relevant context: task type, duration, etc.
  • Use flat key-value pairs for better analytics

​
Error Handling

  • Always check response status
  • Retry on network failures
  • Log errors for debugging

​
Common Integration Patterns

​
Wrapper Function

Create a utility function for your application: 
#!/bin/bash
# my-agent-wrapper.sh
MY_AGENT_ID="my-company.custom-agent"

# Run your agent
python my_agent.py "$@"

# Send telemetry after completion
arden events send --agent "$MY_AGENT_ID" --bid 1000 --data "{\"args\": \"$*\"}"

​
Process Monitoring

Track long-running processes: 
# Start event
arden events send --agent "long-runner" --bid 0 --data '{"status": "started"}'

# Your long process
./my-long-process.sh

# End event
arden events send --agent "long-runner" --bid 2000 --data '{"status": "completed"}'

​
Testing Your Integration

Use dry-run mode to test without sending real events: 
arden events send --agent "test-agent" --bid 1000 --dry-run
View the leaderboard to confirm your events are being tracked: 
arden agents leaderboard

​
Troubleshooting

Events not appearing?
  • Check agent ID format (alphanumeric with optional prefix)
  • Verify network connectivity
  • Use --dry-run --print to debug payload
Rate limiting?
  • Batch events when possible (max 100 per request)
  • Add delays between requests
  • Use exponential backoff for retries
Authentication issues?
  • Set ARDEN_API_TOKEN environment variable
  • Check token validity
  • Verify API endpoint URL