SettleSettleSettleSettle Dev Hub
Console →
SDK Reference

Track an Event

Track what users are doing in your app. Used for usage metering, billing, and analytics.

typescript
// Non-blocking — returns void immediately
// The event is queued and sent in the background
settle.events.track({
  userId: 'user_123',
  eventType: 'AI_QUERY',
  quantity: 1,           // Optional — defaults to 1
  metadata: {            // Optional — attach any context
    model: 'gpt-4',
    tokens: 1240,
  },
})

track() is synchronous and non-blocking. It never awaits a network call. Events are pushed to an internal buffer and sent to the API in batches automatically. This means it will never slow down your response time.

Why is track() not awaited, but wallet.debit() is? - events.track() (Usage Telemetry): Operates on a background in-memory queue and processes at 0ms user-latency. It returns void instantly. - wallet.debit() (Credit Transactions): Makes a blocking atomic database withdrawal and can throw InsufficientCreditsError. It MUST be awaited to guarantee transaction safety before exposing paid features.
Never do this: typescript // ❌ Wrong — track() returns void, not a Promise await settle.events.track({ userId, eventType: 'AI_QUERY' })

Always do this:

typescript
// ✅ Correct — fire and continue
settle.events.track({ userId, eventType: 'AI_QUERY' })

Naming your events — use SCREAMING_SNAKE_CASE#

GoodBad
AI_QUERYaiQuery
PDF_EXPORTpdf-export
API_CALLevent1
VIDEO_MINUTEuserDidSomething

💎 100% TypeScript Type-Safety#

While the SDK accepts any string as an eventType to remain completely flexible, you can strictly enforce autocomplete across your entire app by wrapping it in a typesafe map:

typescript
// 1. Define your immutable application events
export const APP_EVENTS = {
  AI_QUERY: 'AI_QUERY',
  IMAGE_GEN: 'IMAGE_GEN',
  PDF_EXPORT: 'PDF_EXPORT',
} as const;

export type AppEvent = typeof APP_EVENTS[keyof typeof APP_EVENTS];

// 2. Create a lightweight typesafe wrapper
export function trackAppEvent(userId: string, type: AppEvent) {
  settle.events.track({ userId, eventType: type });
}

// 3. Now get IDE Autocomplete & Compiler safety!
trackAppEvent(userId, APP_EVENTS.AI_QUERY);

Force-flush the buffer immediately#

typescript
// Use this during graceful shutdown
await settle.events.flush()

Check how many events are waiting#

typescript
console.log(settle.events.pendingCount) // e.g. 12
← PREVIOUSTransaction HistoryNEXT →Get Usage Summary