Features How it works Pricing FAQ See demo Try it free Docs Join Waitlist

Documentation

Everything you need to connect your agents, track ROI, and detect behaviour changes.

Quickstart

Get agent data flowing into ClawTrait in under 60 seconds.

1. Install the SDK

npm install @clawtrait/sdk

2. Initialize with your API key

import { ClawTrait } from '@clawtrait/sdk'

const ct = new ClawTrait({
  apiKey: process.env.CLAWTRAIT_API_KEY,
})

3. Send your first event

Call trackTask whenever an agent completes a task. ClawTrait uses this to calculate cost per outcome and detect drift.

await ct.trackTask({
  agentId: 'support-bot-1',
  task: 'resolve-ticket',
  outcome: 'success',       // 'success' | 'failure' | 'partial'
  cost: 0.042,              // USD spent on this task
  durationMs: 3200,         // how long the task took
  metadata: {               // optional — any extra context
    ticketId: 'TK-1234',
    model: 'gpt-4o',
  },
})

That is it. Within a few seconds, your agent will appear in the dashboard with live ROI and behaviour data.

API Reference

All endpoints are available at https://api.clawtrait.com/v1.

POST /events

Record an agent task event. This is the primary data ingestion endpoint.

curl -X POST https://api.clawtrait.com/v1/events \
  -H "Authorization: Bearer ct_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "support-bot-1",
    "task": "resolve-ticket",
    "outcome": "success",
    "cost": 0.042,
    "durationMs": 3200
  }'

Response: 201 Created with the event ID.

GET /agents/:id/stats

Retrieve performance stats for a specific agent — including cost per task, success rate, and total spend.

curl https://api.clawtrait.com/v1/agents/support-bot-1/stats \
  -H "Authorization: Bearer ct_your_api_key"

# Response
{
  "agentId": "support-bot-1",
  "period": "30d",
  "totalTasks": 1284,
  "successRate": 0.94,
  "costPerTask": 0.038,
  "totalCost": 48.79,
  "netROI": 2.4
}

GET /agents/:id/drift

Check how much an agent's behaviour has changed from its baseline. A drift score of 0 means no change; higher values indicate the agent is behaving differently from when it was first configured.

curl https://api.clawtrait.com/v1/agents/support-bot-1/drift \
  -H "Authorization: Bearer ct_your_api_key"

# Response
{
  "agentId": "support-bot-1",
  "driftScore": 0.12,
  "status": "healthy",
  "baselineDate": "2026-02-15T00:00:00Z",
  "topChanges": [
    { "dimension": "tone", "delta": 0.08 },
    { "dimension": "task_scope", "delta": 0.04 }
  ]
}

Authentication

All API requests require an API key. Include it in the Authorization header as a Bearer token.

Getting your API key

Sign in to your ClawTrait dashboard
Go to Settings → API Keys
Click Create Key and give it a descriptive name

Key format

API keys start with ct_ followed by a random string. Each key is scoped to a single workspace.

Authorization: Bearer ct_abc123def456...

Key security

Store keys in environment variables — never commit them to source control
Rotate keys from the dashboard at any time without downtime
Each agent should use its own key for granular access control

Rate limits

Starter: 100 events/minute. Pro: 1,000 events/minute. Team: 5,000 events/minute. Enterprise: custom limits.

Need help?

Email us at support@clawtrait.com or check the blog for tutorials and guides.