Checking Usage

Two Usage Query Modes

ABAXUS provides two distinct APIs for querying usage, each with different consistency guarantees and performance characteristics. Choosing the right one for your use case is important.

GET /v1/usage/summary — Eventually Consistent

The summary endpoint returns pre-computed aggregate totals from ABAXUS’s internal materialized view. These aggregates are updated continuously as events are processed from the queue, but there is a short lag between event ingestion and aggregate update.

1
2

curl "$ABAXUS_URL/v1/usage/summary?customer_id=cust_acme&metric_key=api_calls" \
  -H "Authorization: Bearer $ABAXUS_KEY"

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "customer_id": "cust_acme",
  "metric_key": "api_calls",
  "period_start": "2026-04-01T00:00:00Z",
  "period_end": "2026-04-30T23:59:59Z",
  "total": 847293,
  "unit_label": "calls",
  "meta": {
    "lag_seconds": 12,
    "last_event_at": "2026-04-03T10:14:21Z",
    "computed_at": "2026-04-03T10:14:09Z"
  }
}

The meta.lag_seconds field tells you how stale the aggregate is — the number of seconds between the most recent event processed and the current wall clock time. Under normal operating conditions, this is under 30 seconds. During high-volume ingestion spikes, it may reach a few minutes.

When to use it:

• Customer-facing usage dashboards that refresh periodically
• Internal monitoring and alerting
• Any context where near-real-time data is acceptable
• High-frequency polling (the pre-computed nature makes it fast and cheap)

POST /v1/usage/compute — Exact, On-Demand

The compute endpoint scans raw events directly — bypassing the pre-computed aggregates — and returns an exact usage total. This is the correct API to use before issuing invoices or any time you need to be certain the total is accurate.

1
2
3
4
5
6
7
8
9

curl -X POST "$ABAXUS_URL/v1/usage/compute" \
  -H "Authorization: Bearer $ABAXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_acme",
    "metric_key": "api_calls",
    "period_start": "2026-04-01T00:00:00Z",
    "period_end": "2026-04-30T23:59:59Z"
  }'

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "customer_id": "cust_acme",
  "metric_key": "api_calls",
  "period_start": "2026-04-01T00:00:00Z",
  "period_end": "2026-04-30T23:59:59Z",
  "total": 847451,
  "unit_label": "calls",
  "meta": {
    "event_count": 51204,
    "late_event_count": 23,
    "computed_at": "2026-04-03T10:15:44Z",
    "duration_ms": 187
  }
}

The meta.late_event_count field tells you how many events in the result had timestamps earlier than the period_start but arrived (were ingested) after the period had already ended. These are events that would have been missed by a naive cutoff-date approach. ABAXUS includes them in the compute result because they represent real usage that occurred within the period.

When to use it:

• Immediately before creating an invoice
• When a customer disputes a charge and you need the authoritative total
• After a backfill operation to verify the corrected totals
• One-time data reconciliation tasks

Querying All Metrics for a Customer

To get a usage summary for all active metrics at once:

1
2

curl "$ABAXUS_URL/v1/usage/summary?customer_id=cust_acme" \
  -H "Authorization: Bearer $ABAXUS_KEY"

Response:

1
2
3
4
5
6
7
8
9

{
  "customer_id": "cust_acme",
  "period_start": "2026-04-01T00:00:00Z",
  "metrics": [
    { "metric_key": "api_calls", "total": 847293, "unit_label": "calls" },
    { "metric_key": "data_egress_gb", "total": 142.7, "unit_label": "GB" },
    { "metric_key": "active_seats", "total": 12, "unit_label": "seats" }
  ]
}

This is the recommended approach for building a customer usage dashboard — one request gives you the full picture.

Usage Histograms

For more granular views (daily or hourly breakdowns), use the histogram endpoint:

1
2

curl "$ABAXUS_URL/v1/usage/histogram?customer_id=cust_acme&metric_key=api_calls&granularity=day" \
  -H "Authorization: Bearer $ABAXUS_KEY"

This returns a time-series breakdown of usage, useful for rendering usage charts in your customer portal.