Track Endpoint

Record usage events for metered features and update customer balances in real-time

Overview

The /track endpoint records usage events for your metered features. Use it to:

• Track API calls, messages, or other usage-based features
• Deduct from customer balances in real-time
• Bill customers for overage usage
• Log events with custom properties for analytics

Quick Start

React Frontend

import { useCustomer } from '@useautumn/autumn-js/react';

function MessageComposer() {
  const customer = useCustomer();

  const sendMessage = async () => {
    // Send the message
    await sendMessageAPI(messageContent);
    
    // Track usage (fires in background)
    await fetch('/api/autumn/track', {
      method: 'POST',
      body: JSON.stringify({
        featureId: "messages",
        value: 1
      })
    });
  };

  return <button onClick={sendMessage}>Send Message</button>;
}

import { Autumn } from '@useautumn/sdk';

const autumn = new Autumn({ 
  secretKey: process.env.AUTUMN_SECRET_KEY 
});

// After processing an AI request
await processAIRequest();

// Track the usage
const result = await autumn.balances.track({
  customerId: "cus_123",
  featureId: "ai_tokens",
  value: 1312  // Consumed 1312 tokens
});

console.log(`Remaining: ${result.balance?.remaining}`);

from autumn import Autumn

autumn = Autumn(secret_key=os.environ["AUTUMN_SECRET_KEY"])

# After processing request
process_ai_request()

# Track the usage
result = autumn.balances.track(
    customer_id="cus_123",
    feature_id="ai_tokens",
    value=1312
)

print(f"Remaining: {result.balance.remaining}")

Parameters

customerId · string · required

The ID of the customer whose usage to track.

featureId · string

The ID of the feature to track. Use either featureId or eventName.

eventName · string

Event name to track usage for. Use instead of featureId when a single event should update multiple features.

// Track one event that updates multiple features
track({ 
  customerId: "cus_123",
  eventName: "api_request",  // Updates both "api_calls" and "bandwidth"
  value: 1,
  properties: { bytes: 2048 }
})

entityId · string

The ID of the entity for entity-scoped tracking (e.g., per-workspace usage).

value · number · default: "1"

The amount of usage to record. Use negative values to credit balance (e.g., when removing a seat).

// Deduct 500 tokens
track({ featureId: "ai_tokens", value: 500 })

// Credit back 100 tokens (e.g., refund)
track({ featureId: "ai_tokens", value: -100 })

properties · object

Additional properties to attach to the usage event for analytics and debugging.

track({
  featureId: "api_calls",
  value: 1,
  properties: {
    endpoint: "/v1/generate",
    model: "gpt-4",
    responseTime: 1250,
    userId: "usr_xyz"
  }
})

Response

interface TrackResponse {
  customerId: string;            // The customer ID
  entityId?: string;             // The entity ID (if entity-scoped)
  eventName?: string;            // Event name (if tracking by event)
  value: number;                 // Amount recorded
  balance: Balance | null;       // Updated balance (null for event-based)
  balances?: Record<string, Balance>;  // Multiple balances (for event-based)
}

interface Balance {
  featureId: string;
  granted: number;               // Total balance granted
  remaining: number;             // Balance remaining after this usage
  usage: number;                 // Total usage in current period
  unlimited: boolean;            // Whether feature is unlimited
  overageAllowed: boolean;       // Whether overage is allowed
  nextResetAt: number | null;    // Timestamp of next reset
}

Common Use Cases

Track API Calls

Backend

app.post('/api/generate', async (req, res) => {
  // Process the API request
  const result = await generateContent(req.body);
  
  // Track the usage
  await autumn.balances.track({
    customerId: req.user.id,
    featureId: "api_calls",
    value: 1,
    properties: {
      endpoint: "/api/generate",
      model: req.body.model,
      tokensUsed: result.tokens
    }
  });
  
  res.json(result);
});

@app.post("/api/generate")
async def generate(request: Request):
    # Process request
    result = await generate_content(request.body)
    
    # Track usage
    await autumn.balances.track(
        customer_id=request.user.id,
        feature_id="api_calls",
        value=1,
        properties={
            "endpoint": "/api/generate",
            "model": request.body.model
        }
    )
    
    return result

Track Variable Usage (Tokens, Storage, etc.)

Backend

// Track AI token usage
const completion = await openai.completions.create({
  model: "gpt-4",
  prompt: userPrompt
});

await autumn.balances.track({
  customerId: "cus_123",
  featureId: "ai_tokens",
  value: completion.usage.total_tokens,  // Variable amount
  properties: {
    model: "gpt-4",
    promptTokens: completion.usage.prompt_tokens,
    completionTokens: completion.usage.completion_tokens
  }
});

# Track storage usage
file_size = upload_file(file_data)

autumn.balances.track(
    customer_id="cus_123",
    feature_id="storage_gb",
    value=file_size / (1024 ** 3),  # Convert bytes to GB
    properties={
        "filename": file_data.name,
        "content_type": file_data.type
    }
)

Event-Based Tracking (One Event, Multiple Features)

Use eventName to track a single event that updates multiple feature balances:

Backend

// One event updates both "api_calls" and "ai_tokens" features
const result = await autumn.balances.track({
  customerId: "cus_123",
  eventName: "ai_completion",  // Event name instead of featureId
  value: 1,
  properties: {
    model: "gpt-4",
    tokensUsed: 1500
  }
});

// Response includes balances for all affected features
console.log(result.balances);
// {
//   "api_calls": { remaining: 99, ... },
//   "ai_tokens": { remaining: 8500, ... }
// }

Credit Usage (Negative Values)

Use negative values to add back to a customer’s balance:

Backend

// Customer removed a team member, credit back the seat
await removeTeamMember(memberId);

await autumn.balances.track({
  customerId: "cus_123",
  featureId: "seats",
  value: -1,  // Credit back 1 seat
  properties: {
    action: "member_removed",
    memberId: memberId
  }
});

# Refund tokens for failed request
autumn.balances.track(
    customer_id="cus_123",
    feature_id="ai_tokens",
    value=-1000,  # Credit back 1000 tokens
    properties={"reason": "request_failed"}
)

Entity-Scoped Tracking (Per-Workspace)

Backend

// Track usage for a specific workspace
await autumn.balances.track({
  customerId: "cus_123",
  entityId: "workspace_abc",  // Track for specific workspace
  featureId: "api_calls",
  value: 1,
  properties: {
    workspaceName: "Production"
  }
});

Idempotency

For critical operations, use an idempotency key to prevent duplicate tracking:

Backend

import { v4 as uuidv4 } from 'uuid';

const requestId = uuidv4();

// This request will only be processed once, even if retried
await autumn.balances.track({
  customerId: "cus_123",
  featureId: "credits",
  value: 100,
  idempotencyKey: requestId  // Internal parameter
});

Idempotency keys are automatically handled for you in most cases. Only use manual idempotency keys for critical operations where duplicate tracking would cause issues.

Error Handling

Backend

try {
  await autumn.balances.track({
    customerId: "cus_123",
    featureId: "api_calls",
    value: 1
  });
} catch (error) {
  if (error.code === "insufficient_balance") {
    // Customer exceeded their limit and overage not allowed
    return res.status(403).json({ 
      error: "Usage limit exceeded" 
    });
  } else if (error.code === "feature_not_found") {
    // Feature doesn't exist
    console.error("Invalid feature ID");
  }
}

try:
    autumn.balances.track(
        customer_id="cus_123",
        feature_id="api_calls",
        value=1
    )
except AutumnError as e:
    if e.code == "insufficient_balance":
        return {"error": "Usage limit exceeded"}, 403
    elif e.code == "feature_not_found":
        print("Invalid feature ID")

Check Before Track

To prevent exceeding limits, check access before tracking:

Backend

// Option 1: Check then track separately
const checkResult = await autumn.balances.check({
  customerId: "cus_123",
  featureId: "ai_tokens",
  requiredBalance: 1000
});

if (!checkResult.allowed) {
  return res.status(403).json({ error: "Insufficient tokens" });
}

await processAIRequest();

await autumn.balances.track({
  customerId: "cus_123",
  featureId: "ai_tokens",
  value: 1000
});

// Option 2: Atomic check + track (recommended)
const result = await autumn.balances.check({
  customerId: "cus_123",
  featureId: "ai_tokens",
  requiredBalance: 1000,
  sendEvent: true  // Atomically check AND track
});

if (!result.allowed) {
  return res.status(403).json({ error: "Insufficient tokens" });
}

// Usage already tracked, just process request
await processAIRequest();

Use check with sendEvent: true for atomic check + track operations. This prevents race conditions where usage could be tracked even when the balance is insufficient.

Batch Tracking

For high-volume scenarios, batch multiple track calls:

Backend

// Process multiple requests
const requests = await processBatchRequests(batchData);

// Track all usage in parallel
await Promise.all(
  requests.map(req => 
    autumn.balances.track({
      customerId: req.customerId,
      featureId: "api_calls",
      value: 1,
      properties: { batchId: batchData.id }
    })
  )
);

Query Parameters

skipCache · boolean · default: "false"

Bypass cache for fresh balance data.

expand · string[]

Expand related objects. Supports: "balance.feature"

Analytics and Reporting

Use the properties field to add context for analytics:

await autumn.balances.track({
  customerId: "cus_123",
  featureId: "api_calls",
  value: 1,
  properties: {
    // Request context
    endpoint: "/v1/generate",
    method: "POST",
    
    // Feature details
    model: "gpt-4",
    temperature: 0.7,
    
    // Performance metrics
    responseTime: 1250,
    tokensGenerated: 500,
    
    // User context
    userId: "usr_xyz",
    workspaceId: "ws_abc",
    
    // Business context
    plan: "enterprise",
    region: "us-east-1"
  }
});

These properties are available in your analytics dashboard and can be queried via the Events API.

Related Endpoints

• Check Endpoint - Verify access before tracking
• Webhooks - Listen for usage threshold events
• Events API - Query historical usage data

Next Steps

Check Access

Verify feature access before operations

Set Up Webhooks

Listen for threshold and limit events