---
title: "Record an execution event"
method: POST
path: "/v1/events"
tags: ["Events"]
---

# Record an execution event

`POST /v1/events`

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.**

## Request body

- object
  - `customerId` string — Drip customer ID (cus_*). Either customerId or externalCustomerId is required.
  - `externalCustomerId` string — 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.
  - `idempotencyKey` string, required — Unique key (same key = same result)
  - `actionName` string — 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
  - `explanation` string — Human-readable note
  - `metadata` object — Any extra data you want to attach
  - `quantity` number — For billing: how many units
  - `usageType` string — Usage type for billing (matches pricing plan)
  - `units` string — Human-readable unit label (e.g., "tokens", "API calls")
  - `description` string — 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
  - `runId` string — Group events into a run
  - `parentEventId` string — Link to parent event
  - `correlationId` string — Cross-service tracing ID
  - `inputHash` string — SHA-256 hash of input
  - `outputHash` string — SHA-256 hash of output
  - `input` object — Raw input (will be hashed)
  - `output` object — Raw output (will be hashed)
  - `workflowId` string — Link to a workflow
  - `retryOfEventId` string — ID of event being retried
  - `attemptNumber` integer — Attempt number (1 = first try)
  - `spanId` string — Span ID for distributed tracing
  - `spanKind` 'TOOL' | 'LLM' | 'CHAIN' | 'AGENT' | 'RETRIEVER' | 'EMBEDDING' | 'INTERNAL' — OpenTelemetry-inspired span classification
  - `inputBytes` integer — Input size in bytes
  - `outputBytes` integer — Output size in bytes
  - `queueDurationMs` integer — Time spent in queue (ms)
  - `executionDurationMs` integer — Execution time (ms)
  - `startedAt` string, date-time — When execution started
  - `endedAt` string, date-time — When execution ended
  - `errorType` string — Error class/type
  - `errorMessage` string — Error message
  - `errorStack` string — Stack trace
  - `retryCount` integer — Number of retries so far
  - `retryBackoffMs` integer — Backoff time before next retry (ms)
  - `retryReason` string — Why the retry was triggered
  - `storePayloads` boolean — Controls payload storage. Defaults to true when input/output are provided. Set to false to explicitly disable.
  - `payloadTtlSeconds` integer — TTL for stored payloads in seconds (default: 90 days)

## Response `201`

Event created successfully

- object — Event created successfully
  - `id` string — 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'
  - `actionName` string
  - `outcome` 'PENDING' | 'SUCCEEDED' | 'FAILED' | 'SKIPPED' | 'RETRIED' | 'TIMEOUT' | 'CANCELLED'
  - `idempotencyKey` string
  - `createdAt` string, date-time
  - `wasIdempotentReplay` boolean — True if this was a duplicate request
  - `receipt` object — Signed receipt proving Drip acknowledged this event
    - `batchId` string — Idempotency key for this submission
    - `eventCount` integer — Number of events (1 for single event)
    - `batchHash` string — SHA-256 hash of the event data
    - `receivedAt` string, date-time — When Drip received the event
    - `signature` string — Server signature of the receipt
    - `signerAddress` string — Address that signed the receipt

## Other responses

- `400` — Validation error
- `401` — Unauthorized
- `404` — Customer or referenced event not found
- `429` — Rate limit exceeded
- `503` — Service temporarily unavailable — retry with backoff

---

[API](https://skmtc.net/usedrip/apis/drip-api.md) · [All operations](https://skmtc.net/usedrip/apis/drip-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/usedrip/drip-api/revisions/2cb1567969ca/schema)