Documentation

First event in under five minutes

Ambral turns AI activity into economic events. You report what happened — provider, model, usage. Ambral resolves the pricing, calculates the cost, and explains it.

Quickstart

1. Create an account and an API key in the dashboard.
2. Send one event after an LLM call, tool use, or compute action.
3. Watch the cost appear in your dashboard — priced and explained.

curl -X POST https://ambral.dev/api/ingest \
  -H "Content-Type: application/json" \
  -H "x-api-key: ab_..." \
  -d '{
    "idempotency_key": "run-42-call-07",
    "provider": "anthropic",
    "model": "claude-sonnet-4.5",
    "agentId": "research-agent",
    "inputTokens": 12450,
    "outputTokens": 2840
  }'

Canonical event

You never send a cost. Ambral determines the economic value server-side from versioned pricing.

{
  "idempotency_key": "run-42-call-07",
  "provider": "anthropic",
  "model": "claude-sonnet-4.5",
  "agentId": "research-agent",
  "workflowId": "weekly-research",
  "taskId": "task_456",
  "environment": "production",
  "inputTokens": 12450,
  "outputTokens": 2840,
  "cachedInputTokens": 0,
  "reasoningTokens": 0,
  "latencyMs": 1820,
  "status": "success",
  "source": "sdk"
}

Field	Type	Notes
idempotency_key	string	Required. Unique per event; replay-safe.
provider	string	Required. e.g. openai, anthropic, e2b.
model	string	Exact model id, e.g. claude-sonnet-4.5.
agentId	string	The agent that produced the event.
workflowId / taskId	string	For workflow & task attribution.
environment	string	e.g. production, staging.
inputTokens / outputTokens	number	Token counts. Ambral prices them.
cachedInputTokens / reasoningTokens	number	Optional token breakdowns.
latencyMs	number	Optional latency in milliseconds.
status	string	Optional. e.g. success, error.
source	string	Optional. e.g. sdk, api, manual.

Unknown models are never dropped

If a model has no known pricing yet, the event is accepted and markedunpriced— never silently zero. When pricing is discovered, costs are backfilled automatically. Unknown cost is not zero cost.

API

POST /api/ingest — send one or a batch of events (up to 1,000).
GET/POST /api/budgets — daily, weekly, or monthly spending limits.
POST /api/api-keys — create, rotate, and revoke keys.
GET /api/dashboard — spend, trends, and top models.
GET /api/costs — the cost explorer.

SDKs

PHPcomposer require ambral/sdk

Pythonpip install ambral-sdk

JavaScript / TypeScriptnpm install @ambral/sdk

Self-hosting

The MIT-licensed core runs on any Next.js + MySQL host. Self-host it forever, or use the managed Cloud for pricing intelligence, retention, and collaboration.

git clone https://github.com/ambral-app/getambral.git
cd ambral
npm install && npm run setup
npm run dev

See the GitHub repo for the full reference.

Get started free