Sign in

v1

latestOpenAPI 3.1.02026-08-042453938.9 KB
Events

Record an execution event

Record what happened. Only 2 fields required: customerId and idempotencyKey.

All other fields are optional with smart defaults. If you provide input or output payloads, they are automatically stored for later retrieval via GET /events/:id/payload (no need to set storePayloads: true).

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

post/v1/events

Request body

customerIdstring

Drip customer ID (cus_*). Either customerId or externalCustomerId 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. Either customerId or externalCustomerId is required.

idempotencyKeystring required

Unique key (same key = same result)

actionNamestring

What action was performed (defaults to eventType name if omitted)

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

SUCCEEDED, FAILED, PENDING, SKIPPED, RETRIED, TIMEOUT, CANCELLED

explanationstring

Human-readable note

metadataobject

Any extra data you want to attach

quantitynumber

For billing: how many units

usageTypestring

Usage type for billing (matches pricing plan)

unitsstring

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

descriptionstring

Description for support/finance

eventType'USAGE' | 'API_CALL' | 'LLM_INFERENCE' | 'TOOL_CALL' | 'DATABASE' | 'FILE_IO' | 'NETWORK' | 'DECISION' | 'HUMAN_IN_LOOP' | 'MEMORY' | 'CUSTOM' | 'TOOL_CALL_START' | 'TOOL_CALL_END' | 'TOOL_CALL_ERROR' | 'TOOL_CALL_RETRY' | 'TRAINING' | 'FINE_TUNING'

Event category

runIdstring

Group events into a run

parentEventIdstring

Link to parent event

correlationIdstring

Cross-service tracing ID

inputHashstring

SHA-256 hash of input

outputHashstring

SHA-256 hash of output

inputobject

Raw input (will be hashed)

outputobject

Raw output (will be hashed)

workflowIdstring

Link to a workflow

retryOfEventIdstring

ID of event being retried

attemptNumberinteger

Attempt number (1 = first try)

spanIdstring

Span ID for distributed tracing

spanKind'TOOL' | 'LLM' | 'CHAIN' | 'AGENT' | 'RETRIEVER' | 'EMBEDDING' | 'INTERNAL'

OpenTelemetry-inspired span classification

inputBytesinteger

Input size in bytes

outputBytesinteger

Output size in bytes

queueDurationMsinteger

Time spent in queue (ms)

executionDurationMsinteger

Execution time (ms)

startedAtstring date-time

When execution started

endedAtstring date-time

When execution ended

errorTypestring

Error class/type

errorMessagestring

Error message

errorStackstring

Stack trace

retryCountinteger

Number of retries so far

retryBackoffMsinteger

Backoff time before next retry (ms)

retryReasonstring

Why the retry was triggered

storePayloadsboolean

Controls payload storage. Defaults to true when input/output are provided. Set to false to explicitly disable.

payloadTtlSecondsinteger

TTL for stored payloads in seconds (default: 90 days)

Example request

{
  "customerId": "cus_abc123",
  "externalCustomerId": "user_42",
  "idempotencyKey": "req_123",
  "actionName": "api_call",
  "outcome": "SUCCEEDED",
  "explanation": "Processed request successfully",
  "quantity": 100,
  "eventType": "API_CALL"
}

Response

Event created successfully

idstring

Event ID

eventType'USAGE' | 'API_CALL' | 'LLM_INFERENCE' | 'TOOL_CALL' | 'DATABASE' | 'FILE_IO' | 'NETWORK' | 'DECISION' | 'HUMAN_IN_LOOP' | 'MEMORY' | 'CUSTOM' | 'TOOL_CALL_START' | 'TOOL_CALL_END' | 'TOOL_CALL_ERROR' | 'TOOL_CALL_RETRY' | 'TRAINING' | 'FINE_TUNING'
actionNamestring
outcome'PENDING' | 'SUCCEEDED' | 'FAILED' | 'SKIPPED' | 'RETRIED' | 'TIMEOUT' | 'CANCELLED'
idempotencyKeystring
createdAtstring date-time
wasIdempotentReplayboolean

True if this was a duplicate request