Getting Started
Query Your First Usage
Read bucketed usage for a subject and meter.
Usage queries apply the meter's aggregation to time buckets. This example reads
daily api_requests totals for one subject.
curl "http://localhost:18081/v1/usages?subject=org_123&meter=api_requests&from=2026-06-01T00:00:00Z&to=2026-06-10T00:00:00Z&bucket_size=day" \
-H "Authorization: Bearer $OPEN_SPANNER_API_KEY"Each result identifies its bucket window and aggregated quantity. Empty windows are omitted rather than returned as zero-valued rows.
Use group_by=subject to return a row per subject. Use repeated group_by
parameters for meter dimensions:
curl "http://localhost:18081/v1/usages?meter=api_requests&from=2026-06-01T00:00:00Z&to=2026-06-10T00:00:00Z&bucket_size=day&group_by=subject&group_by=region" \
-H "Authorization: Bearer $OPEN_SPANNER_API_KEY"For nested filters or saved dashboard queries, use POST /v1/usages/search.
See Query Model for buckets, filters, and
breakdowns, or SDKs for language-specific clients.