UsageTap API Reference
Complete reference for the UsageTap REST API and SDK.
Table of Contents
- Authentication
- Organization privacy
- Gateway request limits
- Request Headers
- Response Format
- Idempotency
- REST API Endpoints
- GET /v1/model-alternatives/{modelKey}
- POST /call_begin
- GET /sampling/settings
- POST /sampling/decide
- POST /samples
- POST /compress_prompt
- POST /call_end
- POST /call
- GET /calls/{callId}
- POST /customers
- GET /customers/{customerId}/usage
- GET /customers/{customerId}/usage-context
- GET /customers/{customerId}/forecast
- GET /usage/monitoring and exact task lookup
- POST /customers/{customerId}/change_plan
- POST /custom_meter
- SDK API
- Type Definitions
- Error Codes
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.
Option 1: Bearer Token (Recommended)
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 }
}
2. Request Body (Recommended Field: idempotencyKey)
{
"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
callIdand 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.requiredScopenames 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_beginbehaves 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.5for batch or1for 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:
/callchecks the requested tier'sdata.allowedflag before provider work or finalization (requested.premium: trueselects premium; otherwise standard). If it is false,/callreturns thecall_beginHTTP 200 accepted envelope directly, including itsdata.callId,data.allowed, and available rate-limit evidence. This response has no compounddata.begin,data.end,data.vendor, ordata.endUsage. Neither the provider nor/call_endis 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.
/callreturns that begin decision for application-controlled model selection; it does not rewrite the vendor request or finalize the fallback. - If
vendoris provided, UsageTap makes the HTTP call and extracts usage - If
vendoris omitted, onlyusageoverrides are recorded - Non-2xx vendor responses still trigger
call_endwith 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, defaultUTCforecastMetric(optional):calls,inputTokens,outputTokens,allTokens,dollars,agenticApi,customMeter1, orcustomMeter2includeForecast(optional):trueby defaultincludeSignals(optional):trueby 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 abovetimezone(optional): IANA timezone, defaultUTC
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 nocustomerIdidentifies pooled evidence. Existing customer scopes retaincustomerIdand may omitlevel.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, andexpectedAllocationFractioninside the composition evidence: recorded allocation and its observed/expected window consumption, or null when unavailable. These are not remaining balances.consumptionStatusandallowanceStatus: 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.contributionCoverageiscomplete,partial, orchanged. 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, ordata_delayed. This describes quantity evidence, separately from the parent incident's confirmation/status.consumedCalls,expectedCalls,excessCalls,callsPerMinute,expectedCallsPerMinute, andrateMultiple(null when unavailable).reportingEvents,baselineWindows, andbaselineReportingEventspreserve the distinction between consumption and reporting batches.elevatedWindowsand at most threerecentWindows, each withwindowStart,state(elevated,within_range, orunknown),consumedCalls, andexpectedCalls. Persistence is quantity-specific and cadence-specific.features: up to five available feature contributions withfeature,bucket,consumedCalls,expectedCalls(baseline mean), andcallShare.featureMixChanged,reportingPatternChanged, andtaskAttributionFraction(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 cycleIMMEDIATE_PRORATED: Switch immediately, preserve usage already consumed, adjust remaining allowances to the target limits, and keep the current replenishment dateAT_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+jsonContent-Type: application/jsonIdempotency-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 amount409 CUSTOM_METER_CONFLICT: Concurrent update; retry with the same idempotency key404 SUBSCRIPTION_NOT_FOUND: No active subscription found400 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:
- Custom meters must be enabled in the customer's usage plan
- Usage consumes the included allocation, then eligible purchased meter credits and/or PAYG credit according to the meter's funding configuration.
Idempotency-Keyis honored atomically with the subscription update. Reuse it only when retrying the same logical increment.- Unfunded usage is recorded and returns HTTP 200 with
data.blocked: true; the application must enforce the flag. The last included unit is allowed. LLMBLOCK/DOWNGRADEpolicies do not change this meter contract. - 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.
- Unlimited meters record usage events without consuming allocation or charging overages. Their remaining/used snapshot counters are informational; use event history for usage totals.
- 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 identifiermeterSlot("CUSTOM1" | "CUSTOM2" | "AGENTIC_API", required): Which meter to incrementamount(number, required): Positive number to decrement from quotafeature(string, optional): Feature identifier for trackingtags(string[], optional): Tags for categorizationmetadata(object, optional): Additional metadata
Returns: Updated meter snapshot with remaining, limit, used, unlimited, and label fields.
Throws:
UsageTapErrorwith codeUSAGETAP_BAD_REQUESTfor invalid parameters- Authentication or transport failures may throw. An accepted report with
data.blocked: truedoes 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):
remainingis now always a number. Previouslynullmeant "unlimited"; that semantic has moved to the explicitunlimitedboolean flag. Consumers that testedremaining === nullto detect unlimited meters must switch to checkingunlimited === 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
- Documentation: https://usagetap.com/docs
- API Status: https://status.usagetap.com
- GitHub: https://github.com/usagetap/sdk
- Email: support@usagetap.com
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.