Usage Events
Usage events are the raw facts Open Spanner stores before aggregation.
A usage event is one fact about product usage: a subject used a meter at a time, with a quantity and metadata that matches the meter's dimension schema.
Send usage from backend services or workers. The dashboard is meant for inspecting and querying usage, not for manually creating production usage events.
Event Shape
{
"subject": "org_123",
"meter": "api_requests",
"quantity": 1,
"idempotency_key": "usage_001",
"metadata": {
"region": "us-east",
"plan": "pro"
}
}| Field | Purpose |
|---|---|
subject | Customer, organization, user, or account being measured. |
meter | Meter name this event belongs to. |
quantity | Amount of usage recorded. |
idempotency_key | Unique key used to make retries safe. |
timestamp | Event time. Defaults depend on the API request if omitted. |
metadata | Dimension values for filtering and grouping. Must match the meter's configured dimensions when they are defined. |
Idempotency
Every usage event should include an idempotency_key. This lets clients safely retry writes without double-counting usage.
Bulk Ingestion
Use POST /v1/usages/bulk when clients report batches. Bulk ingestion keeps high-volume reporting efficient while preserving per-event validation.
Create an API key in the dashboard and pass it into the SDK client that reports usage.
Retention
Raw events can be pruned by meter retention policy. Aggregated query results are calculated from retained events, so set retention based on your audit and billing needs.