API Reference

https://api.agenticants.ai/v1

curl https://api.agenticants.ai/v1/traces \
  -H "Authorization: Bearer ants_sk_your_api_key_here"

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1635724800

Authorization: Bearer <api_key>
Content-Type: application/json
X-Request-ID: <unique_id>

Content-Type: application/json
X-Request-ID: <unique_id>
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950

POST /v1/traces

{
  "name": "customer-support-query",
  "input": "Help with my order",
  "metadata": {
    "userId": "user_123",
    "sessionId": "session_abc"
  },
  "tags": {
    "environment": "production",
    "team": "support"
  }
}

{
  "id": "trace_abc123",
  "name": "customer-support-query",
  "startTime": "2025-10-23T14:23:45Z",
  "status": "in_progress",
  "input": "Help with my order",
  "metadata": {...},
  "tags": {...}
}

GET /v1/traces/{trace_id}

{
  "id": "trace_abc123",
  "name": "customer-support-query",
  "startTime": "2025-10-23T14:23:45Z",
  "endTime": "2025-10-23T14:23:48Z",
  "duration": 2500,
  "status": "completed",
  "input": "Help with my order",
  "output": "I can help you track your order...",
  "spans": [...],
  "tokens": 350,
  "cost": 0.0105,
  "metadata": {...}
}

GET /v1/traces?limit=100&offset=0&status=completed

{
  "data": [
    {...},
    {...}
  ],
  "pagination": {
    "total": 1234,
    "limit": 100,
    "offset": 0,
    "hasMore": true
  }
}

PATCH /v1/traces/{trace_id}

{
  "output": "I can help you track your order...",
  "status": "completed",
  "metadata": {
    "success": true
  }
}

POST /v1/traces/{trace_id}/spans

{
  "name": "llm-inference",
  "parentId": null,
  "startTime": "2025-10-23T14:23:46Z",
  "attributes": {
    "model": "gpt-4",
    "temperature": 0.7
  }
}

PATCH /v1/spans/{span_id}

{
  "endTime": "2025-10-23T14:23:48Z",
  "status": "ok",
  "output": {...}
}

POST /v1/metrics/query

{
  "metric": "latency_p95",
  "agent": "customer-support",
  "startDate": "2025-10-01T00:00:00Z",
  "endDate": "2025-10-31T23:59:59Z",
  "granularity": "1h"
}

{
  "metric": "latency_p95",
  "data": [
    {"timestamp": "2025-10-01T00:00:00Z", "value": 1850},
    {"timestamp": "2025-10-01T01:00:00Z", "value": 1920},
    ...
  ]
}

GET /v1/agents

{
  "data": [
    {
      "id": "agent_123",
      "name": "customer-support",
      "version": "1.2.3",
      "framework": "langchain",
      "model": "gpt-4",
      "status": "active",
      "createdAt": "2025-10-01T00:00:00Z"
    }
  ]
}

GET /v1/agents/{agent_id}/metrics

{
  "agent": "customer-support",
  "period": "last_24h",
  "metrics": {
    "totalRequests": 1234,
    "avgLatency": 1850,
    "errorRate": 0.5,
    "totalCost": 45.67
  }
}

POST /v1/webhooks

{
  "url": "https://your-app.com/webhooks/agenticants",
  "events": ["trace.completed", "alert.triggered"],
  "secret": "whsec_your_webhook_secret"
}

{
  "event": "trace.completed",
  "timestamp": "2025-10-23T14:23:48Z",
  "data": {
    "traceId": "trace_abc123",
    "agent": "customer-support",
    "duration": 2500,
    "status": "completed"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: name",
    "details": {
      "field": "name",
      "reason": "required"
    }
  }
}

npm install @agenticants/sdk

import { AgenticAnts } from '@agenticants/sdk'
 
const ants = new AgenticAnts({ 
  apiKey: process.env.AGENTICANTS_API_KEY 
})

pip install agenticants

from agenticants import AgenticAnts
 
ants = AgenticAnts(api_key=os.getenv('AGENTICANTS_API_KEY'))

# 1. Create trace
curl -X POST https://api.agenticants.ai/v1/traces \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-support",
    "input": "Help with order"
  }'
 
# Response: {"id": "trace_123", ...}
 
# 2. Create span
curl -X POST https://api.agenticants.ai/v1/traces/trace_123/spans \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "name": "llm-call",
    "startTime": "2025-10-23T14:23:45Z"
  }'
 
# Response: {"id": "span_456", ...}
 
# 3. End span
curl -X PATCH https://api.agenticants.ai/v1/spans/span_456 \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "endTime": "2025-10-23T14:23:47Z",
    "status": "ok"
  }'
 
# 4. Complete trace
curl -X PATCH https://api.agenticants.ai/v1/traces/trace_123 \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "output": "Your order is on the way!",
    "status": "completed"
  }'