UsageTap API Reference

Complete reference for the UsageTap REST API and SDK.

Table of Contents


Organization privacy

The organization admin selects an option under Allowed features in Configure → Privacy policy. Each option includes the permissions above it. The page separates Process for request from Save for later, alongside Features permitted. Processing lets UsageTap handle data during a request; saving retains a copy afterward. Granting a feature permission does not enable or configure it. Data your application sends still reaches UsageTap, even when saving is disabled. Omit data from requests if it must not reach UsageTap. Existing organizations keep their current access and optional identity storage until an admin saves a level. New organizations default to Metering: customer details. The dedicated real-time compression trial starts at Gateway & realtime compression.

Policy option Allowed data and operations
Metering: customer IDs only Meter and Guard use opaque customer IDs and usage measurements. UsageTap discards optional customer and end-user names and emails supplied with Meter requests.
Metering: customer details Adds optional customer and end-user names and emails.
Gateway & realtime compression Adds synchronous Gateway requests and runtime Compress.
Prompt sampling Adds configured production prompt sampling and sampling watches. Sample outputs and raw provider errors are omitted before storage.
Batch compression & quality reviews Adds retained responses, sample analysis, Gateway batches, benchmarks, and quality reviews.

Managed compression jobs, Prompt Review, Prompt Tightener, and Context Profiler also require Batch compression & quality reviews, because their workflows retain generated content or derived results. The server checks submissions and queued worker execution. Synchronous runtime compression continues to require Gateway & realtime compression.

Existing saved Prompt retention policies keep their permissions and appear as Batch compression & quality reviews (stored value PROMPT_RETENTION). The new Prompt sampling level uses PROMPT_ONLY_RETENTION; no migration is required. At that level, UsageTap stores sample input and usage measurements, omitting the separate output and raw-error fields for both inline and object-backed payloads. A content-free failure marker preserves sample error counts when a call fails. Prompt content is retained as supplied, including any prior assistant messages already present in the input; this is not content redaction. Existing retained responses keep their original expiry but are omitted from sample reads under the prompts-only policy. Meter response fields and identity-free Meter latency are unchanged.

API key scopes, billing eligibility, and sampling configuration still apply. On downgrade, existing names, emails, and samples retain their existing retention rules. Customer-profile reads and sample access follow the current policy. Meter receipts can still include previously saved customer details. A privacy-blocked operation returns HTTP 403 with code ORGANIZATION_PRIVACY_POLICY on the REST API, or organization_privacy_policy on Gateway.

For latency-sensitive API and SDK Meter calls, use a stable opaque customerId. Supplied customer names and emails can populate a new customer profile and call records. Optional end-user names and emails can be stored on call and custom-meter event records. Each write with contact fields checks the organization policy: organizations without a saved level and Metering: customer details or higher permit storage; Metering: customer IDs only omits those fields while retaining stable customer and end-user IDs. A request that also creates a profile shares one policy read. Use the customer API or dashboard to update existing profiles. Meter lifecycle responses preserve their existing fields, including names, emails, and email-prefilled billing links when those details are already stored. Meter writes without contact fields skip the customer-details privacy lookup. Idempotent replays and call completion preserve recorded identity without a new customer-details lookup. Customer-profile reads and writes, Gateway, Compress, and sample capture apply their own policy checks. Clients can use the existing cached sampling settings or a metadata-only decision to avoid a preflight round trip per model call. The sample upload checks current policy independently and can reject an upload based on an older decision.

Authentication

API requests require authentication via Bearer token or API key header unless an endpoint is explicitly documented as public. The model-alternatives lookup is public and does not require a UsageTap account or API key.

New server credentials use the utk- prefix and carry one or more OAuth-style scopes. The prefix identifies the credential format; scopes determine what the credential may do.

Scope Access
usage:read Customer usage, organization summaries, and anomalies
usage:write Call lifecycle and custom meter events
customers:read Customer and usage-plan listings
customers:write Customer provisioning, plan changes, and replenishment
gateway:invoke UsageTap Gateway requests
compression:invoke Compression, sampling, and recipe APIs
embeds:read Server-created embed sessions; must use a dedicated key

Scopes can be combined on one utk- key except embeds:read, which is kept separate because embed credentials may be exposed to a browser. Existing ck-, ak-, cmp-, gk-, and ek- keys remain valid with their historical permissions.

Permissions on an active server key can be edited without rotating the secret. The key ID, value, and prefix stay the same, and the new permissions take effect on the next authoritative authentication outside the metering fast path. POST /call, /call_begin, /call_end and /custom_meter authenticate through indexes to avoid an extra primary-record read. They may temporarily accept a revoked or replaced key or its previous permissions until index propagation; there is no promised maximum propagation time. Other durable-key requests recheck the current primary record and fail closed if it cannot be verified. New and replacement key discovery still depends on index propagation. Already-authorized work, signed-session lifetimes and the internal compression verifier's permitted 30-second positive cache are unchanged.

Editing a legacy server key migrates it to explicit stored scopes. Dedicated ek- browser keys cannot be converted to or from server permissions; create a separate key for that trust boundary.

Keys are server credentials. Do not place them in browser code.

Copy a newly created or rotated secret when it is returned; the plaintext is shown once. Listing credentials returns masked metadata, not plaintext or hashes.

Required scopes by operation

Scopes are independent and do not imply one another. Give a key every scope needed by its workflow.

Operations Required scope
POST /call, /call_begin, /call_end, /custom_meter usage:write
GET /calls/{callId}, /customers/{customerId}/usage, /usage/summary, /usage/anomalies, /usage/monitoring (including task lookup) usage:read
GET /customers/{customerId}/usage-context, /customers/{customerId}/forecast customers:read and usage:read
GET /customers, /usage-plans customers:read
POST /customers, /customers/{customerId}/change_plan, /customers/{customerId}/replenish customers:write
GET /sampling/settings, POST /sampling/decide, /samples, /compress_prompt compression:invoke
/v1/compression/authorize and published Compression profile, summary, and job routes compression:invoke
Gateway /v1/* routes gateway:invoke
POST /v1/client/sessions gateway:invoke and/or compression:invoke; returns a five-minute client session with the parent key's client-safe capabilities
POST /v1/embed-sessions embeds:read on a dedicated ek- key

New inline onboarding integration keys include usage:write, gateway:invoke, and compression:invoke, without read/admin/widget access. Existing keys keep their permissions; endpoint minimum scopes remain unchanged. Permissions do not enable routing or compression. Optional Gateway compression uses compress: true on supported requests; direct-provider Meter Tap calls require an SDK wrapper or a separate compression step.

Common combinations:

  • Direct metering plus Compression: usage:write, compression:invoke
  • Gateway with hosted Compression: gateway:invoke, compression:invoke
  • Customer administration with usage reporting: customers:read, customers:write, usage:read

Widget-data requests use the short-lived embed session token created by POST /v1/embed-sessions; they do not receive the long-lived API key.

Client applications use the short-lived session token created by POST /v1/client/sessions. The customer's authenticated backend calls this endpoint with its server-only key and server-derived customer_id and optional customer_user_id. The token inherits only client-safe capabilities: gateway:invoke becomes gateway:chat, and compression:invoke becomes compression:run. A combined parent receives both. The browser keeps the returned token in memory and renews it by calling that backend again before the five-minute expiry. Gateway access is restricted to POST /v1/chat/completions and POST /v1/responses; it cannot list models or use batch routes. The earlier /v1/gateway/sessions path remains an alias.

Authorization: Bearer YOUR_USAGETAP_API_KEY

Option 2: API Key Header

x-api-key: YOUR_USAGETAP_API_KEY

If both headers are present, Authorization takes precedence.


Gateway request limits

For Gateway POST /v1/chat/completions and POST /v1/responses, including streams, the entire decoded UTF-8 JSON body is limited to 1 MiB (1,048,576 bytes), checked before compression or provider dispatch. Gateway imposes no fixed message/input-item count limit. Provider and model input/context and output limits still apply. See Gateway request limits for fallback budgeting and the separate native batch limits.

Request Headers

Required Headers

Accept: application/vnd.usagetap.v1+json
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Optional Headers

Traffic environment

Send X-UsageTap-Environment: production or X-UsageTap-Environment: test on any API request, including POST /customers, /call, /call_begin, /call_end, /custom_meter, and reads/updates. This is request context, not a JSON metadata key. Header names are case-insensitive; values are exact. Empty, unknown or conflicting values return 400 INVALID_ENVIRONMENT. For Automatic customers, omitting the header leaves new records unlabelled. Historical records are not inferred or relabelled.

Admins can open a customer panel, choose Traffic group: Production / Dev-test, and save it. This pins CustomerSubscription.trafficEnvironment and overrides request/SDK labels for new LLM calls and API/custom-meter reports. The customer immediately appears in that group. Choose Automatic (request labels) to clear the pin. Existing usage is not rewritten; usage filters still use each event's stored label. Old history leaves the views through normal retention.

POST /customers
Accept: application/vnd.usagetap.v1+json
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
X-UsageTap-Environment: test

{"customerId":"acme"}

Calls and custom-meter events store environment. Customer creation and usage add persistent customer environment labels; one ID may have both. GET /customers filters membership by this header and returns environments; continue following nextToken, including on empty filtered pages. GET /calls/{callId} only returns a matching labelled record when filtered. GET /usage/summary filters recorded LLM totals by the header. Exact task lookups (GET /usage/monitoring with customerId/taskId) filter recorded LLM and meter totals separately. MCP call list/summary tools accept an optional environment filter; its HTTP header also supplies the default for recorded call reads, task lookup and usage overview. Keep the same filter while paging. Dashboard filters recorded calls, tokens, spend, drivers, active customers, trends and recent activity; configured customer totals use environment membership. The Usage page filters recorded quantities, cost, forecast training and exports before calculating totals. Live filters recent activity. Page-level Environment filters on Overview, Customers, Live Activity and Trends & Forecast default to All traffic and remember the organization selection. Call Log has its own filter. The filters offer All traffic, Production and Dev / test. Production includes both explicitly production-labelled and legacy/unlabelled records; Dev / test includes only test-labelled records. This view grouping does not rewrite stored labels. API header filters continue matching exact recorded labels; omission includes all traffic, and supported explicit unlabelled filters remain available. Usage Forecast defaults to All traffic and offers Production; Dev/Test-only forecasting is not offered. Production forecasts use dedicated aggregates across hourly, daily, weekly and monthly views, including customer exclusions. Historical coverage must be prepared before those forecasts are available; incomplete coverage is not treated as zero usage and does not trigger raw-history scans. Calls, tokens and dollars become available when call-history preparation finishes; API/custom-meter forecasts wait for their meter history. Usage Forecast anomaly deviationPercent is nullable when comparison with a zero baseline makes the percentage undefined. Actual/expected values and anomaly evidence are preserved.

call_end and delivery retries retain the classification/policy recorded at begin/report, even if the customer group changes later. A pinned call accepts the deployment's request labels without changing its recorded group. Automatic calls reject conflicting explicit labels with 409 ENVIRONMENT_CONFLICT. Keep event idempotency keys stable across delivery retries. The Gateway forwards the label into metering and preserves it in queued completion delivery. Never send this header to the underlying model provider.

MCP list_customers, find_customers, list_calls and summarize_calls accept an optional environment filter (production, test, or unlabelled). Customer filters select membership; call filters apply before totals. Keep the filter unchanged while paging and follow cursors even on empty pages. The HTTP environment header supplies defaults for these tools; explicit tool filters take precedence.

Environment labels do not create separate customers, balances, plans, Stripe modes, or parallel Guard baselines. Guard behavioral comparisons always use Production + unlabelled samples and matching retained history. The environment-mix check uses all recorded traffic to detect substantial Dev/Test growth and share changes, with existing Guard notification opt-ins. There is no Dev/Test inclusion setting or setting-driven history reset. Viewing filters do not change detection. Historical findings keep their original population context; rebuilding references does not replay notifications. Account balance/context and customer signals remain account-wide; a header is not an authorization boundary and does not make test usage nonbillable. Existing event rates and limits apply.

Header Description Example
Idempotency-Key Unique key for safe retries 550e8400-e29b-41d4-a716-446655440000
x-usage-correlation-id Track related requests corr_abc123
x-usage-sdk SDK identifier js/1.4.0

Important: Authenticated endpoints require Accept: application/vnd.usagetap.v1+json; requests without it receive 406 Not Acceptable. Public model-alternatives requests use ordinary application/json and do not require an Accept header.


Response Format

All responses follow the canonical envelope format:

Success Response

{
  result: {
    status: "ACCEPTED",
    code: string,           // Status code (e.g., "CALL_BEGIN_SUCCESS")
    message?: string,       // Optional human-readable message
    timestamp: string       // ISO 8601 timestamp
  },
  data: {                   // Endpoint-specific data
    // ...
  },
  correlationId: string     // For request tracing
}

Error Response

{
  result: {
    status: "ERROR",
    code: string,           // Error code
    message: string,        // Error description
    timestamp: string
  },
  error: object,            // Error-specific machine-readable fields
  correlationId: string
}

Idempotency

UsageTap supports three methods for providing idempotency keys:

1. Request Header (Preferred)

POST /call_begin
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "customerId": "cust_123",
  "requested": { "standard": true }
}
{
  "customerId": "cust_123",
  "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
  "requested": { "standard": true }
}

3. Request Body (Deprecated: idempotency)

{
  "customerId": "cust_123",
  "idempotency": "550e8400-e29b-41d4-a716-446655440000",
  "requested": { "standard": true }
}

Priority: Header > idempotencyKey > idempotency

Auto-Generated Keys

If no idempotency key is provided, UsageTap generates one deterministically by hashing:

  • Organization ID
  • Customer ID
  • Feature name
  • Requested entitlements
  • Call type
  • Pricing mode

The resolved key is returned in data.idempotency.key.

This fallback is for compatibility, not normal call creation. Identical inputs can replay an earlier call. Direct integrations should send a unique key for each new logical call and reuse that key only when retrying that call. The JavaScript SDK generates a unique key by default.

Idempotency Behavior

  • Same key + same payload → Reuses the same callId and recorded entitlement decision. Account, plan and balance metadata may reflect current state; the full response is not cached. Current caller access is still checked.
  • Same key + different payload → Returns error
  • Different key + same payload → Creates new call

On a begin replay, policy and entitlementHints preserve the recorded effective acceptance, denial or downgrade, using existing call fields. They do not claim the exact historical plan configuration. Current plan policy is available in subscription.limitType. If current account metadata cannot be read, subscription, customerStatus, canceled and inactive are null; balance amounts are omitted, meter quantities remain unknown, and payg.enabled is null when its current setting is unavailable. Saved allowed flags and PAYG selection remain authoritative for this call. A new operation requires a fresh key. An inconsistent stored denial that also allows its requested tier returns 409 CALL_BEGIN_STATE_CONFLICT; it requires investigation rather than an automatic retry or lifecycle repair.


REST API Endpoints

GET /v1/model-alternatives/{modelKey}

Resolve a provider model key to source-backed same-provider equivalents and cross-provider candidates. This endpoint is public, CORS-enabled, and does not require an API key or the UsageTap vendor media type.

Use a provider-qualified key when possible. The greedy path also accepts model keys that contain /.

curl https://api.usagetap.com/v1/model-alternatives/openai/gpt-4-turbo
{
  "schemaVersion": 1,
  "catalogVersion": "2026-09-16",
  "requested": {
    "modelKey": "openai/gpt-4-turbo",
    "provider": "openai",
    "model": "gpt-4-turbo"
  },
  "lifecycle": {
    "status": "DEPRECATED",
    "shutdownAt": "2026-10-23",
    "source": {
      "label": "OpenAI API deprecations",
      "url": "https://developers.openai.com/api/docs/deprecations",
      "checkedAt": "2026-09-16"
    }
  },
  "action": "REPLACE",
  "recommendedModelKey": "openai/gpt-5.6-sol",
  "equivalents": [
    {
      "modelKey": "openai/gpt-5.6-sol",
      "provider": "openai",
      "relation": "official_replacement",
      "confidence": "authoritative",
      "rationale": "The provider names this model as the replacement.",
      "requiresEvaluation": false
    }
  ],
  "alternatives": [
    {
      "modelKey": "anthropic/claude-sonnet-4-6",
      "provider": "anthropic",
      "relation": "similar_price_and_strength",
      "confidence": "candidate",
      "rationale": "UsageTap places this model in a similar capability and price class; evaluate it on your workload before switching.",
      "requiresEvaluation": true
    }
  ],
  "automation": {
    "canResolveWithoutUsageTapAccount": true,
    "autoApplyRecommended": true,
    "note": "The recommended key is provider-designated. Opt in to automatic substitution only after validating request parameters and output behavior."
  }
}

equivalents lists provider-designated replacements with confidence: "authoritative" first, followed by any same-provider similarity candidates. alternatives contains cross-provider candidates. Computed entries include their score, price distance, current input/output price, and the mechanical capability evidence used to rank them. They report confidence: "candidate" and must be evaluated on the application's workload.

When available, match explains how a supplied alias or fuzzy model identifier was resolved, while pricing identifies the current pricing snapshot. The recommendationSource value distinguishes provider, admin_review, computed, and none results. An unknown key with no pricing/catalog match returns HTTP 200, lifecycle.status: "UNKNOWN", action: "REVIEW", and empty candidate arrays so application fallback logic remains deterministic.

GET /v1/model-alternatives returns the catalog metadata and all known transitions.

POST /call_begin

Start a usage tracking session and retrieve customer entitlements.

Existing Gateway integrations can send top-level taskId and taskType on Chat Completions and Responses requests, including streams, or in each native batch item's body. Gateway validates the task strings, forwards them to this endpoint, and removes them from provider requests. Do not send a separate call_begin for the same Gateway call.

Endpoint: POST {baseUrl}/call_begin

Request Body:

{
  customerId: string;           // Required: Your customer identifier
  taskId?: string;              // Customer-scoped operation ID, 1-128 characters
  taskType?: string;            // Stable workload category, 1-128 characters
  customerUserId?: string;      // Optional: Stable end-user identifier
  customerUserName?: string;    // Optional: End-user display name
  customerUserEmail?: string;   // Optional: End-user display email
  feature?: string;             // Optional: Feature being accessed
  requested?: {                 // Optional: Requested capabilities
    standard?: boolean;         // Standard tier models
    premium?: boolean;          // Premium tier models
    audio?: boolean;            // Audio processing
    image?: boolean;            // Image generation
    search?: boolean;           // Web search
    reasoningLevel?: "NONE" | "LOW" | "MEDIUM" | "HIGH";
  };
  idempotencyKey?: string;      // Direct callers should send one per logical call
  tags?: string[];              // Optional: Tags for analytics
  customerName?: string;        // Optional display name for first provisioning
  customerEmail?: string;       // Optional email for first provisioning
  stripeCustomerId?: string;    // Optional: Link to Stripe customer
  batch?: boolean;              // Optional: Whether this call uses batch pricing (default: false)
  pricingMode?: "batch" | "standard"; // Optional: Explicit pricing mode (default: "standard")
}

call_begin reports entitlements, including the allowed reasoning ceiling. Execution identity belongs to call_end. Do not infer reasoningEffort from reasoningTokens; omit unknown values and include provenance whenever effort is known. The UsageTap gateway treats effort as a normalized cross-provider ladder. When a selected Anthropic or Google model does not support the requested value, the gateway maps downward to the nearest supported level (with minimal mapping to the lowest non-zero level) and reports that effective value at call_end. For models that support disabling reasoning, none is preserved; otherwise it maps to the lowest supported level.

Response (200 OK):

{
  result: {
    status: "ACCEPTED",
    code: "CALL_BEGIN_SUCCESS",
    timestamp: "2025-11-05T12:00:00.000Z"
  },
  data: {
    callId: string;             // Use in call_end
    callType?: "standard" | "API";
    startTime: string;          // ISO 8601 timestamp
    feature: string;            // Echo of feature
    tags?: string[];            // Echo of tags
    newCustomer: boolean;       // True if customer was just created
    canceled: boolean | null;   // Null when current account status is unavailable
    policy: "NONE" | "BLOCK" | "DOWNGRADE";

    // What customer can actually use
    allowed: {
      standard: boolean;
      premium: boolean;
      audio: boolean;
      image: boolean;
      search: boolean;
      reasoningLevel: "NONE" | "LOW" | "MEDIUM" | "HIGH";
    };

    // Guidance for selecting models
    entitlementHints: {
      suggestedModelTier: "premium" | "standard" | "none";
      reasoningLevel: "NONE" | "LOW" | "MEDIUM" | "HIGH";
      policy: "NONE" | "BLOCK" | "DOWNGRADE";
      downgrade?: {
        reason: string;         // Why downgraded (e.g., "PREMIUM_QUOTA_EXHAUSTED")
        fallbackTier?: string;  // Suggested fallback
      };
    };

    rateLimits?: {              // Optional rolling-call limit snapshots
      rollingCalls: object | { [scope: string]: object };
    };

    // Current usage levels per meter; null quantities mean unavailable
    meters: {
      [meterName: string]: {
        remaining: number | null; // Null is unknown; `unlimited` is separate
        limit: number | null;
        used: number | null;
        unlimited: boolean;       // true = unbounded; remaining is informational
        ratio: number | null;     // remaining/limit (0-1), null when unlimited
      };
    };

    // Quick lookup for remaining ratios
    remainingRatios: {
      [meterName: string]: number | null;
    };

    // Subscription details
    subscription: {
      id: string;
      usagePlanVersionId: string;
      planName: string;
      planVersion: string;
      limitType: "NONE" | "BLOCK" | "DOWNGRADE";
      reasoningLevel: "NONE" | "LOW" | "MEDIUM" | "HIGH";
      lastReplenishedAt: string;
      nextReplenishAt: string;
      subscriptionVersion: number;
      customerFriendlyName?: string;
      customerEmail?: string;
      stripeCustomerId?: string;
      pending?: {               // Scheduled plan change
        usagePlanVersionId: string;
        strategy: string;
        effectiveAt: string;
      };
    } | null; // Null when current account metadata is unavailable on replay.

    // Organization-specific model mappings
    models?: {
      standard?: string[];      // Standard tier models
      premium?: string[];       // Premium tier models
    };

    // Resolved idempotency key
    idempotency: {
      key: string;              // Always matches callId
      source: "explicit" | "derived";
    };

    // Batch pricing
    batch: boolean;             // Whether batch pricing is applied
    pricingMode: "batch" | "standard"; // Pricing mode for this call

    // Legacy fields (backward compatibility)
    plan?: {
      id: string;
      name: string;
      version: string;
    };
    balances?: {
      tokensRemaining?: number;
      searchesRemaining?: number;
    };
  },
  correlationId: string
}

Example:

curl -X POST https://api.usagetap.com/call_begin \
  -H "Authorization: Bearer ck-..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.usagetap.v1+json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerId": "cust_123",
    "customerUserId": "user_123",
    "feature": "chat.completions",
    "requested": {
      "standard": true,
      "premium": true,
      "search": true,
      "reasoningLevel": "HIGH"
    },
    "tags": ["production", "web-app"]
  }'

call_begin returns an accepted HTTP 200 envelope even when the requested entitlement is denied. Inspect data.allowed before invoking the provider. A denied call is stored with status NOT_ALLOWED and is already finalized; do not invoke the provider or call /call_end for that denial. Under DOWNGRADE, select only an application-approved fallback model.

Configured LLM burst limits count distinct begin attempts, including quota, credit and burst denials. Reusing a call's idempotency key replays its saved decision and does not increment or extend the window. Counts are shared across traffic environments and isolated by organization, customer, call type and tier. Premium burst downgrade checks standard capacity before allowing fallback. That attempt counts against the denied premium tier and the checked standard tier; the call's rateLimitKey identifies the effective standard tier. PAYG does not bypass a burst denial, and no funds are reserved by these controls.

Admission state and the call record are committed atomically. Rolling counts use one-second buckets, so expiry may conservatively block for less than one extra second. rateLimits.rollingCalls.resolutionSeconds is 1; used is the count before the current attempt. Its state is fresh once the entire relevant window has been tracked by the new writer. Existing customers remain available during a one-window warm-up, with indexed history included and state: estimated; concurrent new attempts are serialized, but old index-only history can still lag. Strict boundaries require all writers on the new implementation and a full window of tracked history. Increasing the window can temporarily restore the estimated state. Disabling limits preserves recorded calls; the next ordinary begin invalidates inactive counter state so re-enabling cannot reuse incomplete history. Existing records and labels are never rewritten.

Storage failure, invalid state, exhausted contention retries or a bounded migration-read/item-size budget return 503 BURST_ADMISSION_UNAVAILABLE before provider work. Retry with the same idempotency key. A failed atomic transaction creates neither a call nor a counted attempt; an ambiguous successful commit is replayed from the primary call record. This does not provide exactly-once provider execution for arbitrary client retries.


GET /sampling/settings

These settings support integrations that explicitly opt into sampling. Automatic Gateway capture additionally requires a saved valid capture rate or an active feature watch; the default settings returned to explicit integrations do not enable Gateway capture. A request with llmGateway.sampling: false opts out.

Load the organization's canonical sampling policy. This is the best option for high-throughput, non-SDK integrations that want to cache the policy and evaluate it locally.

For an end-to-end Gateway, SDK, and direct-API guide that finishes with a Production Sample model benchmark, see Benchmark Models on Production Tasks.

Endpoint: GET {baseUrl}/sampling/settings

The response includes rate, minInputTokens, feature/customer filters, retentionDays, a content-derived version, and cache metadata. Honor the Cache-Control header (currently five minutes); the response also includes an ETag containing the policy version.

curl https://api.usagetap.com/sampling/settings \
  -H "Authorization: Bearer cmp-..." \
  -H "Accept: application/vnd.usagetap.v1+json"
{
  "data": {
    "version": "a1b2c3d4e5f60718",
    "rate": 0.1,
    "minInputTokens": 2000,
    "features": { "include": [], "exclude": [] },
    "customers": { "exclude": [] },
    "retentionDays": 7,
    "cacheSeconds": 300,
    "settingsExpiresAt": "2026-07-23T00:05:00.000Z"
  }
}

customerId identifies the customer account. End-user fields are optional. Prefer a stable, non-PII customerUserId; name and email are display metadata and may be omitted. CamelCase, snake_case, and the legacy nested customer object are accepted.

Authentication and permission failures are intentionally distinct:

  • 401 UNAUTHORIZED: the credential is missing, malformed, unknown, revoked, or otherwise invalid. The response does not claim that adding a scope will repair an invalid credential.
  • 403 API_KEY_SCOPE_REQUIRED: the credential is valid but lacks the required permission. error.requiredScope names the exact scope to add.
{
  "result": {
    "status": "ERROR",
    "code": "API_KEY_SCOPE_REQUIRED",
    "message": "This operation requires the \"usage:read\" API key scope.",
    "timestamp": "2026-08-04T12:00:00.000Z"
  },
  "error": {
    "reason": "API_KEY_SCOPE_REQUIRED",
    "requiredScope": "usage:read"
  },
  "correlationId": "corr_abc123"
}

Gateway errors use the OpenAI-compatible error envelope and expose the same machine-readable values as error.code and error.requiredScope.

Evaluate filters before the rate: customer exclusion, feature exclusion, feature inclusion, minimum input tokens, then the sampling rate. Only selected calls should be sent to /samples.


POST /sampling/decide

Ask UsageTap for a centralized sampling decision without sending prompt or response content. This is the simplest direct-API integration and can run in parallel with the model request.

Endpoint: POST {baseUrl}/sampling/decide

{
  samplingKey?: string;     // Stable provider/request ID; generated if omitted
  customerId?: string;
  feature?: string;
  inputTokens?: number;     // Preferred when known
  inputCharacters?: number; // Accepted instead; approximated at 4 chars/token
}

Supplying a stable samplingKey makes retries return the same decision for the same policy version. The response contains sample, a machine-readable reason, decisionId, samplingKey, policyVersion, and settingsExpiresAt.

curl -X POST https://api.usagetap.com/sampling/decide \
  -H "Authorization: Bearer cmp-..." \
  -H "Accept: application/vnd.usagetap.v1+json" \
  -H "Content-Type: application/json" \
  -d '{"samplingKey":"req_123","customerId":"cust_123","feature":"assistant.answer","inputTokens":4200}'

POST /samples

Store a call selected by the SDK, a local policy evaluation, or /sampling/decide. The sample automatically expires according to the retention period configured on the Sampling page.

Endpoint: POST {baseUrl}/samples

{
  sampleId?: string;       // Stable ID recommended for safe retries
  decisionId?: string;     // From /sampling/decide
  policyVersion?: string;  // From settings or decision response
  customerId?: string;
  feature?: string;
  environment?: string;
  tags?: string[];
  provider: string;
  model?: string;
  input: unknown;          // Required; retained raw call data
  output?: unknown;
  usage?: unknown;
  latencyMs?: number;
  error?: unknown;
}

The maximum request body is 300 KiB. A successful response includes sampleId, receivedAt, expiresAt, retentionDays, and policyVersion. Because this endpoint stores raw application data, call it only after a positive sampling decision.

Send the original input, not a stored payload reference. The top-level $usagetapSamplePayload input key is reserved for server storage; supplying it returns HTTP 400 with reason SAMPLE_PAYLOAD_REFERENCE_RESERVED.


POST /compress_prompt

Record prompt compression savings for an existing call. This endpoint is optional and should only be used after call_begin when your application has already compressed the prompt locally. Do not send raw prompt content, compressed prompt content, messages, tool schemas, or other user data to this endpoint.

Endpoint: POST {baseUrl}/compress_prompt

Request Body:

{
  callId: string;                         // Required: From call_begin response
  promptCompression: {
    provider: "heuristic" | "toon" | "thetokencompany" | "usagetap";
    originalTokens: number;
    compressedTokens: number;
    savedTokens?: number;                 // Re-derived by UsageTap
    tokenSavingsRatio?: number;           // Re-derived by UsageTap
    techniques: string[];                 // e.g. ["json-minify", "embedded-json-toon"]
  };
}

Response (200 OK):

{
  result: {
    status: "ACCEPTED",
    code: "PROMPT_COMPRESSION_RECORDED",
    timestamp: string
  },
  data: {
    callId: string;
    updated: true;
    provider: "heuristic" | "toon" | "thetokencompany" | "usagetap";
    originalTokens: number;
    compressedTokens: number;
    savedTokens: number;
    tokenSavingsRatio: number;
    techniques: string[];
  },
  correlationId: string
}

Behavior:

  • Compression is opt-in. call_begin behaves the same whether you use this endpoint or not.
  • UsageTap stores only counts, ratios, provider, techniques, and timestamp. Raw prompt content is never stored by this endpoint.
  • Token savings use lightweight regex estimation, not a provider-specific BPE tokenizer.
  • The JavaScript SDK's promptCompress() handles local compression and calls this endpoint for you. If compression or telemetry fails, the SDK returns the original prompt so the vendor call can continue.

Example:

curl -X POST https://api.usagetap.com/compress_prompt \
  -H "Authorization: Bearer cmp-..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.usagetap.v1+json" \
  -H "x-usage-correlation-id: corr_abc123" \
  -d '{
    "callId": "call_xyz789",
    "promptCompression": {
      "provider": "heuristic",
      "originalTokens": 260,
      "compressedTokens": 180,
      "techniques": ["json-minify", "embedded-json-toon"]
    }
  }'

POST /call_end

Successful usage finalization is separate from Stripe delivery. Configured Stripe quantities are saved with the usage record and attempted after commit; completed replay and the existing replenisher retry outstanding delivery without applying usage again. Provider acceptance does not establish invoice inclusion. See Stripe usage delivery for retry/reconciliation limits.

completionReason is an optional top-level call_end / SDK endCall field: a trimmed, non-empty provider-reported string of at most 128 characters, without control characters. Use the primary Chat Completions choice's finish_reason, Anthropic's stop_reason, or Responses incomplete_details.reason (otherwise its terminal status, such as completed). Omit it when unknown; never infer it from HTTP 200, zero tokens, or UsageTap lifecycle status. Call details display missing values as Unknown. This field does not change pricing or lifecycle status. Guard can compare reported reason categories when sufficient eligible data is available.

The optional value is persisted on the existing Call record and returned by the call-pricing read API when present. Gateway captures it from provider responses and streams. Updated SDK/observer source wrappers capture it automatically; installed packages require a release containing this support. Older integrations may use direct HTTP.

Report actual usage for a tracked call.

Endpoint: POST {baseUrl}/call_end

Request Body:

{
  callId: string;               // Required: From call_begin response
  completionReason?: string;    // Provider terminal reason, 1-128 characters; omit when unknown
  providerUsed?: string;        // Executing vendor, e.g. "openai"
  modelUsed?: string;           // Model identifier (e.g., "gpt-5.6-luna")
  reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
  reasoningEffortSource?: "provider_response" | "provider_request" | "gateway_config" | "model_default";
  reasoningMode?: string;       // Optional provider-specific thinking mode
  reasoningBudgetTokens?: number; // Optional explicit thinking budget
  inputTokens?: number;         // Total prompt tokens, including cache reads/writes
  responseTokens?: number;      // Completion tokens
  cachedInputTokens?: number;   // Subset served from prompt cache
  cacheWriteInputTokens?: number; // Subset written to prompt cache
  reasoningTokens?: number;     // Reasoning tokens (o1 models)
  searches?: number;            // Number of web searches
  audio?: number;               // Audio processing units
  audioSeconds?: number;        // Audio duration in seconds
  promptCompression?: {         // Optional before/after savings metadata
    provider: "heuristic" | "toon" | "thetokencompany" | "usagetap";
    originalTokens: number;
    compressedTokens: number;
    savedTokens?: number;        // Re-derived by UsageTap for consistency
    tokenSavingsRatio?: number;  // Re-derived by UsageTap for consistency
    techniques?: string[];
  };
  isPremium?: boolean;          // Override premium detection
  error?: {                     // Report error if call failed
    code: string;
    message: string;
  };
  stripeCustomerId?: string;    // Override Stripe customer ID
  batch?: boolean;              // Optional: Whether this call uses batch pricing (default: false)
  pricingMode?: "batch" | "standard"; // Optional: Explicit pricing mode (default: "standard")
}

Response (200 OK):

{
  result: {
    status: "ACCEPTED",
    code: "CALL_END_SUCCESS",
    timestamp: "2025-11-05T12:00:05.000Z"
  },
  data: {
    callId: string;
    status: "COMPLETED" | "FAILED";
    error?: {
      code: string;
      message: string;
    };
    providerUsed?: string;
    modelUsed?: string;
    reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
    reasoningEffortSource?: "provider_response" | "provider_request" | "gateway_config" | "model_default";
    reasoningMode?: string;
    reasoningBudgetTokens?: number;
    costUSD: number;            // Final cost after pricing mode
    costUsdNano?: string;       // High-precision decimal integer representation
    costBreakdown?: object;     // Provider/model pricing components
    standardCostUSD: number;    // Cost before batch reduction
    pricingMultiplier: 0.5 | 1; // Applied pricing multiplier
    batch: boolean;             // Whether batch pricing was applied
    pricingMode: "batch" | "standard"; // Pricing mode used
    usage: {
      inputTokens: number;
      cachedInputTokens: number;
      cacheWriteInputTokens: number;
      billableInputTokens: number;
      responseTokens: number;
      reasoningTokens: number;
    };
    metered: {                  // Usage that was counted
      calls?: number;
      tokens?: number;          // Provider-reported output tokens
      reasoningTokens?: number;
      searches?: number;
      audio?: number;
      audioSeconds?: number;
    };
    spendVelocity?: {           // Aggregate-backed customer spend telemetry
      currency: "USD";
      source: "usage_aggregate";
      generatedAt: string;
      customerId: string;
      currentCallCostUsd: number;
      windows: {
        hour: {
          bucket: string;        // UTC bucket, e.g. "2026-05-01T17"
          windowMinutes: 60;
          startedAt: string;
          endedAt: string;
          completedCostUsd: number;
          completedCalls: number;
        };
        day: {
          bucket: string;        // UTC bucket, e.g. "2026-05-01"
          windowMinutes: 1440;
          startedAt: string;
          endedAt: string;
          completedCostUsd: number;
          completedCalls: number;
        };
      };
    };
    balances?: {                // Remaining quotas
      tokensRemaining?: number;
      searchesRemaining?: number;
      audioSecondsRemaining?: number;
    };
    stripeCustomerId?: string;
  },
  correlationId: string
}

The persisted plan limit and Stripe meter keys standardTokens and premiumTokens represent standard-tier and premium-tier output tokens. Input tokens, including cache reads and cache writes, remain recorded and affect provider cost but do not consume these allowances or Stripe token meters. metered.tokens reports the same output-token quantity. Reasoning tokens are a breakdown of provider output and are not added again.

When error is supplied with non-empty code and message, UsageTap accepts the finalization, stores the call as FAILED, and returns the normalized error metadata in data.error. Invalid error objects return 400 BAD_REQUEST. Sanitize the message; do not send prompts, credentials, or raw provider bodies.

If the active-subscription lookup is empty at completion, UsageTap returns 409 NO_ACTIVE_SUBSCRIPTION and retains reported usage and any calculable provider cost on the failed call. Unresolved pricing remains unavailable rather than a known zero. This path does not deduct allowances or create customer charges. Its conditional write cannot replace a concurrent finalization; the winning stored result is replayed. If a competing update is still unfinished or its result cannot be read, 503 CALL_END_CONFLICT asks the caller to retry the same completion instead of implying that usage was saved. Provider HTTP status does not change the accounting error returned by a retry.

Premium Detection:

UsageTap automatically classifies calls as premium based on model pricing:

  • Premium: Output token price > $4.00 per million tokens
  • Standard: Output token price ≤ $4.00 per million tokens

Override with isPremium: true or isPremium: false for custom models.

Batch Pricing:

Batch mode applies a 50% discount to standard pricing rates. Prefer pricingMode: "batch"; batch: true is retained as a compatibility flag. When both are supplied, pricingMode is authoritative. A mode set on call_begin carries through to call_end; either field on call_end can override the stored mode.

UsageTap accepts the execution mode asserted by the authenticated application. Provider response usage supplies token quantities but is not treated as proof of batch execution. OpenAI and Anthropic per-response usage objects do not expose a dependable batch-priced signal; applications using their native asynchronous batch APIs must retain that workflow context and report it.

For auditability, call_end returns and persists:

  • standardCostUSD: cost before the batch rate.
  • pricingMultiplier: 0.5 for batch or 1 for standard.
  • costUSD: final cost after the multiplier.

PAYG markup and credit settlement use costUSD, so the batch rate is applied before markup and credit deduction. Token and call allowances still decrement using actual usage.

When promptCompression is present, UsageTap stores the before/after token counts, derives saved tokens and percentage decrease, and estimates prompt input cost avoided from the resolved model pricing. Raw prompt content is never included in this telemetry.

Example:

curl -X POST https://api.usagetap.com/call_end \
  -H "Authorization: Bearer ck-..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.usagetap.v1+json" \
  -H "x-usage-correlation-id: corr_abc123" \
  -d '{
    "callId": "call_xyz789",
    "modelUsed": "gpt-5.6-sol",
    "inputTokens": 512,
    "responseTokens": 256,
    "reasoningTokens": 0,
    "searches": 1,
    "batch": true,
    "pricingMode": "batch"
  }'

POST /call

Unified endpoint that combines begin, vendor call, and end in one request.

Endpoint: POST {baseUrl}/call

Request Body:

{
  // Standard call_begin fields
  customerId: string;
  customerUserId?: string;
  customerUserName?: string;
  customerUserEmail?: string;
  feature?: string;
  requested?: { /* entitlements */ };
  idempotencyKey?: string;
  tags?: string[];

  // Optional vendor call configuration
  vendor?: {
    url: string;                // Vendor API endpoint
    provider?: string;          // Vendor label recorded at call_end
    method: "POST" | "GET";     // HTTP method
    headers: {                  // Headers to send
      [key: string]: string;
    };
    body?: object;              // Request body
    timeoutMs?: number;         // Request timeout (default: 30000)
    responseType?: "json" | "text" | "stream";
  };

  // Usage overrides (if vendor block is omitted)
  usage?: {
    modelUsed?: string;
    inputTokens?: number;
    responseTokens?: number;
    // ... other usage fields
  };

  // Optional error details
  end?: {
    error?: {
      code: string;
      message: string;
    };
  };
}

Response (200 OK):

{
  result: {
    status: "ACCEPTED",
    code: "CALL_SUCCESS" | "CALL_VENDOR_WARNING",
    timestamp: string
  },
  data: {
    begin: {                    // call_begin response
      callId: string;
      allowed: { /* ... */ };
      // ... other begin fields
    };
    end: {                      // call_end response
      costUSD: number;          // Final provider/model cost
      standardCostUSD: number;  // Cost before batch reduction
      pricingMultiplier: number;
      costUsdNano?: string;
      costBreakdown?: object;
      metered: { /* ... */ };
      balances: { /* ... */ };
      payg?: {
        chargedUsd: number;     // Final customer PAYG charge
        markupPercent: number;
      };
    };
    vendor?: {                  // Vendor response (if vendor block provided)
      ok: boolean;
      status: number;
      modelUsed?: string;
      error?: {
        message: string;
        details?: object;
      };
    };
    endUsage: {                 // Final reported usage
      tokens: number;
      modelUsed: string;
      // ... other usage fields
    };
  },
  correlationId: string
}

Behavior:

  • /call checks the requested tier's data.allowed flag before provider work or finalization (requested.premium: true selects premium; otherwise standard). If it is false, /call returns the call_begin HTTP 200 accepted envelope directly, including its data.callId, data.allowed, and available rate-limit evidence. This response has no compound data.begin, data.end, data.vendor, or data.endUsage. Neither the provider nor /call_end is invoked, including when only usage overrides were supplied. Delivery retries honor the saved decision even when fresh rate-limit evidence is absent.
  • Standard fallback permission does not authorize the original premium vendor payload. /call returns that begin decision for application-controlled model selection; it does not rewrite the vendor request or finalize the fallback.
  • If vendor is provided, UsageTap makes the HTTP call and extracts usage
  • If vendor is omitted, only usage overrides are recorded
  • Non-2xx vendor responses still trigger call_end with error metadata

Example:

curl -X POST https://api.usagetap.com/call \
  -H "Authorization: Bearer ck-..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.usagetap.v1+json" \
  -d '{
    "customerId": "cust_123",
    "customerUserId": "user_123",
    "feature": "chat.completions",
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
    "requested": {
      "standard": true,
      "premium": true
    },
    "vendor": {
      "url": "https://api.openai.com/v1/chat/completions",
      "method": "POST",
      "headers": {
        "Authorization": "Bearer sk-...",
        "Content-Type": "application/json"
      },
      "body": {
        "model": "gpt-5.6-luna",
        "messages": [
          { "role": "user", "content": "Hello" }
        ]
      },
      "responseType": "json"
    },
    "usage": {
      "modelUsed": "gpt-5.6-luna"
    }
  }'

GET /calls/{callId}

Retrieves pricing for an existing call without changing usage, balances, or settlement state. This endpoint requires an API key with the usage:read scope. A missing call and a call owned by another organization both return 404 CALL_NOT_FOUND.

Endpoint: GET {baseUrl}/calls/{callId}

Response (200 OK):

{
  result: {
    status: "ACCEPTED";
    code: "CALL_PRICING_RETRIEVED";
    timestamp: string;
  };
  data: {
    callId: string;
    customerId: string | null;           // Customer account identity recorded on the call
    customerUserId: string | null;       // End-user identity, when recorded on the call
    status: "IN_PROGRESS" | "COMPLETED" | "FAILED" | "TIMEOUT" | "NOT_ALLOWED";
    pricingStatus: "PENDING" | "FINAL" | "UNAVAILABLE";
    currency: "USD";
    costUSD: number | null;             // Final provider/model cost
    costUsdNano: string | null;
    standardCostUSD: number | null;     // Cost before batch reduction
    pricingMultiplier: number;
    pricingMode: "batch" | "standard";
    batch: boolean;
    costBreakdown: object | null;
    modelPricingSnapshotId: string | null;
    pricingTier: string | null;
    pricingTierReason: string | null;
    providerUsed: string | null;
    modelUsed: string | null;
    startTime: string | null;
    endTime: string | null;
    payg: {
      usingCredit: boolean;
      chargedUsd: number | null;         // Final customer PAYG charge
      chargeNanoUsd: string | null;
      markupPercent: number | null;
      settlementStatus: "PENDING" | "POSTED" | "FAILED" | null;
      settlementFailureReason: string | null;
    };
    pricingUnavailableReason?: string;
  };
  correlationId: string;
}

pricingStatus must be FINAL before treating costUSD as finalized. A completed call can report UNAVAILABLE when the model or pricing snapshot could not be resolved; this prevents an unresolved price from being mistaken for a free call.

customerId and customerUserId are the only customer identity fields returned by this endpoint. Use stable, opaque, non-PII values for both fields. customerUserId is null when it was not recorded on the call. Customer and end-user names or emails, billing-provider identifiers, organizationId, and the internal orgIdCustomerId composite key are deliberately not returned.

curl https://api.usagetap.com/calls/call_123 \
  -H "Authorization: Bearer utk-..." \
  -H "Accept: application/vnd.usagetap.v1+json"

POST /customers

Create or retrieve a customer subscription idempotently.

Endpoint: POST {baseUrl}/customers

Authentication: A Usage key with Meter calls access (ck-…) or an Admin key (ak-…) from the provider organization.

Request Body:

{
  customerId: string;           // Required: Your customer identifier
  customerFriendlyName?: string; // HIGHLY IMPORTANT BUT OPTIONAL: Display name (preferred field; alias: customerName)
  customerName?: string;        // HIGHLY IMPORTANT BUT OPTIONAL: Alias for customerFriendlyName
  customerEmail?: string;       // HIGHLY IMPORTANT BUT OPTIONAL: Email for notifications
  stripeCustomerId?: string;    // Link to Stripe customer
}

Response (200 OK):

{
  result: {
    status: "ACCEPTED",
    code: "CUSTOMER_READY",
    timestamp: string
  },
  data: {
    customerId: string;
    newCustomer: boolean;       // True if just created, false if existing
    canceled: boolean;
    policy: "NONE" | "BLOCK" | "DOWNGRADE";
    allowed: { /* ... */ };     // Current entitlements
    entitlementHints: { /* ... */ };
    meters: { /* ... */ };      // Current usage
    remainingRatios: { /* ... */ };
    subscription: { /* ... */ }; // Full subscription details
    models?: { /* ... */ };
    plan?: { /* ... */ };
    balances?: { /* ... */ };
    stripeCustomerId?: string;
  },
  correlationId: string
}

Idempotent: Calling multiple times returns the same customer. Only newCustomer: true on first call.

Example:

curl -X POST https://api.usagetap.com/customers \
  -H "Authorization: Bearer ck-..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.usagetap.v1+json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerId": "cust_123",
    "customerFriendlyName": "Acme Corp",
    "customerEmail": "billing@acme.com",
    "stripeCustomerId": "cus_stripe123"
  }'

GET /customers/{customerId}/usage

Check current usage status without creating a call.

Each successful metering check consumes one UsageTap Meter event. It does not consume UsageTap's API/MCP allowance and remains available when that allowance or its eligible overage credit is exhausted. Failed checks do not consume a Meter event. Authentication and the usage:read permission are still required.

Endpoint: GET {baseUrl}/customers/{customerId}/usage

Path Parameters:

  • customerId (string, required): Customer identifier

Response (200 OK):

Same structure as POST /customers but without newCustomer field.

Example:

curl -X GET https://api.usagetap.com/customers/cust_123/usage \
  -H "Authorization: Bearer ck-..." \
  -H "Accept: application/vnd.usagetap.v1+json"

GET /customers/{customerId}/usage-context

Prepare a compact, read-only account usage brief from the same canonical contract used by the UsageTap MCP tool. Requires both customers:read and usage:read.

Endpoint: GET {baseUrl}/customers/{customerId}/usage-context

Query Parameters:

  • timezone (optional): IANA timezone, default UTC
  • forecastMetric (optional): calls, inputTokens, outputTokens, allTokens, dollars, agenticApi, customMeter1, or customMeter2
  • includeForecast (optional): true by default
  • includeSignals (optional): true by default

The response contains contractVersion: "1", customer and plan facts, meters with explicit units, funding context, the latest seven completed UTC days versus the preceding seven, current-period quantities, signals, forecast status and quality, deterministic review reasons, and evidence completeness. All periods use an inclusive start and exclusive end.

Only agenticApi, customMeter1, and customMeter2 have a one-to-one allowance mapping and may return projectedAllowanceExhaustionAt. Aggregate call and token forecasts never fabricate a combined allowance runout. A runout of included allowance does not guarantee service interruption because purchased meter credit, PAYG funding, or another configured policy may allow usage to continue. dollars means recorded provider cost, not revenue or margin.

curl -X GET "https://api.usagetap.com/customers/cust_123/usage-context?forecastMetric=agenticApi" \
  -H "Authorization: Bearer utk-..." \
  -H "Accept: application/vnd.usagetap.v1+json"

Missing and cross-tenant customer IDs return the same non-enumerating 404. Responses use Cache-Control: private, no-store.


GET /customers/{customerId}/forecast

Return the canonical, customer-scoped forecast component without the rest of the account brief. Requires both customers:read and usage:read.

Endpoint: GET {baseUrl}/customers/{customerId}/forecast

Query Parameters:

  • metric (required): one of the supported metrics listed above
  • timezone (optional): IANA timezone, default UTC

The projection horizon is resolved by the server from the customer's next replenishment boundary. The public endpoint does not accept an organization ID, arbitrary horizon, model tuning, exclusions, seasonality test mode, or growth adjustment. Forecast status is one of available, insufficient_history, not_applicable, incomplete, or temporarily_unavailable.

curl -X GET "https://api.usagetap.com/customers/cust_123/forecast?metric=agenticApi&timezone=UTC" \
  -H "Authorization: Bearer utk-..." \
  -H "Accept: application/vnd.usagetap.v1+json"

MCP get_guard_summary

Requires organization-wide usage:read authorization. This read-only MCP tool supports daily operational briefs alongside customer signals and usage totals. It does not introduce a REST route or SDK method.

{
  "startTime": "2026-11-03T00:00:00.000Z",
  "endTime": "2026-11-04T00:00:00.000Z"
}

Omit both times for the trailing 24 hours. Start is inclusive and end exclusive; maximum range is seven days within 56-day retention. Convert a calendar day in the desired timezone to UTC before calling. Period membership uses saved assessment window starts, not individual call timestamps or notification delivery. Traffic headers do not change Guard populations: behavioral checks use Production plus unlabelled; environment mix uses all traffic. Each comparison retains its original traffic policy and separate LLM/API/custom-meter identity.

The response includes period, comparisons, notifications, limits, complete and nextToken. Each comparison includes grouped period findings, periodAssessmentCounts (saved, ready, notReady, unavailable), historyComplete, separate current readiness/checks, and an evidenceUrl. Current check visualAlert follows current detector Alert settings; saved history is retained even when visual alerts are off. Saved size is separate from current state; informational cost changes remain informational.

Each page reads one comparison scope, up to 500 retained period rows, and up to 100 notice records. Follow nextToken until null, including empty pages. Counts are page-local. Merge findings with the same id, sum their comparison/major comparison counts, and preserve earliest/latest times and latest evidence. Keep the same explicit range or omit both times on continuation. Tokens bind the organization, authenticated principal, period and settings revisions; restart if settings change. Concurrent new records or delivery updates are not a frozen transactional snapshot. Scope discovery uses current retained application scopes.

Notifications preserve change/recovery linkage and separate email/Slack delivery: sent, skipped, or unknown_or_pending. A notice record does not prove delivery. An empty stream does not prove no findings. Reading does not send or enable alerts, change settings, acknowledge incidents, recover findings, or block usage.

complete and historyComplete describe pagination, not monitoring coverage or health. Saved comparison counts do not establish uninterrupted assessments. Overlapping comparisons are not independent incidents or affected-call counts. Report missing, stale, pending, disabled and unsupported evidence explicitly; current readiness is observed now, separately from the selected period. Guard findings support investigation rather than proof of compromise. This application report is separate from get_customer_signals and get_usage_anomalies.

MCP get_usage_anomalies opt-in evidence

Requires organization-authorized usage:read. Omission preserves the existing anomaly response. Optional evidence requires outer metric: "calls". Within evidence, supply question, mode (calendar_counts, rate_comparison, rate_replay), aligned inclusive startTime/exclusive endTime, and optionally exact customerId/environment. Rates require referenceEndTime strictly inside the range; bucketMinutes is 5 or 60 (calendar counts require 60). End at least five minutes ago. Maximum 31 days / 1000 buckets / 5000 calls / 100 source pages / ten-second read budget. rateOutcome is errors or successes; assumeIndependentTrials defaults false. The existing environment header supplies the default when the tool omits it.

The additional evidence field returns the question, counts, source completeness, organization timezone (explicit UTC default when unavailable), uncertainty, recent comparisons and supporting rows. Calendar evidence retains selected peer dates, fallback tier and expected range; rate evidence retains distinct integer successes/trials and assumptions. Empty complete reads mean zero recorded exposure; unknown outcomes or capped reads stay unknown. Page evidence.analysis.comparisons using evidence.evidenceOffset and evidence.expectedFingerprint=evidence.analysis.fingerprint with identical analysis arguments; changed source snapshots return source_changed. Failed optional analysis returns evidence.status=unavailable while retaining the existing daily/hourly anomalies. evidenceLimit defaults to 5, maximum 20. Use the returned list_calls drilldown and corroborate with related usage/Guard evidence under caller policy. Extra evidence retains its own explicit source scope and never replaces existing organization-wide anomaly windows. No separate MCP tool is added. No incident confirmation, alert delivery, scheduled detector changes or SDK method. This MCP-only analysis has no separate REST endpoint. See full semantics and examples.

GET /usage/monitoring

Current boundary: without taskId, this endpoint returns { "scopes": [], "nextToken": null, "retired": "r0" }; it no longer starts history imports or exposes R0 scope snapshots. Exact task lookup below is unchanged. R1 application monitoring starts automatically for all organizations. Organization admins can inspect evidence; change/recovery email and Slack alerts require explicit existing notification opt-in. There is no incident case-management workflow. Guard compares genuine call/report populations; batched quantities do not create independent calls or timestamps. Applications automatically compare trailing two-hour populations using each detector's supported calendar history. The organization timezone is used, with an explicit UTC default. Same-weekday, weekday/weekend and daily references activate according to eligible support; sparse checks use labelled recent compatible history. Customers do not configure comparison policies. Dense calendar periods are reproducibly sampled without replacement, up to 256 observations per historical period and 4,096 current observations. Numeric comparisons use 512 observations per population within those caps, dividing the reference budget across periods to bound exact-test runtime. Periods below their allocated quota retain every observation. Categorical recent-history fallback can use the 4,096-observation reference budget. Full recorded counts, missingness and sampling support remain separate; samples can miss rare changes. Provisional sampling assumptions and a per-assessment statistical budget do not establish a daily or lifetime false-positive rate. Missing policy, coverage, support or resolution does not establish health. Recorded cost-per-call distributions, reported completion reasons and denominator-based token/user/task coverage have comparison adapters. Missing historical measurements stay unknown. Token coverage and end-user attribution coverage measure eligible completed LLM calls; API/custom attribution coverage measures genuine reports. Historical LLM samples without the user-coverage measurement stay unknown; reporting an ID does not establish authorization or enable individual-user behavioral monitoring. Errors compares the recorded response-code distribution across eligible finalized successes, failures and timeouts, including shifts among successful codes; missing codes stay unknown. API call rate uses reported AGENTIC_API quantities over five-minute exposure with an explicit daily UTC reference. Batches do not reveal individual call times; missing/delayed windows remain unknown. Guard Settings provides separate Alert and Notification dropdowns per detector, each with Off, All, Major. All includes minor and major changes. Development is the default preset for organizations without saved detector settings: major behavioral alerts and notifications, with Environment mix Off. Production uses Alert: All and Notification: Major for every connected detector. Individual overrides show Custom; presets populate the existing controls and apply on Save. Existing saved preferences keep their behavior. Alert: Major keeps smaller or unclassified changes neutral in evidence/history, without warning icons, active findings or amber timeline emphasis. Alert: Off removes visual alerts while allowing opted-in notifications; both Off skips evaluation. Both levels are saved together in the existing detector preference. Notification: Off stops pending delivery; channel opt-in is still required. Meter recording and saved findings are preserved. The Production preset shows all supported changes; notifications default to major changes using detector-specific magnitude criteria, with an optional all-supported-changes setting per detector. Email and Slack still require existing explicit channel opt-ins. A smaller change can notify when it first becomes major; repeated changed windows do not repeat alerts. Settings do not reset history or create catch-up alerts. Guard never automatically blocks usage. An hourly calendar reuses saved findings: green means no change in loaded findings, not verified health; partial history and refresh failures stay explicit.

For event payloads that make this evidence useful, see Guard instrumentation.

Exact task lookup

Supplying taskId switches this endpoint from scope snapshots to recorded task usage. customerId is required for that mode. Both values are top-level query parameters, not metadata. Requires usage:read and the canonical Accept header.

GET /usage/monitoring?customerId=acme&taskId=import_123
Accept: application/vnd.usagetap.v1+json
Authorization: Bearer <server-side-key>

The canonical envelope has code USAGE_MONITORING and this data shape:

{
  organizationId: string;
  customerId: string;
  taskId: string;
  totalsScope: "this_page";
  taskCompletion: "not_reported";
  llmCalls: number;
  recordedLlmCostUsd: number;
  missingLlmCostCalls: number;
  inProgressCalls: number;
  meterUnits: {
    meterKey: string;
    meterName: string;
    amount: number;
    reportingEvents: number;
    recordedChargeUsd: number;
  }[];
  records: {
    kind: "llm" | "meter";
    id: string;
    at: string;
    feature?: string;
    taskType?: string;
    status?: string; // LLM status; inspect instead of assuming completion
  }[];
  nextToken: string | null;
}

Each page reads up to 50 indexed LLM records and 50 indexed meter records before meter eligibility filtering. Repeat the same customer/task query with nextToken until null, including empty pages. Sum page counters and merge meter totals by meterKey; never treat the first page as the whole task. Do not reuse a cursor for a different task/customer. Indexes are eventually consistent and retention follows source records. Missing cost and open calls remain explicit; commercial meter charges are not LLM provider cost. Blocked/internal meter events are omitted, while LLM records can include non-completed statuses. Untagged historical events cannot be joined. Task completion and cost per completed task are not inferred.

MCP get_task_usage({ customerId, taskId, nextToken? }) returns the same task page semantics. The SDK does not currently expose a task-read method.

Historical R0 scope snapshot schema (retired)

Guard evaluates the application and each customer independently. Comparable model/execution workloads and different meter units remain separate; totals and detail overlap and must not be added. Anomalyzer 0.3.0 supplies numerical evidence. Configured measured-event rules can operate on the first trustworthy value. Learned cost checks accumulate actual priced calls across quiet calendar periods; recent hourly relationships and daily-hour volume profiles have their own calibration. Readiness, reference quality and business impact are separate. Missing periods stay unknown; no-call per-event values remain undefined. Legacy history-only references retain null scores and cannot trigger or recover incidents. Existing learned detectors activate automatically from eligible data. Optional early risk rules are configured by admins in Guard Integration instructions. Email/Slack delivery needs separate opt-in; a ready check does not establish current health.

scope.applicationTotal: true identifies compatible application totals; scope.applicationWorkload: true identifies comparable operation/model/execution populations across customers. scope.customerTotal: true identifies that customer's totals. These views overlap; never add them. Application contributors have coverage (complete, partial, changed), customerCount, customerCountIsLowerBound and bounded customers. Partial lists are not a full ranking. Dollar totals are recorded LLM cost, not custom-meter charges.

New evidence has version: "guard-anomalyzer-v2" and engine containing name, package version, profile revision, policy revision and fixed origin. Every factors[].mechanism identifies its profile, observationBasis (event_index or hourly_measurement), reference state/quality, maturity, training/calibration sample counts, pattern names, active/violated rule IDs, materiality and unavailable reasons. relationship retains the formula and aligned numerator/denominator values. event retains the actual event ID, original time, customer and optional task. Interpret event values using that source timestamp, not as the mean of an hourly window. Same-time events retain distinct identities without asserting execution order.

callCostRisk and consumptionRisk are actual measured-value criteria. costPerCall can be a native recent-call check or an hourly relationship; inspect the mechanism. recordedSpend is hourly recorded LLM dollars. All pre-existing learned detectors have automatic profiles with built-in defaults; optional risk rules are not their activation gate. Distributions preserve actual token/size/ feature vectors and use daily calibrated distance profiles. Allowance burn keeps its pre-existing supporting-context role. Critical requires a configured impact criterion; a large score or multiple correlated metrics is insufficient. Native EVENT incidents do not auto-recover from quiet hours. Business settings are versioned signed-in admin operations, not public REST/MCP mutations. Default optional rules are empty; learned detector defaults remain active. Unconfigured optional rule checks are excluded from detector-readiness counts.

Hourly snapshots retain minutes: 60. Unknown or delayed periods are not healthy; recordedQuiet means a successful scheduled zero-reported-volume check only. Retained legacy referenceOnly/weekly readiness fields describe their original method, not a universal readiness gate for new evidence. Older cadence scopes remain historical with evaluationEnabled: false. Follow each profile's reasons when learning, importing history or original references are unavailable.

Read persisted Guard evidence using the existing usage:read permission. Optional customerId narrows the result; follow nextToken for additional scopes. The equivalent MCP read tool is get_usage_monitoring.

Reads return initialized customer-total scopes first, followed (without customerId) by independent application totals/workloads and organization/meter pooled feature-mix scopes, then detailed customer scopes. pageScope: "customer_totals" identifies customer-total pages; pageScope: "organization" identifies pooled application pages. Overview clients should continue through both summary families before presenting application coverage. Follow the opaque nextToken until null for all detailed scopes, including empty filtered pages; pooled pages are not a complete list of customer exceptions. Tokens are bound to the organization and customer filter. A customer-filtered read never returns pooled totals as that customer's usage.

Enabled feature-mix scopes add the following fields without changing Meter events:

  • scope.level: "organization" with no customerId identifies pooled evidence. Existing customer scopes retain customerId and may omit level.
  • scope.composition: the configuration revision, selected features, and effective time.
  • snapshots[].composition.features[]: reported units/events, their separate shares, baseline shares, and baseline mean quantities for each selected feature plus Other and Unspecified.
  • snapshots[].composition.expectedUnits: the total consumption reference for that window.
  • allocationUnits, allocationFraction, and expectedAllocationFraction inside the composition evidence: recorded allocation and its observed/expected window consumption, or null when unavailable. These are not remaining balances.
  • consumptionStatus and allowanceStatus: independent readiness/change states; a composition change does not establish increased consumption or allowance burn.
  • factors[].role: "supporting_context" identifies allowance-burn evidence. Its value, reference, and local status remain visible, but it has no incident severity and does not participate in Guard status, triggers, confirmation, escalation, quarantine, reminders, or recovery requirements. This does not change customer allowance alerts, limits, forecasts, or customer signals.
  • evaluationEnabled: false for a disabled or superseded composition scope. Its snapshots remain historical evidence, not a statement of current health.
  • snapshots[].composition.pool: pooled contributor coverage, customer count, customerCountIsLowerBound, and up to five observed contributors with units, reporting events, and shares. contributionCoverage is complete, partial, or changed. Partial lists do not rank unseen customers; changed totals withhold shares and the count. Detector totals include all eligible events independently of contributor pagination.

Pooled scopes combine raw consumption for one meter and settings revision, across customer plans and allowances. Allocation fields are null, allowanceStatus is unavailable, and no pooled allowance-burn factor is emitted. Customer scopes retain their own allocation evidence and independent incident lifecycle. Pooled readiness requires its own eligible history and residual calibration and does not establish local customer readiness.

Monitoring incident reads include triggerEligible. A retained allowance-only incident returns false even if its historical stored status is still OPEN or PENDING; do not count it as an active Guard behavioral incident. Background reevaluation retires those records with guardResolutionReason: "allowance_context_only" and no recovery notification. This retirement does not establish current account health. Original incident evidence remains historical; snapshot factor roles and aggregate statuses apply the current context policy.

API / Agentic Calls snapshots and incident evidence can include optional runaway JSON, version runaway-agent-calls-v1:

  • state: candidate, sustained, severe, within_range, learning, insufficient_data, or data_delayed. This describes quantity evidence, separately from the parent incident's confirmation/status.
  • consumedCalls, expectedCalls, excessCalls, callsPerMinute, expectedCallsPerMinute, and rateMultiple (null when unavailable).
  • reportingEvents, baselineWindows, and baselineReportingEvents preserve the distinction between consumption and reporting batches.
  • elevatedWindows and at most three recentWindows, each with windowStart, state (elevated, within_range, or unknown), consumedCalls, and expectedCalls. Persistence is quantity-specific and cadence-specific.
  • features: up to five available feature contributions with feature, bucket, consumedCalls, expectedCalls (baseline mean), and callShare.
  • featureMixChanged, reportingPatternChanged, and taskAttributionFraction (null when unavailable) provide investigation context. Task coverage is the fraction of reporting events supplying a task ID; it does not identify a task, actor, or individual agent.

Runaway uses the existing quantity gates and scoped incident. Two elevated quantity windows among three qualify sustained growth; critical quantity gates qualify a severe spike immediately. Other factors and allowance burn do not count toward this persistence. incident.runawayDetectedAt records the first qualification in its incident cycle and coordinates one new-case announcement across cadences. It is not an execution timestamp or proof of a runaway agent. Missing/delayed evidence is unknown, and snapshot quantity state does not by itself resolve the parent incident. Historical snapshots may lack this field until their next evaluation. Stored-history initialization does not replay historical incidents.

Check timestamps, data readiness, and each factor's status before interpreting changes. Reporting events are not assumed to equal underlying API requests. Feature mix uses events from the effective time of the applicable settings revision.

Monitoring reads initialize up to eight weeks of stored completed calls and eligible meter reports through resumable background queries. The optional page-level history object reports phase (calls, meters, complete), from, asOf, baselineBefore, processed (source records checked), and updatedAt. While loading, scopes and recorded observations may be partial. A scope's optional recordedWindow contains its latest nonempty live or reconstructed hourly sample, including start, minutes, calls, token/cost coverage counts and totals, meter units, histograms, and source (live or stored_history). Original delivery latency is unknown for reconstructed samples. This sample can be low-volume or from an open hour; it is not current anomaly evidence. Readiness and factor status remain authoritative. Only completed loading supplies historical baseline hours older than the 48-hour live lateness horizon; overlapping live hours are replaced, not added. Missing hours stay unknown, and replay never creates retrospective incidents. These optional fields are returned through REST, MCP and the signed-in app. Pending history is resumed from saved cursors by an independent one-minute background schedule. Recent eligible meter samples may appear before the full LLM replay finishes; the subsequent meter pass deduplicates them. processed counts records checked, including any preview reports checked again.

Signed-in organization settings use monitoringFeatureMixConfig (read) and monitoringSetFeatureMixConfig (admin-only write) through the application Data API. The mutation takes meter slot/key, enabled, up to 64 exact features, and expectedRevision for optimistic concurrency. These settings operations are not new public REST or MCP mutation capabilities. No SDK reporting change is needed.

The signed-in Data API also provides monitoringFeatureMixCustomers for viewers: pass organizationId, a pooled scopeKey, minutes (5 or 30), the exact ISO windowStart, and optionally nextToken. It returns up to 50 customers with customerId, units, and events, plus totalsScope: "this_page". Its cursor is bound to the organization, scope, and window. Contributions can change with late reporting and are separate from frozen incident evidence; they do not identify which customers independently triggered. This full contributor lookup is a signed-in application query; REST/MCP snapshots include the bounded summary above.

Guard is free when you use UsageTap Meter. Evaluations, views, and opt-in alerts do not add billable events; normal pricing for underlying Meter events applies.

The optional applicationHistory status tracks independent application/native-call initialization using the same status fields as history; it never adds customer summaries again.

In the application, Live View → Guard and Meter → Guard → Dashboard show detector status, active findings and a compact hourly history row. Older loads earlier history; unloaded empty hours are omitted and the date grid is expandable. Green history cells mean no change in loaded findings, not verified health. Each surface's activity dot and timestamp use its latest loaded usage observation; a green activity dot means a usage window within 15 minutes, independently of assessment status. Findings retains prior changes with current status, saved measurements and expandable guidance/evidence, with customer/call/task drill-down on demand. Integration guide and Email / Slack notifications are separate action links. Enable UsageTap Guard changes and recovery email/Slack checkboxes in Settings → Notifications to opt in. Destinations are shared with other admin alerts. No LLM is used for descriptions; category shares explain the overall distribution finding and are not independently significant.


POST /customers/{customerId}/change_plan

Change customer's usage plan.

Endpoint: POST {baseUrl}/customers/{customerId}/change_plan

Path Parameters:

  • customerId (string, required): Customer identifier

Request Body:

{
  planId: string;               // Required: Target plan ID
  strategy?: "IMMEDIATE_RESET" | "IMMEDIATE_PRORATED" | "AT_NEXT_REPLENISH";
}

Strategy Options:

  • IMMEDIATE_RESET (default when omitted through the API): Switch immediately, grant the target plan's full allowances, and start a new replenishment cycle
  • IMMEDIATE_PRORATED: Switch immediately, preserve usage already consumed, adjust remaining allowances to the target limits, and keep the current replenishment date
  • AT_NEXT_REPLENISH: Keep the current plan until the existing scheduled replenishment, then apply the target plan

Response (200 OK):

{
  result: {
    status: "ACCEPTED",
    code: "PLAN_CHANGED",
    timestamp: string
  },
  data: {
    success: boolean;
    subscription: {             // Updated subscription
      id: string;
      usagePlanVersionId: string;
      planName: string;
      planVersion: string;
      // ... full subscription details
      pending?: {               // If strategy = AT_NEXT_REPLENISH
        usagePlanVersionId: string;
        strategy: string;
        effectiveAt: string;
      };
    };
  },
  correlationId: string
}

Example:

curl -X POST https://api.usagetap.com/customers/cust_123/change_plan \
  -H "Authorization: Bearer ak-..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.usagetap.v1+json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "planId": "plan_premium_v2",
    "strategy": "IMMEDIATE_RESET"
  }'

POST /custom_meter

Configured Stripe mappings export the recorded customer-unit amount, including batched/unlimited and blocked: true reports. This reports consumption, independently of internal credit funding or PAYG overage units. Delivery/replay uses the saved event identity; see Stripe usage delivery.

Update (increment) a custom meter for a customer by recording a new usage event. Custom meters allow you to track any usage metric beyond the standard LLM usage counters.

Use meterSlot: "AGENTIC_API" for the dedicated Agentic & API Calls meter. One unit represents one HTTP API request or MCP tool call. It uses the same allocation, purchased meter credits, PAYG overages, and single or graduated pricing as Custom Meter 1 and 2. No model, token count, standard/premium tier, or call lifecycle is required. See the integration example.

Endpoint: POST {baseUrl}/custom_meter

Headers:

  • Accept: application/vnd.usagetap.v1+json
  • Content-Type: application/json
  • Idempotency-Key (recommended): unique per report, reused only for its retries

Request Body:

{
  customerId: string;           // Required: Customer identifier
  taskId?: string;              // Customer-scoped operation ID, 1-128 characters
  taskType?: string;            // Stable workload category, 1-128 characters
  customerUserId?: string;      // Optional: Stable end-user identifier
  customerUserName?: string;    // Optional: End-user display name
  customerUserEmail?: string;   // Optional: End-user display email
  meterSlot: "CUSTOM1" | "CUSTOM2" | "AGENTIC_API"; // Required: Which meter to increment
  amount: number;               // Required: Positive safe integer usage quantity
  feature?: string;             // Optional: Feature identifier for tracking
  tags?: string[];              // Optional: Tags for categorization
  metadata?: object;            // Optional: Additional metadata
}

taskId and taskType are trimmed, non-empty, case-sensitive strings without control characters. Send them as top-level fields here and on call_begin. Use one task ID across related LLM and meter events, but a unique idempotency key per logical event. For API calls, send safe metadata.method and metadata.endpoint route labels; for MCP, send metadata.toolName and optional metadata.serverName. Arbitrary metadata/tags do not create Guard detector dimensions. feature and customerUserId also belong at the top level. See Guard instrumentation for batching, privacy, and detection-readiness guidance.

API/custom-meter task-type mix reuses top-level taskType and actual consumed calls/units; update shares support batching investigation. Unspecified labels remain measurement context. One report is one sampling event. This compares reported consumption, not distinct/completed tasks or cost per task; taskId remains customer-scoped lookup identity. The application monitor adds no continuous customer/end-user or LLM task-type collection.

Response (200 OK):

{
  result: {
    status: "ACCEPTED",
    code: "CUSTOM_METER_SUCCESS",
    timestamp: string
  },
  data: {
    success: boolean;           // true
    eventId: string;            // Unique event identifier
    meterSlot: "CUSTOM1" | "CUSTOM2" | "AGENTIC_API";
    amount: number;             // Amount that was recorded
    meter: {                    // Updated meter snapshot
      remaining: number;          // Always numeric; check `unlimited` for unbounded
      limit: number | null;
      used: number;               // 0 for unlimited meters
      unlimited: boolean;
      ratio: number | null;       // remaining/limit, null when unlimited
      label: string;
      periodUsageBefore: string;  // Exact interval volume before this event
      periodUsageAfter: string;   // Exact interval volume after this event
      overagePricingModel: "SINGLE" | "GRADUATED";
      overagePricingComponents: Array<{
        tierIndex: number;
        upTo: string | null;
        unitsExact: string;
        priceNanoUsd: string;
        priceQuantity: string;
      }>;
    };
    blocked: boolean;           // true if usage exceeds allocation and eligible overage funding
  },
  correlationId: string
}

Error Responses:

  • 400 BAD_REQUEST: Invalid meterSlot, missing customerId, or invalid amount
  • 409 CUSTOM_METER_CONFLICT: Concurrent update; retry with the same idempotency key
  • 404 SUBSCRIPTION_NOT_FOUND: No active subscription found
  • 400 METER_NOT_ENABLED: Custom meter not enabled on customer's plan

Example:

curl -X POST https://api.usagetap.com/custom_meter \
  -H "Authorization: Bearer ck-..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.usagetap.v1+json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerId": "cust_123",
    "customerUserId": "user_123",
    "meterSlot": "CUSTOM1",
    "amount": 5,
    "feature": "agent_actions",
    "tags": ["workflow_automation"],
    "metadata": {
      "workflowId": "wf_abc123",
      "actionType": "email_send"
    }
  }'

Use Cases:

Custom meters are ideal for tracking:

  • Agent actions or tool invocations
  • Document processing units
  • API calls to non-LLM services
  • Custom workflow steps
  • Any usage that doesn't fit standard LLM metrics

Important Notes:

  1. Custom meters must be enabled in the customer's usage plan
  2. Usage consumes the included allocation, then eligible purchased meter credits and/or PAYG credit according to the meter's funding configuration.
  3. Idempotency-Key is honored atomically with the subscription update. Reuse it only when retrying the same logical increment.
  4. Unfunded usage is recorded and returns HTTP 200 with data.blocked: true; the application must enforce the flag. The last included unit is allowed. LLM BLOCK/DOWNGRADE policies do not change this meter contract.
  5. PAYG overages require PAYG to be enabled and a valid single or graduated price. Settlement is asynchronous; this endpoint does not reserve dollar credit or enforce a rolling rate limit.
  6. Unlimited meters record usage events without consuming allocation or charging overages. Their remaining/used snapshot counters are informational; use event history for usage totals.
  7. Graduated rates are resolved and snapshotted when the event is recorded. Tier progress resets with the plan's replenishment interval; UsageTap's own meter-event pricing should use a monthly plan.

SDK API

The TypeScript/JavaScript SDK provides a high-level interface to the REST API.

Installation

# OpenAI/OpenRouter
npm install @usagetap/sdk openai

# Anthropic
npm install @usagetap/sdk @anthropic-ai/sdk

Initialization

import { UsageTapClient } from "@usagetap/sdk";

const client = new UsageTapClient({
  apiKey: process.env.USAGETAP_API_KEY!,
  baseUrl: process.env.USAGETAP_BASE_URL!,

  // Optional configuration
  defaultFeature?: string;          // Default feature name
  defaultTags?: string[];           // Default tags
  fetchImpl?: typeof fetch;         // Custom fetch implementation
  headers?: Record<string, string>; // Additional headers
  retries?: {
    maxAttempts?: number;           // Default: 3
    baseDelayMs?: number;           // Default: 250
    maxDelayMs?: number;            // Default: 5000
    jitterRatio?: number;           // Default: 0.2
  };
  idempotencyGenerator?: () => string; // Custom ID generator
  autoIdempotency?: boolean;        // Default: true
  onLog?: (entry) => void;          // Logging callback
  useApiKeyHeader?: boolean;        // Use x-api-key header
  allowBrowser?: boolean;           // Allow browser usage (testing only)
  tokenCompanyApiKey?: string;      // Optional remote prompt compression provider
  tokenCompanyEndpoint?: string;    // Optional compatible compression endpoint
  tokenCompanyModel?: string;       // Optional TTC model, default "bear-2"
  aggressiveness?: number;          // Optional compression aggressiveness, 0.0-1.0
  tokenCompanyAppId?: string;       // Optional TTC app identifier
  usageTapCompressionEndpoint?: string; // Optional single-text compression endpoint
  usageTapCompressionMessagesEndpoint?: string; // Optional message/request compression endpoint
});

Core Methods

beginCall(request, options?)

const response = await client.beginCall({
  customerId: "cust_123",
  feature: "chat.send",
  idempotencyKey: crypto.randomUUID(),
  requested: {
    standard: true,
    premium: true,
    search: true,
    reasoningLevel: "HIGH",
  },
  tags: ["production"],
});

console.log("Call ID:", response.data.callId);
console.log("Allowed:", response.data.allowed);

promptCompress(request, options?)

Optional local prompt compression for manual flows. Call it after beginCall and before your vendor request. beginCall does not compress prompts by itself.

const begin = await client.beginCall({
  customerId: "cust_123",
  feature: "chat.send",
  idempotencyKey: crypto.randomUUID(),
});

const compressed = await client.promptCompress({
  callId: begin.data.callId,
  text: "Your text here",
  provider: "usagetap",
  model: "bear-2",
  aggressiveness: 0.5,
});

const response = await openai.responses.create({
  model: "gpt-5.6-luna",
  input: compressed.compressedInput,
});

console.log("Approx tokens saved:", compressed.savedTokens);
console.log("Savings ratio:", compressed.tokenSavingsRatio);

promptCompress() compresses locally, sends only savings metadata to /compress_prompt, and returns compressedInput for your vendor request. It is fail-open: if local compression or metadata reporting fails, it returns the original input with zero savings so the vendor call can continue.

With provider: "usagetap", manual compression uses the single-text compatible endpoint and accepts scalar aggressiveness. OpenAI and Anthropic wrappers use the message/request endpoint and can pass per-role aggressiveness such as { user: 0.5, system: 0.5, tool: 0.5 }.

For OpenAI and Anthropic clients, wrapOpenAI() / wrapAnthropic() can compress automatically when enabled:

const ai = wrapOpenAI(openai, client, {
  defaultContext: { customerId: "cust_123", feature: "chat.send" },
  promptCompression: {
    provider: "heuristic",
    roles: { user: true, tool: true },
    minTokens: 500,
  },
});

Assistant messages are skipped by default. The wrappers record aggregate compression telemetry once per UsageTap call and expose totals on ai.promptCompression.

For custom pipelines, use client.compressPromptInput(input, options?) to get a PromptCompressionResult without recording telemetry, then call client.recordPromptCompression({ callId, promptCompression }) to persist precomputed savings metadata. Use protectPromptText(text) from @usagetap/sdk for exact spans that compatible compressors should not rewrite.

endCall(request, options?)

const response = await client.endCall({
  callId: "call_xyz789",
  modelUsed: "gpt-5.6-sol",
  inputTokens: 512,
  responseTokens: 256,
  reasoningTokens: 0,
  searches: 1,
});

console.log("Cost:", response.data.costUSD);
console.log("Metered:", response.data.metered);

withUsage(request, handler, options?)

const result = await client.withUsage(
  {
    customerId: "cust_123",
    feature: "chat.send",
    idempotencyKey: crypto.randomUUID(),
    requested: { standard: true, premium: true },
  },
  async ({ begin, setUsage, setError }) => {
    try {
      const model = begin.data.allowed.premium ? "gpt-5.6-sol" : "gpt-5.6-luna";

      const response = await openai.chat.completions.create({
        model,
        messages: [{ role: "user", content: "Hello" }],
      });

      setUsage({
        modelUsed: model,
        inputTokens: response.usage?.prompt_tokens ?? 0,
        responseTokens: response.usage?.completion_tokens ?? 0,
      });

      return response.choices[0].message.content;
    } catch (error) {
      setError({
        code: "VENDOR_ERROR",
        message: error instanceof Error ? error.message : String(error),
      });
      throw error;
    }
  },
);

createCustomer(request, options?)

const response = await client.createCustomer({
  customerId: "cust_123",
  customerFriendlyName: "Acme Corp",
  customerEmail: "billing@acme.com",
  stripeCustomerId: "cus_stripe123",
});

console.log("New customer?", response.data.newCustomer);
console.log("Plan:", response.data.subscription.planName);

checkUsage(request, options?)

const response = await client.checkUsage({
  customerId: "cust_123",
});

console.log("Meters:", response.data.meters);
console.log("Allowed:", response.data.allowed);

changePlan(request, options?)

const response = await client.changePlan({
  customerId: "cust_123",
  planId: "plan_premium_v2",
  strategy: "IMMEDIATE_RESET",
});

console.log("Success:", response.data.success);
console.log("New plan:", response.data.subscription.planName);

incrementCustomMeter(request, options?)

Track custom usage metrics beyond standard LLM counters.

const response = await client.incrementCustomMeter({
  customerId: "cust_123",
  meterSlot: "CUSTOM1",
  amount: 5,
  feature: "agent_actions",
  tags: ["workflow_automation"],
  metadata: {
    workflowId: "wf_abc123",
    actionType: "email_send",
  },
});

console.log("Event ID:", response.data.eventId);
console.log("Remaining:", response.data.meter.remaining);
console.log("Blocked:", response.data.blocked);

Parameters:

  • customerId (string, required): Customer identifier
  • meterSlot ("CUSTOM1" | "CUSTOM2" | "AGENTIC_API", required): Which meter to increment
  • amount (number, required): Positive number to decrement from quota
  • feature (string, optional): Feature identifier for tracking
  • tags (string[], optional): Tags for categorization
  • metadata (object, optional): Additional metadata

Returns: Updated meter snapshot with remaining, limit, used, unlimited, and label fields.

Throws:

  • UsageTapError with code USAGETAP_BAD_REQUEST for invalid parameters
  • Authentication or transport failures may throw. An accepted report with data.blocked: true does not throw; inspect the flag and enforce it in your application.

Use Cases:

// Track agent tool invocations
await client.incrementCustomMeter({
  customerId: "cust_123",
  meterSlot: "AGENTIC_API",
  amount: 1,
  feature: "agent.tool_call",
  tags: ["web_search"],
});

// Track document processing
await client.incrementCustomMeter({
  customerId: "cust_456",
  meterSlot: "CUSTOM2",
  amount: 10, // 10 pages processed
  feature: "document.ocr",
  metadata: { documentId: "doc_789", pages: 10 },
});

// Track HTTP API requests or MCP tool calls
await client.incrementCustomMeter({
  customerId: "cust_789",
  meterSlot: "AGENTIC_API",
  amount: 1,
  feature: "external_api.maps",
  tags: ["geocoding"],
});

OpenAI Integration

wrapOpenAI(client, usageTap, options)

import OpenAI from "openai";
import { wrapOpenAI } from "@usagetap/sdk/openai";

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY! });

const ai = wrapOpenAI(openai, client, {
  defaultContext: {
    customerId: "cust_123",
    feature: "chat.completions",
    requested: {
      standard: true,
      premium: true,
      search: true,
      reasoningLevel: "HIGH",
    },
  },
});

// Now use `ai` instead of `openai`
const completion = await ai.chat.completions.create(
  {
    messages: [{ role: "user", content: "Hello" }],
    // model is optional - selected based on entitlements
  },
  {
    usageTap: {
      idempotencyKey: crypto.randomUUID(),
    },
  },
);

Streaming Support

const stream = await ai.chat.completions.create(
  {
    messages: [{ role: "user", content: "Hello" }],
    stream: true,
  },
  {
    usageTap: {
      customerId: "cust_123",
      idempotencyKey: crypto.randomUUID(),
    },
  },
);

// Next.js
import { toNextResponse } from "@usagetap/sdk/openai";
return toNextResponse(stream, { mode: "text" });

// Express
import { pipeToResponse } from "@usagetap/sdk/openai";
pipeToResponse(stream, res);

Anthropic Integration

wrapAnthropic(client, usageTap, options)

import Anthropic from "@anthropic-ai/sdk";
import { wrapAnthropic } from "@usagetap/sdk/anthropic";

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });

const claude = wrapAnthropic(anthropic, client, {
  defaultContext: {
    customerId: "cust_123",
    feature: "chat.anthropic",
    requested: { standard: true, premium: true },
  },
  promptCompression: {
    roles: { system: true, user: true, tool: true },
  },
});

const message = await claude.messages.create({
  model: "claude-3-5-haiku-latest",
  max_tokens: 512,
  system: "Long system prompt",
  messages: [{ role: "user", content: "Long user prompt" }],
});

const stream = claude.messages.stream({
  model: "claude-sonnet-4-5",
  max_tokens: 512,
  messages: [{ role: "user", content: "Stream it" }],
});
stream.on("text", (text) => process.stdout.write(text));
const streamedMessage = await stream.finalMessage();

In @usagetap/sdk 1.6.0 and newer, wrapAnthropic() instruments messages.create() and the synchronous messages.stream() helper, applies UsageTap model hints when model is omitted, extracts Anthropic token and prompt-cache usage, and can compress system, user text blocks, and tool_result content before the vendor request. Wrapped create results retain .withResponse() and .asResponse(). messages.stream() preserves Anthropic's event handlers, async iterator, cancellation, and final-message helpers while UsageTap finalizes the call on completion, failure, or abort.

Express Middleware

import { withUsage } from "@usagetap/sdk/express";

app.use(withUsage(client, (req) => req.user?.id || "anonymous"));

app.post("/api/chat", async (req, res) => {
  const ai = req.usageTap!.openai(openai, {
    feature: "chat.assistant",
    requested: { standard: true, premium: true },
  });

  const stream = await ai.chat.completions.create({
    messages: req.body.messages,
    stream: true,
  });

  req.usageTap!.pipeToResponse(stream, res);
});

React Hook

import { useChatWithUsage } from "@usagetap/sdk/react";

function Chat({ userId }: { userId: string }) {
  const { messages, input, setInput, handleSubmit, isLoading } =
    useChatWithUsage({
      api: "/api/chat",
      customerId: userId,
      feature: "chat.assistant",
    });

  return (
    <div>
      {messages.map((m) => (
        <div key={m.id}>{m.content}</div>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={(e) => setInput(e.target.value)} />
        <button type="submit" disabled={isLoading}>
          Send
        </button>
      </form>
    </div>
  );
}

Type Definitions

ReasoningLevel

type ReasoningLevel = "NONE" | "LOW" | "MEDIUM" | "HIGH";

LimitType

type LimitType = "NONE" | "BLOCK" | "DOWNGRADE";

RequestedEntitlements

interface RequestedEntitlements {
  standard?: boolean;
  premium?: boolean;
  audio?: boolean;
  image?: boolean;
  search?: boolean;
  reasoningLevel?: ReasoningLevel;
}

AllowedEntitlements

type AllowedEntitlements = Required<RequestedEntitlements>;

MeterSummary

interface MeterSummary {
  remaining: number; // Always numeric (0 when exhausted; the `unlimited` flag is authoritative)
  limit: number | null; // Null when plan does not specify a limit for this meter
  used: number;
  unlimited: boolean; // true = this meter is unbounded; remaining is informational only
  ratio: number | null; // remaining/limit (0-1), null when unlimited or limit is null/0
}

Breaking change (v2026-02): remaining is now always a number. Previously null meant "unlimited"; that semantic has moved to the explicit unlimited boolean flag. Consumers that tested remaining === null to detect unlimited meters must switch to checking unlimited === true.

SubscriptionSnapshot

interface SubscriptionSnapshot {
  id: string;
  usagePlanVersionId: string;
  planName: string;
  planVersion: string;
  limitType: LimitType;
  reasoningLevel: ReasoningLevel;
  lastReplenishedAt: string; // ISO 8601
  nextReplenishAt: string; // ISO 8601
  subscriptionVersion: number;
  customerFriendlyName?: string;
  customerEmail?: string;
  stripeCustomerId?: string;
  pending?: {
    usagePlanVersionId: string;
    strategy: string;
    effectiveAt: string;
  };
}

EntitlementHints

interface EntitlementHints {
  suggestedModelTier: "premium" | "standard" | "none";
  reasoningLevel: ReasoningLevel;
  policy: LimitType;
  downgrade?: {
    reason: string;
    fallbackTier?: "premium" | "standard" | "none";
  };
}

IdempotencyMetadata

interface IdempotencyMetadata {
  key: string; // Always matches callId
  source: "explicit" | "derived";
}

Error Codes

SDK Error Codes

Code Description Retryable
USAGETAP_AUTH_ERROR Invalid API key or unauthorized No
USAGETAP_BAD_REQUEST Invalid request parameters No
USAGETAP_RATE_LIMITED Too many requests Yes
USAGETAP_SERVER_ERROR Server-side error Yes
USAGETAP_NETWORK_ERROR Network failure Yes
USAGETAP_INVALID_RESPONSE Unexpected response format No
USAGETAP_END_CALL_ERROR Failed to finalize call No
USAGETAP_BROWSER_RUNTIME SDK used in browser without allowBrowser No

API Result Codes

Code Status Description
CALL_BEGIN_SUCCESS ACCEPTED Call started successfully
CALL_END_SUCCESS ACCEPTED Call ended successfully
CALL_SUCCESS ACCEPTED Unified /call succeeded
CALL_VENDOR_WARNING ACCEPTED /call succeeded but vendor returned error
CUSTOMER_READY ACCEPTED Customer subscription ready
PLAN_CHANGED ACCEPTED Plan change successful

HTTP Status Codes

Status Meaning Retryable
200 Success N/A
400 Bad Request (invalid parameters) No
401 Unauthorized (invalid API key) No
403 Forbidden No
404 Not Found No
406 Not Acceptable (missing Accept header) No
409 Conflict (idempotency key mismatch) No
429 Rate Limited Yes
500 Internal Server Error Yes
502 Bad Gateway Yes
503 Service Unavailable Yes
504 Gateway Timeout Yes

Examples

Complete Node.js Script

import OpenAI from "openai";
import { UsageTapClient } from "@usagetap/sdk";
import crypto from "crypto";

const usageTap = new UsageTapClient({
  apiKey: process.env.USAGETAP_API_KEY!,
  baseUrl: process.env.USAGETAP_BASE_URL!,
});

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY!,
});

async function chat(userId: string, message: string) {
  return usageTap.withUsage(
    {
      customerId: userId,
      feature: "chat.send",
      idempotencyKey: crypto.randomUUID(),
      requested: {
        standard: true,
        premium: true,
        search: true,
        reasoningLevel: "MEDIUM",
      },
    },
    async ({ begin, setUsage }) => {
      // Select model based on entitlements
      const model = begin.data.allowed.premium ? "gpt-5.6-sol" : "gpt-5.6-luna";

      // Add search tool if allowed
      const tools = begin.data.allowed.search
        ? [{ type: "web_search" as const }]
        : undefined;

      const response = await openai.chat.completions.create({
        model,
        messages: [{ role: "user", content: message }],
        tools,
      });

      setUsage({
        modelUsed: model,
        inputTokens: response.usage?.prompt_tokens ?? 0,
        responseTokens: response.usage?.completion_tokens ?? 0,
        searches: tools ? (response.usage?.web_search_queries ?? 0) : 0,
      });

      return response.choices[0].message.content;
    },
  );
}

chat("user_123", "What's new in AI today?")
  .then((response) => console.log("Response:", response))
  .catch((error) => console.error("Error:", error));

Raw HTTP Request

const response = await fetch("https://api.usagetap.com/call", {
  method: "POST",
  headers: {
    Authorization: "Bearer ck-...",
    "Content-Type": "application/json",
    Accept: "application/vnd.usagetap.v1+json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    customerId: "cust_123",
    feature: "chat.completions",
    requested: {
      standard: true,
      premium: true,
    },
    vendor: {
      url: "https://api.openai.com/v1/chat/completions",
      method: "POST",
      headers: {
        Authorization: "Bearer sk-...",
        "Content-Type": "application/json",
      },
      body: {
        model: "gpt-5.6-luna",
        messages: [{ role: "user", content: "Hello" }],
      },
      responseType: "json",
    },
    usage: {
      modelUsed: "gpt-5.6-luna",
    },
  }),
});

const result = await response.json();
console.log("Result:", result.data);

Support


Last Updated: July 29, 2026 API Version: v1 SDK Version: 1.4.0

Subscription quantity and pooled usage

A customer subscription has an active quantity (default 1) and optional pendingQuantity. Included LLM, API / Agentic Calls, and custom-meter allowances, plus recurring included PAYG dollar credit, scale by active quantity. All users report the same account customerId; customerUserId attributes individual consumption. Actual usage, purchased credits, top-ups, signup credit, prices, markup, minimum credit, and rolling rate limits do not multiply. Graduated custom-meter usage boundaries scale with the plan bundle; rates remain unchanged.

Supply an optional positive integer quantity to POST /customers when creating a customer. Creation grants the pooled allowance immediately. Calling creation for an existing customer does not change its quantity.

Use POST /customers/{customerId}/quantity to edit quantity, with JSON { "quantity": 10 }. Requires customers:write; accepts the Idempotency-Key header. Quantity must be a whole number from 1 to 2,147,483,647, and resulting allowances must fit a safe integer. The response envelope contains data.success, data.subscription.quantity, data.subscription.pendingQuantity, and data.effectiveAt. Edits apply at the next replenishment, including an explicitly requested manual replenishment. A null effective date means no automatic replenishment is scheduled. Setting the active quantity cancels a pending edit. Current usage and purchased balances are preserved.

Usage checks and widgets read active quantity from the subscription; callers do not pass a multiplier on usage requests. Customer details exposes the same deferred edit. These edits affect UsageTap allowances and do not change the external billing subscription.

Stripe subscription sync derives quantity from the mapped licensed subscription item, excluding metered add-ons. Multiple mapped licensed items are rejected as ambiguous. Quantity-only updates are processed even when the plan is unchanged, using the same deferred policy. New subscriptions receive their initial quantity immediately. Cancellation restores quantity 1 and clears any scheduled quantity when returning to the default plan, while preserving purchased balances. With a configured subscription API key, sync retrieves current Stripe state to reconcile delayed webhook snapshots; the key needs Subscriptions: Read permission. Without an API key, sync uses the signed webhook snapshot. If an existing restricted key lacks that read permission, sync also falls back to the signed snapshot and records a permission warning; transient lookup failures remain retryable. Stripe sync can replace a manual pending quantity, so edit seat count in Stripe when Stripe owns billing. Stripe test-mode events retain the existing log-only behavior.