Start From Zero To Hero

How It Works

Limits & Guardrails

• Required tags: task_type, feature, route.
• Custom tags are allowed and auto-accepted if key is lowercase snake_case.
• Custom tag values can be string or string[].
• Limits: max 24 tags/event, max 16 values in one array tag, max 120 chars/value.
• Prompt/content/output-like fields are blocked by privacy guard.

OpenRouter

OpenRouter is OpenAI-compatible, so the existing createOpenAIUsageEvent() helper works out of the box. Set provider: "openrouter" in tags for attribution.

Option A: SDK Integration

import OpenAI from "openai";
import { init, trackUsage, createOpenAIUsageEvent } from "@aispendguard/sdk";

init({
  apiKey: process.env.AISPENDGUARD_API_KEY!,
  endpoint: "https://www.aispendguard.com/api/ingest",
});

const openrouter = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY!,
});

const startedAt = Date.now();

const response = await openrouter.chat.completions.create({
  model: "anthropic/claude-sonnet-4-20250514",
  messages: [{ role: "user", content: "Hello" }],
});

const event = createOpenAIUsageEvent({
  model: "anthropic/claude-sonnet-4-20250514",
  resolvedModel: response.model,
  usage: response.usage,
  latencyMs: Date.now() - startedAt,
  tags: {
    provider: "openrouter",  // Override provider to "openrouter"
    task_type: "chat",
    feature: "support",
    route: "/api/chat",
  }
});

await trackUsage(event);

Option B: LiteLLM (Python)

If you use LiteLLM with the openrouter/ model prefix, our aispendguard-litellm integration auto-detects OpenRouter and tracks all calls.

import litellm
from aispendguard_litellm import AISpendGuardLogger

litellm.callbacks.append(
    AISpendGuardLogger(api_key="asg_...",
                       default_tags={"feature": "api", "route": "/chat"})
)

response = litellm.completion(
    model="openrouter/anthropic/claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": "Hello"}],
    metadata={"aispendguard_tags": {"task_type": "chat"}},
)

Option C: Broadcast Webhook (Zero-Code)

OpenRouter can push all your usage telemetry directly to AISpendGuard via its Broadcast feature. No SDK, no code changes — just configure the webhook and you're done.

// Zero-code setup — no SDK needed!
// 1. Copy your AISpendGuard API key from /settings/workspace
// 2. In OpenRouter → Settings → Broadcast → Add Webhook:
//    URL:  https://www.aispendguard.com/api/ingest/otlp
//    Auth: Authorization: Bearer asg_your_api_key
// 3. Enable privacy mode (recommended)
// 4. Done — all OpenRouter usage flows to AISpendGuard automatically

Privacy mode strips prompt/response content. Even without it, AISpendGuard automatically strips all prompt content — only cost, tokens, and metadata are stored.

Auto-Wrap (Zero-Code Tracking)

Wrap your AI client once — every call is tracked automatically. No manual trackUsage() needed.

OpenAI

import OpenAI from "openai";
import { init, wrapOpenAI } from "@aispendguard/sdk";

init({
  apiKey: process.env.AISPENDGUARD_API_KEY!,
  defaultTags: {
    feature: "chatbot",
    route: "POST /api/chat",
    environment: "prod",
  },
});

const openai = wrapOpenAI(new OpenAI());

// Every call is now tracked automatically:
const res = await openai.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Hello" }],
  // Override tags per call (optional):
  asgTags: { task_type: "chat", customer_plan: "pro" },
});

Anthropic

import Anthropic from "@anthropic-ai/sdk";
import { init, wrapAnthropic } from "@aispendguard/sdk";

init({
  apiKey: process.env.AISPENDGUARD_API_KEY!,
  defaultTags: { feature: "support", route: "POST /api/support" },
});

const anthropic = wrapAnthropic(new Anthropic());

const msg = await anthropic.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 200,
  messages: [{ role: "user", content: "Summarize this ticket" }],
  asgTags: { task_type: "summarize" },
});

Gemini

import { GoogleGenAI } from "@google/genai";
import { init, wrapGemini } from "@aispendguard/sdk";

init({
  apiKey: process.env.AISPENDGUARD_API_KEY!,
  defaultTags: { feature: "translate", route: "POST /api/translate" },
});

const model = wrapGemini(
  ai.models,       // pass the models object
  "gemini-2.0-flash" // model name is required
);

const res = await model.generateContent({
  contents: [{ role: "user", parts: [{ text: "Translate to French" }] }],
  asgTags: { task_type: "translate" },
});

defaultTags

Tags passed to init({ defaultTags }) are merged into every auto-wrapped call. Per-call asgTags override defaults. Use this to set feature, route, and environment once instead of repeating them.

LangChain.js Integration

The SDK includes a LangChain.js callback handler that tracks every LLM call automatically. Works with any LangChain-supported provider (OpenAI, Anthropic, Google, Mistral, Cohere, etc.).

import { ChatOpenAI } from "@langchain/openai";
import { init, AISpendGuardCallbackHandler } from "@aispendguard/sdk";

init({ apiKey: process.env.AISPENDGUARD_API_KEY! });

const handler = new AISpendGuardCallbackHandler({
  defaultTags: {
    feature: "rag_pipeline",
    route: "POST /api/ask",
  },
});

const llm = new ChatOpenAI({
  model: "gpt-4o-mini",
  callbacks: [handler],
});

// Or pass to any chain/agent:
const result = await chain.invoke(
  { input: "..." },
  { callbacks: [handler] }
);

The handler auto-detects the provider, model, and token usage from LangChain's callback data. It never reads prompts or outputs — only metadata is tracked. Events are deduplicated by LangChain run ID.

For LangChain Python, install pip install aispendguard-langchain — see the aispendguard-langchain repo.

Python SDK

Native Python SDK with batched transport, provider helpers, and the same validation rules as the TypeScript SDK.

pip install aispendguard

from aispendguard import AISpendGuard, create_openai_event
import openai, time

client = AISpendGuard(api_key="asg_your_key_here")

openai_client = openai.OpenAI()
start = time.time()

response = openai_client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Classify: 'I want to cancel'"}],
)

event = create_openai_event(
    model="gpt-4o-mini",
    usage=response.usage,
    latency_ms=int((time.time() - start) * 1000),
    tags={
        "task_type": "classify",
        "feature": "ticket_triage",
        "route": "POST /api/classify",
    },
)
client.track(event)

Also supports create_anthropic_event and create_gemini_event. See the full docs at github.com/AISpendGuard/aispendguard-python.

OpenTelemetry (OTLP)

If you already instrument with OpenTelemetry, send GenAI traces directly — no SDK needed.

POST https://www.aispendguard.com/api/otel/v1/traces
Content-Type: application/json
Authorization: Bearer asg_your_api_key

# Standard OTLP/HTTP JSON format with GenAI semantic conventions:
#   gen_ai.system          → provider (openai, anthropic, google)
#   gen_ai.request.model   → model name
#   gen_ai.usage.input_tokens
#   gen_ai.usage.output_tokens

# AISpendGuard-specific attributes (optional):
#   asg.task_type, asg.feature, asg.route — override tags
#   asg.*                  → custom tags (prefix stripped)

# Headers for default tags:
#   x-asg-feature: my_feature
#   x-asg-route: POST /api/endpoint

Works with any OTLP-compatible instrumentation (OpenLLMetry, Traceloop, custom spans). Prompt content and model outputs are automatically stripped — only token counts and metadata are stored.

Budget Alerts

Set a monthly USD spending cap and get email alerts at 75% and 90% thresholds. Available on the Pro plan.

Setup via Dashboard

Go to /billing → Budget panel → set your monthly limit, enable alert thresholds, and add an alert email address.

Setup via API

# Create or update budget (requires Clerk session, OWNER/ADMIN role)
POST /api/budgets
Content-Type: application/json

{
  "monthlyLimitUsd": 500,
  "alertAt75": true,
  "alertAt90": true,
  "alertEmail": "alerts@yourcompany.com"
}

# Check current budget
GET /api/budgets

# Remove budget
DELETE /api/budgets

Alerts fire in real-time at ingest — as soon as your spend crosses a threshold, you get an email. Each threshold fires once per calendar month (deduplicated automatically). Spend is calculated from both rolled-up daily aggregates and unprocessed events for accuracy.

Ingest Response

Every POST /api/ingest call returns a JSON object with these fields:

{
  "accepted": 1,
  "duplicates": 0,
  "rejected": 0,
  "event_ids": ["cm...abc"],       // IDs of accepted events
  "warnings": [                     // Non-critical issues (event still accepted)
    "events[0].tags.task_type \"lab-benchmark\" is not recognized — coerced to \"other\"",
    "events[0].tags.my-key is not a supported tag key — stripped"
  ],
  "enforcement": {                  // Budget status (event always accepted)
    "action": "block",              // "none" | "warn" | "block"
    "reason": "workspace_budget_exceeded",
    "budget_limit": 50.00,
    "current_spend": 52.34
  },
  "dashboard_url": "https://www.aispendguard.com/events",
  "usage": {
    "eventsThisMonth": 1234,
    "monthlyLimit": 50000,
    "tier": "FREE"
  }
}

Use event_ids to verify your events were stored. Open dashboard_url to see them live.

Warnings: Tag validation issues (invalid task_type, unsupported tag keys, values too long) produce warnings — events are always accepted with best-effort coercion. Only privacy violations (forbidden keys like prompt, message) cause hard rejection.

Enforcement: When your workspace exceeds its budget, events are still tracked and accepted. The enforcement field signals the budget status so your code can decide whether to continue sending requests.

Error Reference

Error Response Shape (400)

{
  "accepted": 0,
  "duplicates": 0,
  "rejected": 2,
  "errors": [
    "events[0] contains forbidden field: prompt",
    "events[1] invalid provider: must be a non-empty string"
  ]
}

Troubleshooting

Streaming Responses

With streaming, usage data arrives in the final chunk, not during the stream. Accumulate the stream, then track usage after it completes.

OpenAI Streaming

import time
start = time.time()

# Must pass stream_options to get usage in stream
stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
    stream_options={"include_usage": True},
)

usage = None
for chunk in stream:
    if chunk.usage:
        usage = chunk.usage
    # ... process chunk.choices[0].delta

if usage:
    event = create_openai_event(
        model="gpt-4o-mini",
        usage=usage,
        latency_ms=int((time.time() - start) * 1000),
        tags={"task_type": "chat", "feature": "assistant", "route": "POST /api/chat"},
    )
    asg.track(event)

Anthropic Streaming

with anthropic_client.messages.stream(
    model="claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": "Hello"}],
    max_tokens=200,
) as stream:
    for text in stream.text_stream:
        pass  # process text chunks
    message = stream.get_final_message()

# Usage is on the final message object
event = create_anthropic_event(
    model="claude-sonnet-4-20250514",
    usage=message.usage,
    latency_ms=latency,
    tags={"task_type": "chat", "feature": "assistant", "route": "POST /api/chat"},
)
asg.track(event)

TypeScript SDK (OpenAI)

const stream = await openai.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Hello" }],
  stream: true,
  stream_options: { include_usage: true },
});

let usage;
for await (const chunk of stream) {
  if (chunk.usage) usage = chunk.usage;
  // ... process chunk
}

if (usage) {
  const event = createOpenAIUsageEvent({
    model: "gpt-4o-mini",
    usage,
    latencyMs: Date.now() - start,
    tags: { task_type: "chat", feature: "assistant", route: "POST /api/chat" },
  });
  await trackUsage(event);
}

Data Export API

Export your usage events as JSON or CSV for internal dashboards, reporting, or analysis. Requires Clerk authentication (session cookie).

# JSON (default)
GET /api/export?from=2026-03-01&to=2026-04-01&limit=5000

# CSV
GET /api/export?format=csv&from=2026-03-01&to=2026-04-01

# Parameters:
#   from    — start date (default: 1st of current month)
#   to      — end date (default: 1st of next month)
#   format  — "json" (default) or "csv"
#   limit   — max rows, 1–10000 (default: 1000)