Query Model

Open Spanner stores usage events and returns aggregates over time windows.

Buckets

A bucket has:

• Start and end time
• Meter
• Unit
• Aggregated value
• Subject, when the query is scoped to one subject or grouped by subject
• Optional dimension group values

The meter's aggregation mode decides how the value is calculated.

Basic Query

Use query parameters when you know the direct filters:

curl "http://localhost:18081/v1/usages?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"

Omit subject to aggregate every subject for the meter. Add subject=org_123 when you want a single customer's bucket series.

Advanced Query

Use POST /v1/usages/search when you need nested filter groups or grouping:

{
  "meter": "api_requests",
  "from": "2026-06-01T00:00:00Z",
  "to": "2026-06-10T00:00:00Z",
  "bucket_size": "day",
  "group_by": ["subject", "service.tier"],
  "filter": {
    "type": "group",
    "op": "and",
    "rules": [
      {
        "type": "condition",
        "field": "metadata.service.tier",
        "op": "eq",
        "value": "gold"
      }
    ]
  }
}

Use group_by: ["subject"] to return one row per subject in each bucket. Combine subject with metadata dimensions when you need customer-by-region, customer-by-plan, or customer-by-service-tier reports. Dotted fields such as service.tier target nested metadata and are queried as metadata.service.tier in filters.

Breakdowns

Use POST /v1/usages/breakdowns/search when you want to know which subjects or dimension values contributed the most usage inside a time window.

Breakdowns use the meter's aggregation mode. For a sum meter, the top value is the value with the largest summed quantity. For a count meter, the quantity is the event count. The response also includes the raw number of matching events for each value.

{
  "meter": "api_requests",
  "field": "subject",
  "from": "2026-06-01T00:00:00Z",
  "to": "2026-06-10T00:00:00Z",
  "limit": 5,
  "filter": {
    "type": "condition",
    "field": "metadata.service.tier",
    "op": "eq",
    "value": "gold"
  }
}

Use field: "subject" for top subjects. Use a metadata key, such as field: "region-name", field: "service.tier", or field: "endpoint", for top dimension values.

{
  "items": [
    {
      "field": "subject",
      "value": "org_123",
      "quantity": 4200,
      "events": 128,
      "aggregation": "sum",
      "unit": "request"
    }
  ]
}