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

Getting Started

Integrations

API Reference

Custom

Custom Integration

Overview

Using the CLI

Basic Event

Batch Events

Using the API

Language Examples

Python

JavaScript/Node.js

Go

Best Practices

Agent Naming

Bid Values

Data Payload

Error Handling

Common Integration Patterns

Wrapper Function

Process Monitoring

Testing Your Integration

Troubleshooting

​Custom Integration

​Overview

​Using the CLI

​Basic Event

​Batch Events

​Using the API

​Language Examples

​Python

​JavaScript/Node.js

​Go

​Best Practices

​Agent Naming

​Bid Values

​Data Payload

​Error Handling

​Common Integration Patterns

​Wrapper Function

​Process Monitoring

​Testing Your Integration

​Troubleshooting

Custom Integration

Overview

Using the CLI

Basic Event

Batch Events

Using the API

Language Examples

Python

JavaScript/Node.js

Go

Best Practices

Agent Naming

Bid Values

Data Payload

Error Handling

Common Integration Patterns

Wrapper Function

Process Monitoring

Testing Your Integration

Troubleshooting