> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nozle.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Send metered usage events from a trusted backend

Use the Node.js or Python SDK for event ingestion. The SDK sends one event per `track()` call; it does not batch automatically.

<Info>
  See [Node.js event tracking](/sdks/node/tracking-events) or [Python event tracking](/sdks/python/tracking-events) for subscription resolution and idempotency behavior.
</Info>

## Event envelope

```json theme={null}
{
  "event": {
    "transaction_id": "request_0183f",
    "external_customer_id": "customer_123",
    "external_subscription_id": "subscription_123",
    "code": "api_calls",
    "properties": {
      "model": "example-model",
      "tokens": 1500
    },
    "timestamp": "2026-08-04T10:30:00Z"
  }
}
```

| Field                      | Required    | Description                                                                              |
| -------------------------- | ----------- | ---------------------------------------------------------------------------------------- |
| `transaction_id`           | yes         | Stable identifier for the logical event. Preserve it with the same timestamp on retries. |
| `external_customer_id`     | yes         | Customer that generated usage.                                                           |
| `external_subscription_id` | recommended | Subscription receiving usage. Required when resolution would be ambiguous.               |
| `code`                     | yes         | Feature code.                                                                            |
| `properties`               | no          | Aggregation and attribution metadata.                                                    |
| `timestamp`                | no          | ISO 8601 occurrence time.                                                                |

For direct HTTP ingestion, send this envelope to the Events API configured for your organization with a secret key. Prefer the SDKs so subscription lookup, UUID generation, timeout handling, and errors remain consistent.

<Note>
  For retry safety, preserve the complete event identity. High-volume event storage deduplicates using both `transaction_id` and `timestamp`.
</Note>