@limitry/client - v0.4.1
    Preparing search index...

    Class Track

    Index

    Constructors

    constructor

    Methods

    usage

    Constructors

    Methods

    • Track usage with enforcement

      All-in-one endpoint for tracking usage with quota and rate limit enforcement.

      This is the recommended endpoint* for most use cases. It performs three operations in sequence:

      1. Rate Limit Check: Validates against configured rate limits (fast, Redis-based)
      2. Quota Check: Validates against configured quotas (database-based)
      3. Event Ingestion: Records the event if all checks pass

      Response Codes:*

      • 201 Created: Event tracked successfully, all limits within bounds
      • 429 Too Many Requests: Rate limit or quota exceeded (check response body for details)

      Rate Limit Headers:* The response includes standard rate limit headers:

      • X-RateLimit-Limit: Maximum requests allowed
      • X-RateLimit-Remaining: Requests remaining in current window
      • X-RateLimit-Reset: Unix timestamp when window resets
      • Retry-After: Seconds to wait before retrying (on 429 responses)

      Quota Headers (on quota exceeded):* When a quota is exceeded, the response includes:

      • Retry-After: Seconds to wait before retrying
      • X-Quota-Reset: Unix timestamp when the quota period resets
      • X-Quota-Period: Quota period (hour, day, week, month)
      • X-Quota-Metric: Quota metric (total_tokens, total_events, total_cost_cents)

      Dimension Matching:* Quotas and rate limits are matched based on dimensions extracted from:

      • customerId → customer_id
      • eventType → event_type
      • model → model
      • provider → provider
      • properties → All string values are included as dimensions

      Parameters

      • request: {
            costCents?: number;
            customerId: string;
            eventType: string;
            idempotencyKey?: string;
            inputTokens?: number;
            latencyMs?: number;
            model?: string;
            outputTokens?: number;
            properties?: { [key: string]: unknown };
            provider?: string;
            timestamp?: string;
            totalTokens?: number;
        }

        Request body

        • OptionalcostCents?: number

          Cost in cents (e.g., 25 = $0.25)

        • customerId: string

          Your customer's identifier (e.g., user ID, tenant ID)

        • eventType: string

          Type of event (e.g., "model_call", "embedding", "tool_call")

        • OptionalidempotencyKey?: string

          Unique key for deduplication (prevents duplicate events)

        • OptionalinputTokens?: number

          Number of input tokens consumed

        • OptionallatencyMs?: number

          Request latency in milliseconds

        • Optionalmodel?: string

          Model used (e.g., "gpt-4", "claude-3-opus", "gpt-3.5-turbo")

        • OptionaloutputTokens?: number

          Number of output tokens generated

        • Optionalproperties?: { [key: string]: unknown }

          Custom dimensions for quota/rate limit matching (e.g., user_id, team_id, feature)

        • Optionalprovider?: string

          Provider name (e.g., "openai", "anthropic", "google")

        • Optionaltimestamp?: string

          Format: date-time

          ISO 8601 timestamp (defaults to current time if not provided)

        • OptionaltotalTokens?: number

          Total tokens (auto-calculated if not provided)

      Returns Promise<
          {
              allowed: boolean;
              id: string;
              quotas: {
                  exceeded: boolean;
                  id: string;
                  limit: number;
                  metric: string;
                  name: string;
                  period: string;
                  remaining: number;
                  reset: number;
                  used: number;
              }[];
              rateLimits: {
                  exceeded: boolean;
                  id: string;
                  limit: number;
                  name: string;
                  remaining: number;
                  reset: number;
                  window: string;
              }[];
          },
      >

      Event tracked successfully - all limits within bounds

      const request: Request = {
        customerId: "customerid_123",
        eventType: "example",
        model: "example",
        provider: "provider_123"
        // ... other properties
      };

      const result = await client.track.usage(request);
      console.log(result);

      Invalid request body

      Unauthorized - Invalid or missing API key

      Rate limit or quota exceeded - request was blocked

      If a network error occurs

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods