Sign in

v1

latestOpenAPI 3.1.02026-08-042453938.9 KB
Usage

Record internal usage (batched, high throughput)

Batch-optimized variant of POST /v1/usage/internal.

Events are buffered in memory and flushed to the database every ~2 seconds using a single bulk INSERT. This reduces per-event DB overhead by ~99% and is designed for customers sending 1M+ events/day.

Returns 202 immediately. The event will be persisted within 2 seconds. Idempotency is still enforced via idempotencyKey — duplicates are silently skipped during the bulk insert.

Requires a secret key (sk_*) with at least the OPERATOR role.

post/v1/usage/internal/batch

Request body

customerIdstring

Drip customer ID (cus_*). One of customerId, externalCustomerId, or stripeCustomerId is required.

externalCustomerIdstring

Your own database's customer ID. If no Drip customer exists yet for (business, externalCustomerId), one is auto-provisioned as an internal customer on first use.

stripeCustomerIdstring

Stripe customer ID (cus_…) from your connected Stripe account. If no Drip customer exists yet for (business, stripeCustomerId), one is auto-provisioned and usage is forwarded to Stripe's Billing Meter Events. Intended for merchants who just finished Stripe OAuth, so you can start sending usage against Stripe IDs immediately without waiting for the background customer import.

usageTypestring

Usage type matching a pricing plan (defaults to "generic" if omitted)

quantitynumber

Quantity of usage (defaults to 1 if omitted)

unitsstring

Human-readable unit label for display (e.g., "tokens", "API calls", "seconds")

descriptionstring

Human-readable description for support/finance teams (e.g., "Chat completion for Customer XYZ")

idempotencyKeystring required

Unique key to prevent duplicate charges. Required. Use a stable identifier like {customerId}_{action}_{timestamp} so retries produce the same key.

metadataobject

Optional metadata

workflowIdstring

Link this usage to a workflow

runIdstring

Link this usage to an agent run

eventType'USAGE' | 'INFERENCE' | 'TOOL_CALL' | 'DELEGATION' | 'RETRIEVAL' | 'CUSTOM'

Classify the type of usage event

actionNamestring

Name of the action performed (e.g., "chat_completion", "image_generation")

outcome'SUCCEEDED' | 'FAILED' | 'PENDING' | 'SKIPPED' | 'CANCELLED'

Outcome of the action

explanationstring

Human-readable explanation of what happened

parentEventIdstring

ID of the parent event (for building causality trees)

retryOfEventIdstring

ID of the event this is retrying (for retry chain tracking)

attemptNumberinteger

Attempt number (1 = first try, 2 = first retry, etc.)

inputHashstring

SHA-256 hash of the input for verification

outputHashstring

SHA-256 hash of the output for verification

inputobject

Raw input data (will be hashed for verification)

outputobject

Raw output data (will be hashed for verification)

Example request

{
  "customerId": "cus_abc123def456",
  "externalCustomerId": "user_42",
  "stripeCustomerId": "cus_NffrFeUfNV2Hib",
  "usageType": "api_call",
  "quantity": 100,
  "units": "API calls",
  "description": "Eligibility check for Pharmacy ABC (workflow: insurance_verify)",
  "idempotencyKey": "req_20240115_abc123",
  "metadata": {
    "endpoint": "/v1/chat",
    "model": "gpt-4"
  }
}

Response

Usage accepted for batched insert

successboolean
customerIdstring
usageTypestring
quantitynumber
idempotencyKeystring
pendingEventsinteger

Number of events waiting to be flushed

messagestring

Example response

{
  "success": true,
  "message": "Event queued for batched insert (~2s)"
}