Overview
Events track customer usage for metered billing. Send events to Polar as they occur, and they’ll be aggregated by meters and billed accordingly.
The Event Object
When the event occurred (ISO 8601)
Event properties (key-value pairs)
Ingest Events
curl -X POST "https://api.polar.sh/v1/events/ingest" \
-H "Authorization: Bearer polar_pat_..." \
-H "Content-Type: application/json" \
-d '{
"events": [
{
"name": "api_request",
"customer_id": "cust_123",
"timestamp": "2024-01-15T10:30:00Z",
"properties": {
"endpoint": "/api/v1/users",
"response_time_ms": 150
}
}
]
}'
Events are processed asynchronously. They’ll be available for querying within a few seconds.
Request Body
Array of events to ingest (max 100 per request)
Event name (alphanumeric, underscores, dots)
Customer ID (use this OR external_customer_id)
Your external customer ID
Event timestamp (ISO 8601)
Event properties. Use consistent types for each property name.
Unique key to prevent duplicate ingestion
Response
Number of events successfully ingested
Array of errors for failed events
List Events
curl -X GET "https://api.polar.sh/v1/events" \
-H "Authorization: Bearer polar_pat_..."
Query Parameters
Filter by external customer ID
Filter events matching a meter’s filter
JSON filter clause (same format as meter filters)
Filter events after this timestamp
Filter events before this timestamp
Get Event
curl -X GET "https://api.polar.sh/v1/events/{id}" \
-H "Authorization: Bearer polar_pat_..."
Path Parameters
Get Event Statistics
curl -X GET "https://api.polar.sh/v1/events/statistics" \
-H "Authorization: Bearer polar_pat_..." \
-H "Content-Type: application/json"
Query Parameters
Time interval: hour, day, week, or month
Aggregate events for specific meter
Aggregation function: count, sum, avg, min, or max
Property to aggregate (for sum/avg/min/max)
Response
Returns time series data:
[
{
"timestamp": "2024-01-15T00:00:00Z",
"value": 1234
},
{
"timestamp": "2024-01-16T00:00:00Z",
"value": 2345
}
]
Examples
Ingest Single Event
curl -X POST "https://api.polar.sh/v1/events/ingest" \
-H "Authorization: Bearer polar_pat_..." \
-H "Content-Type: application/json" \
-d '{
"events": [
{
"name": "api_request",
"external_customer_id": "user_123",
"timestamp": "2024-01-15T10:30:00Z",
"properties": {
"method": "POST",
"endpoint": "/api/v1/data",
"bytes_sent": 2048
},
"idempotency_key": "req_abc123"
}
]
}'
Ingest Batch of Events
curl -X POST "https://api.polar.sh/v1/events/ingest" \
-H "Authorization: Bearer polar_pat_..." \
-H "Content-Type: application/json" \
-d '{
"events": [
{
"name": "api_request",
"customer_id": "cust_123",
"timestamp": "2024-01-15T10:30:00Z",
"properties": {"endpoint": "/api/users", "count": 1}
},
{
"name": "api_request",
"customer_id": "cust_123",
"timestamp": "2024-01-15T10:31:00Z",
"properties": {"endpoint": "/api/posts", "count": 1}
},
{
"name": "data_processed",
"customer_id": "cust_123",
"timestamp": "2024-01-15T10:32:00Z",
"properties": {"bytes": 10485760, "rows": 5000}
}
]
}'
Query Events for Customer
curl -X GET "https://api.polar.sh/v1/events?customer_id=cust_123&start_timestamp=2024-01-01T00:00:00Z&end_timestamp=2024-01-31T23:59:59Z" \
-H "Authorization: Bearer polar_pat_..."
Get Daily Statistics
curl -X GET "https://api.polar.sh/v1/events/statistics?organization_id=org_123&start_timestamp=2024-01-01T00:00:00Z&end_timestamp=2024-01-31T23:59:59Z&interval=day&aggregation=count" \
-H "Authorization: Bearer polar_pat_..."