***

title: Usage Events
subtitle: Report metered usage for usage-based billing
slug: endpoints/usage-events
---------------------

For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.prolifi.io/endpoints/llms.txt. For full documentation content, see https://docs.prolifi.io/endpoints/llms-full.txt.

Usage events are how your application reports metered consumption to Prolifi. Events are aggregated per billing period to calculate usage-based charges on invoices.

## Endpoints

| Method | Path                    | Description                              |
| ------ | ----------------------- | ---------------------------------------- |
| `POST` | `/events`               | Report a single usage event              |
| `POST` | `/events/batch`         | Report up to 1,000 events in one request |
| `GET`  | `/customers/{id}/usage` | Get a customer's usage summary           |

## Key concepts

* **Event definitions**: Before reporting events, configure usage event definitions in the Prolifi dashboard. The `event_name` in your API call must match an active definition.
* **Properties**: Attach custom key-value properties to events for segmentation and filtering (e.g., `endpoint`, `model`, `region`). If no properties are provided, a default `count: 1` property is added.
* **Batch reporting**: For high-volume integrations, use the batch endpoint to send up to 1,000 events per request. Each event is processed independently — the response shows accepted and rejected counts.
* **Idempotency**: Include an `idempotency_key` on usage events to prevent double-counting during retries. This is separate from the `Idempotency-Key` header (which applies to the HTTP request level).
* **Usage summaries**: The customer usage endpoint returns aggregated counts grouped by event type, useful for dashboards and quota displays.