Integration Guide

Connect your applications to track AI usage automatically

Quick Start

Start tracking AI usage in under 5 minutes

Configure Providers

Add your AI providers and set model pricing in the Providers page

Add Tracking Code

Use our SDK wrapper or call the API directly after each AI request

Monitor Usage

View real-time spending data, set alerts, and manage budgets

API Endpoint

POST request to track usage

POST/api/usage/track

AuthorizationBearer aur_live_… (org & default project resolved from the key)

Request Body

userIdstringUser making request (or the key's default)

providerstringRequired - openai, anthropic, google

modelstringRequired - e.g., gpt-4, claude-3-opus

inputTokensnumberRequired - Prompt tokens used

outputTokensnumberRequired - Completion tokens

requestIdstringOptional - Idempotency key (dedupes retries)

projectIdstringOptional - Associate with project (or key default)

metadataobjectOptional - Extra data to store

Send a single record, or { "records": [ … ] } to batch many in one request. Use POST /api/usage/check for a pre-flight budget gate that records nothing.

Integration Examples

Copy-paste code for your stack

import { generateText } from 'ai'
import { trackAIUsage } from '@/lib/auralis-tracker'

const result = await generateText({
  model: 'openai/gpt-4o',
  prompt: 'Your prompt here',
})

// org + default project come from the API key; userId optional override
await trackAIUsage({
  config: { apiKey: process.env.AURALIS_API_KEY!, userId: currentUser.id },
  model: 'openai/gpt-4o',
  usage: result.usage,
  requestId: result.response?.id, // optional idempotency key
})

Manual tracking gives you full control over when and what to track.

API Response

What you get back after tracking

Success Response (200)

{
  "success": true,
  "record": {
    "id": "uuid-here",
    "cost": 0.0234,
    "inputTokens": 150,
    "outputTokens": 50,
    "createdAt": "2026-05-17T..."
  }
}

Limit Exceeded (403)

{
  "error": "User spend limit exceeded",
  "currentSpend": 485.50,
  "spendLimit": 500.00,
  "attemptedCost": 23.45
}

Use this to block requests before hitting provider APIs!

Pro Tips

Pre-flight checks: Call GET /api/usage/track?organizationId=X&userId=Y before AI calls to check remaining budget
Project tracking: Use projectId to see spending per project and stay within project budgets
Metadata: Store request IDs, session info, or feature flags in metadata for debugging
Fire and forget: Track asynchronously so it doesn't slow down your AI responses