Sign in

v1

latestOpenAPI 3.1.02026-08-042453938.9 KB
Usage

Record internal usage (no billing)

Record a usage event for internal visibility tracking only. No billing or charges are created.

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

Use cases:

  • Track internal team usage without charging
  • Pilot programs where you want visibility before billing
  • Usage tracking before customer has on-chain wallet setup

This endpoint:

  • Does NOT create a Charge record
  • Does NOT require customer balance
  • Does NOT require blockchain/wallet setup for internal customers
  • Works with both internal and regular customers

For billing customers, use POST /v1/usage or POST /v1/usage/async instead.

post/v1/usage/internal

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

Internal usage recorded

successboolean
usageEventIdstring

Usage event ID

customerIdstring

Customer ID

usageTypestring

Type of usage

quantitynumber

Quantity recorded

unitsstring nullable

Human-readable unit label

descriptionstring nullable

Human-readable event description

isInternalboolean

Whether customer is internal-only

messagestring

Example response

{
  "success": true,
  "message": "Usage recorded for internal visibility (no charge created)"
}