Metrx is now live — Start tracking your AI costs for free →
Integration Guide

This guide walks you through integrating Metrx into your application, from initial setup to advanced features.

Table of Contents

  1. 5-Minute Quickstart
  2. SDK Installation & Usage
  3. Gateway Proxy Setup
  4. Custom Headers for Tracking
  5. Streaming Responses
  6. OpenTelemetry Integration
  7. Webhook Setup
  8. Migration Guide
  9. IDE-Assisted Setup
  10. Budget Configuration
  11. Alert Setup
  12. Realtime Dashboard

5-Minute Quickstart

1. Get Your API Key

Sign up at app.metrxbot.com:

  • Create an organization
  • Go to Settings → API Keys
  • Click Generate Key
  • Copy your key (starts with al_)

2. Make Your First Request

Replace your direct LLM API calls with Metrx’s Gateway. Here’s a simple example:

Before (Direct OpenAI):

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer sk_openai_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

After (Metrx Gateway):

curl https://gateway.metrxbot.com/v1/chat/completions \
  -H "Authorization: Bearer al_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "X-Provider-Key: sk_openai_live_abc123" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

What changed:

  • URL: api.openai.com → gateway.metrxbot.com
  • Auth: Your OpenAI key → X-Provider-Key header
  • New auth header: Metrx API key in Authorization

3. View Your Dashboard

Log into app.metrxbot.com and see:

  • Real-time cost tracking
  • Call counts by model
  • Performance metrics
  • Usage vs. plan limit

That’s it! Your costs are now tracked automatically.

SDK Installation & Usage

For a more integrated experience, install the official Metrx SDK:

Install

npm install @metrxbot/sdk

Initialize

import { Metrx } from '@metrxbot/sdk';
 
const metrx = new Metrx({
  apiKey: process.env.METRX_API_KEY,
  gatewayUrl: 'https://gateway.metrxbot.com', // optional, defaults to production
});

Make Requests

// Get supported models
const models = await metrx.models.list();
console.log(models);
 
// OpenAI-compatible chat completions
const response = await metrx.chat.completions.create({
  model: 'gpt-4',
  messages: [
    { role: 'user', content: 'What is 2+2?' },
  ],
  agentId: 'my-agent', // optional custom identifier
  sessionId: 'session-123', // optional session grouping
  customerId: 'cust-456', // optional customer tracking
});
 
console.log(response.choices[0].message.content);

Track Outcomes

// After a successful business outcome
await metrx.outcomes.create({
  sessionId: 'session-123',
  name: 'Successfully answered customer question',
  metadata: {
    satisfactionScore: 5,
    resolvedFirstContact: true,
  },
});

Full SDK Example

import { Metrx } from '@metrxbot/sdk';
 
async function main() {
  const metrx = new Metrx({
    apiKey: process.env.METRX_API_KEY,
  });
 
  // Make a request
  const completion = await metrx.chat.completions.create({
    model: 'gpt-4',
    messages: [
      { role: 'user', content: 'Analyze this customer feedback' },
    ],
    agentId: 'sentiment-analyzer',
    sessionId: 'feedback-2024-02-20-001',
  });
 
  const analysis = completion.choices[0].message.content;
 
  // Report outcome
  if (analysis.includes('positive')) {
    await metrx.outcomes.create({
      sessionId: 'feedback-2024-02-20-001',
      name: 'Positive feedback detected',
    });
  }
}
 
main().catch(console.error);

Gateway Proxy Setup

The Gateway is a drop-in replacement for OpenAI, Anthropic, and other LLM APIs. You can gradually migrate without rewriting code.

Node.js with OpenAI SDK

Use the OpenAI SDK pointing to the Metrx Gateway:

import OpenAI from 'openai';
 
const client = new OpenAI({
  apiKey: process.env.METRX_API_KEY, // Metrx key
  baseURL: 'https://gateway.metrxbot.com/v1',
  defaultHeaders: {
    'X-Provider-Key': process.env.OPENAI_API_KEY, // Your OpenAI key
    'X-Agent-ID': 'my-agent',
  },
});
 
const response = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }],
});
 
console.log(response.choices[0].message.content);

Python with OpenAI SDK

import os
from openai import OpenAI
 
client = OpenAI(
    api_key=os.environ.get('METRX_API_KEY'),
    base_url='https://gateway.metrxbot.com/v1',
    default_headers={
        'X-Provider-Key': os.environ.get('OPENAI_API_KEY'),
        'X-Agent-ID': 'my-agent',
    }
)
 
response = client.chat.completions.create(
    model='gpt-4',
    messages=[{'role': 'user', 'content': 'Hello!'}],
)
 
print(response.choices[0].message.content)

Direct HTTP

curl -X POST https://gateway.metrxbot.com/v1/chat/completions \
  -H "Authorization: Bearer al_your_api_key" \
  -H "Content-Type: application/json" \
  -H "X-Provider-Key: sk_openai_your_key" \
  -H "X-Agent-ID: my-agent" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Anthropic API

The Gateway also supports Anthropic’s claude-* models:

import Anthropic from '@anthropic-ai/sdk';
 
const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
  // Note: Anthropic SDK doesn't support custom baseURL yet
  // Use direct HTTP or Metrx SDK instead
});
 
// Or with Metrx SDK:
const metrx = new Metrx({
  apiKey: process.env.METRX_API_KEY,
});
 
const response = await metrx.messages.create({
  model: 'claude-3-opus-20240229',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello Claude!' }],
});

Custom Headers for Tracking

Use these headers to track costs and outcomes across your organization:

X-Agent-ID

Custom identifier for your AI agent or system:

curl -H "X-Agent-ID: customer-support-bot-v2"

Benefits:

  • Track costs by agent
  • Compare performance across versions
  • Identify which agents are most cost-effective

X-Session-ID

Group related LLM calls together (conversation, workflow, user session):

curl -H "X-Session-ID: user-456-session-2024-02-20-001"

Benefits:

  • Track multi-turn conversations as a single session
  • Aggregate cost and latency per session
  • Correlate with business outcomes
  • Identify long-running sessions for optimization

X-Customer-ID

Track costs by end-customer (for multi-tenant SaaS apps):

curl -H "X-Customer-ID: cust_enterprise_xyz"

Benefits:

  • Chargeback costs to specific customers
  • Per-customer usage dashboards
  • Identify high-cost customers

Example: Complete Tracking Setup

import { Metrx } from '@metrxbot/sdk';
 
const metrx = new Metrx({
  apiKey: process.env.METRX_API_KEY,
});
 
async function handleCustomerQuery(customerId: string, query: string) {
  const sessionId = `${customerId}-session-${Date.now()}`;
 
  const response = await metrx.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: query }],
    agentId: 'customer-support-bot',
    sessionId: sessionId,
    customerId: customerId,
  });
 
  // After generating response, report business outcome
  if (response.choices[0].message.content.length > 100) {
    await metrx.outcomes.create({
      sessionId: sessionId,
      name: 'Detailed support response generated',
      metadata: {
        responseLength: response.choices[0].message.content.length,
        model: 'gpt-4',
      },
    });
  }
 
  return response.choices[0].message.content;
}

Streaming Responses

The Gateway supports streaming responses for real-time output. Stream transparently with full cost tracking:

SDK Example

const metrx = new Metrx({
  apiKey: process.env.METRX_API_KEY,
});
 
const stream = await metrx.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Write a long story...' }],
  stream: true,
  agentId: 'story-generator',
  sessionId: 'session-123',
});
 
// Stream chunks to client
for await (const chunk of stream) {
  if (chunk.choices[0].delta.content) {
    process.stdout.write(chunk.choices[0].delta.content);
  }
}

OpenAI SDK Example

import OpenAI from 'openai';
 
const client = new OpenAI({
  apiKey: process.env.METRX_API_KEY,
  baseURL: 'https://gateway.metrxbot.com/v1',
  defaultHeaders: {
    'X-Provider-Key': process.env.OPENAI_API_KEY,
  },
});
 
const stream = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Write code for a binary search' }],
  stream: true,
});
 
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0].delta.content || '');
}

Cost Calculation with Streaming

Even with streaming responses, costs are accurately calculated:

  1. Gateway captures all SSE (Server-Sent Event) chunks
  2. Final chunk includes token usage from the provider
  3. Cost is calculated and logged with the event
  4. Webhook notifies your app when complete

OpenTelemetry Integration

Export Gateway metrics and traces to your observability stack (Datadog, New Relic, etc.):

Initialize OpenTelemetry

import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { JaegerExporter } from '@opentelemetry/exporter-jaeger-basic';
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-node';
 
const jaegerExporter = new JaegerExporter({
  endpoint: 'http://localhost:14268/api/traces', // Your Jaeger endpoint
});
 
const sdk = new NodeSDK({
  traceExporter: jaegerExporter,
  instrumentations: [getNodeAutoInstrumentations()],
});
 
sdk.start();
console.log('Tracing initialized');

Track Gateway Calls

The Metrx SDK automatically exports spans with these attributes:

service.name: agent-ledger
span.name: chat.completions
attributes:
  model: gpt-4
  agent_id: my-agent
  session_id: session-123
  input_tokens: 150
  output_tokens: 75
  cost_microcents: 2250
  latency_ms: 1234
  status: success

View in Your Observability Dashboard

Once exported, view latency, error rates, and costs alongside your own app metrics:

Query: Latency by model
gpt-4:          1250ms avg
gpt-3.5-turbo:  450ms avg

Query: Cost by agent
customer-support: $123.45
content-generator: $89.23

Webhook Setup

Webhooks deliver real-time events to your backend as they happen.

1. Create a Webhook Endpoint

On your backend, create an endpoint to receive events:

// pages/api/webhooks/metrx.ts
import { NextApiRequest, NextApiResponse } from 'next';
import crypto from 'crypto';
 
export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  // Verify webhook signature
  const signature = req.headers['x-webhook-signature'] as string;
  const secret = process.env.METRX_WEBHOOK_SECRET;
 
  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(req.body))
    .digest('hex');
 
  if (hash !== signature) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
 
  // Handle event
  const { event_type, data } = req.body;
 
  switch (event_type) {
    case 'event.created':
      await handleEventCreated(data);
      break;
    case 'outcome.confirmed':
      await handleOutcomeConfirmed(data);
      break;
  }
 
  res.status(200).json({ success: true });
}
 
async function handleEventCreated(data: any) {
  console.log(`LLM call: ${data.model} cost $${data.cost_microcents / 100000}`);
 
  // Log to your analytics system
  // Trigger alerts if cost exceeds threshold
  // Update customer billing
}
 
async function handleOutcomeConfirmed(data: any) {
  console.log(`Outcome confirmed: ${data.name}`);
 
  // Update your database
  // Calculate ROI
  // Generate reports
}

2. Register the Webhook

Log into app.metrxbot.com:

  • Go to Settings → Webhooks
  • Click Add Webhook
  • Enter your endpoint: https://your-app.com/api/webhooks/metrx
  • Select events: event.created, outcome.confirmed, etc.
  • Click Create

3. Verify Webhook Signature

Every webhook includes a signature for verification:

import crypto from 'crypto';
 
function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
 
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

4. Handle Events

event.created:

{
  "event_type": "event.created",
  "data": {
    "id": "event_123",
    "model": "gpt-4",
    "input_tokens": 150,
    "output_tokens": 75,
    "cost_microcents": 2250,
    "latency_ms": 1234,
    "status": "success",
    "agent_key": "my-agent",
    "session_id": "session-123",
    "customer_id": "cust-456"
  }
}

outcome.confirmed:

{
  "event_type": "outcome.confirmed",
  "data": {
    "id": "outcome_xyz",
    "name": "Successfully handled inquiry",
    "session_id": "session-123",
    "related_events": 3
  }
}

Migration Guide: From Direct API Calls

Step 1: Create Metrx Account

Sign up at app.metrxbot.com and get your API key.

Step 2: Update Environment Variables

# Before
OPENAI_API_KEY=sk_openai_live_abc123
 
# After
OPENAI_API_KEY=sk_openai_live_abc123  # Keep for X-Provider-Key
METRX_API_KEY=al_your_api_key   # New
METRX_GATEWAY_URL=https://gateway.metrxbot.com

Step 3: Refactor LLM Client (Node.js)

Before:

import OpenAI from 'openai';
 
const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});
 
const response = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello' }],
});

After:

import OpenAI from 'openai';
 
const client = new OpenAI({
  apiKey: process.env.METRX_API_KEY,
  baseURL: process.env.METRX_GATEWAY_URL + '/v1',
  defaultHeaders: {
    'X-Provider-Key': process.env.OPENAI_API_KEY,
    'X-Agent-ID': 'my-agent',
  },
});
 
const response = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello' }],
});

Step 4: Test Staging

  1. Deploy to staging with new environment variables
  2. Run your integration tests
  3. Verify costs are tracked in the Metrx dashboard
  4. Check that responses match expected behavior

Step 5: Gradually Roll Out

Option A: Gradual Environment Variable Switch (Recommended)

# Week 1: Run 10% of traffic through Metrx
METRX_TRAFFIC_PERCENTAGE=10
 
# Week 2: 50%
METRX_TRAFFIC_PERCENTAGE=50
 
# Week 3: 100%
METRX_TRAFFIC_PERCENTAGE=100

Option B: Client Selection

// Route some LLM calls through Metrx, others direct
function getLLMClient() {
  if (shouldUseMetrx()) {
    return new OpenAI({
      apiKey: process.env.METRX_API_KEY,
      baseURL: process.env.METRX_GATEWAY_URL + '/v1',
      defaultHeaders: {
        'X-Provider-Key': process.env.OPENAI_API_KEY,
      },
    });
  } else {
    return new OpenAI({
      apiKey: process.env.OPENAI_API_KEY,
    });
  }
}

Step 6: Monitor & Optimize

Once migrated, use the Metrx dashboard to:

  • Identify expensive calls
  • Compare model performance
  • Set up cost alerts
  • Optimize prompts for cheaper models

Troubleshooting

”Invalid API key”

Ensure your Metrx API key is in the Authorization header, not X-Provider-Key:

# Wrong
curl -H "X-Provider-Key: al_xxx"
 
# Correct
curl -H "Authorization: Bearer al_xxx"

“Missing X-Provider-Key header”

Your LLM provider key (OpenAI, Anthropic, etc.) must be in the X-Provider-Key header:

# Correct
curl -H "X-Provider-Key: sk_openai_xxx"

“Unsupported model”

Check supported models:

curl https://gateway.metrxbot.com/v1/models \
  -H "Authorization: Bearer al_xxx"

Costs not appearing

  1. Check that requests complete with status 200
  2. Verify session_id is set (if grouping calls)
  3. Check the Events tab in the dashboard
  4. View logs with METRX_DEBUG=true

IDE-Assisted Setup

Metrx offers an intelligent setup feature that generates context-aware installation prompts for popular AI IDEs.

How It Works

  1. Go to app.metrxbot.com and start the onboarding flow
  2. At Step 1, click “Set up with AI IDE”
  3. Select your IDE from the list:
    • Claude Code
    • Cursor
    • Codex
    • Windsurf
    • Gemini
    • Grok
  4. Choose your preferred programming language (Python, TypeScript, etc.)
  5. Copy the generated prompt
  6. Paste it into your IDE’s AI assistant

What the Generated Prompt Includes

The AI IDE will guide you through:

  • Installing the Metrx SDK for your language
  • Configuring the agent with your API key
  • Setting the gateway URL (https://gateway.metrxbot.com)
  • Making your first test request
  • Verifying the connection works

This approach lets you leverage your IDE’s AI assistant to understand each step and ask questions as you go.

Budget Configuration

Control spending by setting budget limits and enforcement policies.

Setting Up Budgets

  1. Log in to app.metrxbot.com
  2. Go to Settings → Budgets
  3. Click Create Budget
  4. Configure:
    • Period: Daily or Monthly
    • Limit: Maximum spending for the period (in dollars)
    • Warning Threshold: Optional percentage (e.g., alert at 80% of limit)
    • Enforcement Mode: See options below
    • Apply To: Specific agent or entire organization

Enforcement Modes

ModeBehavior
alert_onlySend alerts when limit is reached; requests still go through
soft_blockAllow requests but flag them; log warnings to console
hard_blockReject requests with 429 error when limit is exceeded

Tier Limits

Budget functionality varies by plan:

TierBudgets Allowed
Starter1 budget
Lite5 budgets
Pro10 budgets
EnterpriseUnlimited

How Budget Enforcement Works

  1. When you make a request through the gateway, the gateway checks the current spending
  2. If enforcement is alert_only or soft_block, the request proceeds
  3. If enforcement is hard_block and the limit is reached, gateway returns: 
    {
  "error": "Budget limit exceeded",
  "limit": 10000,
  "current_spending": 10050,
  "retry_at": "2024-03-01T00:00:00Z"
}
  4. Budget resets at the start of the next period (daily/monthly)

Alert Setup

Configure notifications for cost spikes, errors, and other important events.

Configuring Alerts

  1. Log in to app.metrxbot.com
  2. Go to Settings → Alerts
  3. Select notification channels (see Notification Channels below)
  4. Choose which alert types to enable
  5. Set thresholds for each alert type

Alert Types

Alert TypeTriggerExample
cost_spikeDaily spending exceeds thresholdSpending jumped 50% above average
error_rateError percentage exceeds threshold>5% of requests failed
usage_spikeAPI call volume exceeds threshold2x normal call volume
idle_agentAgent inactive for configured periodNo calls in 7 days
budget_warningSpending approaching budget limit80% of monthly budget used

Notification Channels

Metrx can send alerts via:

  • Email: Instant emails to configured address
  • Slack: Messages to a Slack channel (webhook required)
  • Telegram: Direct messages to a Telegram user (bot token required)
  • Webhook: POST requests to your backend

Example: Slack Setup

  1. Create an Incoming Webhook in Slack (at api.slack.com/apps)
  2. Copy the webhook URL
  3. In Metrx Settings → Alerts, select Slack
  4. Paste your webhook URL
  5. Enable specific alert types
  6. Metrx will post alerts to your channel

Example Slack message:

🚨 Cost Spike Alert
Your costs jumped 50% today: $145 vs. average $95
Breakdown: GPT-4 calls increased 200%
Action: Review recent prompts or adjust temperature

Realtime Dashboard

The Metrx dashboard updates in real time as events occur.

How Real-Time Updates Work

Instead of polling the API repeatedly, the dashboard uses Supabase Realtime subscriptions:

  1. When you open the dashboard, it establishes a WebSocket connection
  2. New events are pushed to your browser instantly
  3. Dashboard components (charts, metrics, agent list) update automatically
  4. No page refresh needed

What Updates in Real-Time

  • New Events: LLM calls appear immediately
  • Cost Totals: Daily/monthly spending updates live
  • Agent Status: Online/offline status changes
  • Alert Triggers: New alerts appear in the notification panel
  • Agent Topology: Network graphs update as agents interact

Benefits

  • No Stale Data: Always see current costs and activity
  • Low Latency: Updates appear in under 100ms
  • Reduced Load: No polling requests hammering your servers
  • Better UX: Watch your agents work in real-time

Next Steps: See the API Reference for complete endpoint documentation.

API ReferenceArchitecture