> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.prolifi.io/endpoints/usage-events/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.prolifi.io/_mcp/server.

# Usage Events

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.

> Report metered usage for usage-based billing


## API Docs

- Usage Events [Report a usage event](https://docs.prolifi.io/endpoints/usage-events/report-usage-event.md)
- Usage Events [Batch report usage events](https://docs.prolifi.io/endpoints/usage-events/batch-report-usage-events.md)
- Usage Events [Get customer usage summary](https://docs.prolifi.io/endpoints/usage-events/get-customer-usage.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://docs.prolifi.io/endpoints/usage-events/openapi.json)
- [OpenAPI YAML](https://docs.prolifi.io/endpoints/usage-events/openapi.yaml)