Integrate

Connect your agents to AgentBurn in minutes

1. Register an Agent

Create an agent to group cost events under a named entity.

curl -X POST http://localhost:3000/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Agent",
    "description": "Handles customer onboarding workflows",
    "projectId": "onboarding",
    "tags": ["support", "onboarding"]
  }'

Returns the agent object with its id — use this in cost events.

2. Ingest Cost Events

Send a single event or a batch (up to 1,000). Authenticate with your API key.

curl -X POST http://localhost:3000/api/ingest \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "agentId": "AGENT_ID_HERE",
    "provider": "anthropic",
    "model": "claude-3.5-sonnet",
    "operation": "llm_call",
    "inputTokens": 12500,
    "outputTokens": 3200,
    "costUsd": 0.0855,
    "taskId": "ticket-CTMS-5109",
    "workflowId": "sprint-42"
  }'

Batch mode: Send an array of events in a single request for high-throughput ingestion.

3. Python SDK Example

Drop-in wrapper for your agent code.

import requests

class AgentBurn:
    def __init__(self, base_url, api_key, agent_id):
        self.base_url = base_url
        self.api_key = api_key
        self.agent_id = agent_id

    def track(self, provider, cost_usd, **kwargs):
        requests.post(
            f"{self.base_url}/api/ingest",
            headers={"x-api-key": self.api_key},
            json={
                "agentId": self.agent_id,
                "provider": provider,
                "costUsd": cost_usd,
                **kwargs
            }
        )

# Usage
finops = AgentBurn("https://your-domain.com", "your-key", "agent-id")
finops.track("anthropic", 0.085, model="claude-3.5-sonnet",
             operation="llm_call", inputTokens=12500, outputTokens=3200)

4. Event Schema

Field	Type	Required	Description
agentId	string	Required	ID of the registered agent
provider	string	Required	Service provider (openai, anthropic, e2b, etc.)
operation	string	Required	llm_call \| tool_call \| compute \| api_call
costUsd	number	Required	Cost in USD
model	string	Optional	Model name (gpt-4o, claude-3.5-sonnet, etc.)
inputTokens	integer	Optional	Input/prompt tokens
outputTokens	integer	Optional	Output/completion tokens
taskId	string	Optional	Group events by task
workflowId	string	Optional	Group events by workflow
metadata	object	Optional	Arbitrary JSON metadata
timestamp	ISO 8601	Optional	Event time (defaults to now)