An event is a name, a customer and whatever metadata you want to bill on. Post it from your application and every meter can read it.
Every event starts with a name that says what happened, such as ai_usage, video_streamed or file_uploaded. Meters use it to pick the events they care about.
It carries a customer, given as the Polar customer ID or the ID you already use for that user in your own database. No mapping table to keep in sync.
The rest is metadata, a JSON object with anything worth filtering or summing later. Tokens in and out, the model, seconds of compute, bytes stored.
That is the whole contract. You describe what happened once, and the pricing decisions stay on the Polar side where you can change them without touching your code.
Post a batch of events through the SDK or the Events Ingestion API.
Attribute usage with the external ID your application already has.
Once an event is ingested it cannot be changed or deleted.
Set a timestamp in the past for batched ingestion or replays from your queue.
The ingestion SDK wraps the most common event sources, so the events fire without you writing the plumbing.
Wrap a model from the AI SDK. Prompt and completion tokens are reported for every model call.
Wrap any readable or writable stream and the bytes it consumes are reported as they flow.
Wrap the AWS S3 client and every byte uploaded is reported for you.
Measure how long any piece of execution takes and report the duration.
When no strategy fits, post events directly through the SDK or the API.
Ingestion follows a few fixed rules, so the number on the invoice is always one you can explain.
The record of what a customer used is append-only, so a past invoice can always be traced back to its events.
Events are billed in the period Polar receives them. Closed invoices are never reopened.
The timestamp you supply places the event on the usage charts and sets the date range on the invoice line.
Polar always accepts the event. Whether to enforce a limit is a decision for your product.
Install the SDK and ingest an event in a few lines.