Meter usage tracking

Record and query metered usage events to monitor consumption across your account.

Meter usage tracking lets you record consumption events against named meters and retrieve aggregated summaries over a date range. Use it to monitor resource usage, track billable activity, or build internal dashboards around any metric you define.

Each usage entry captures a meter name, a numeric usage amount, and an optional timestamp. Sailia stores every entry and aggregates totals per meter when you query a summary.

How it works

1. Record usage — send a usage entry with a meter name and amount whenever a billable or trackable event occurs.
2. Query summaries — retrieve aggregated usage and event counts grouped by meter for a given date range.

All timestamps are handled as Unix seconds. If you omit the timestamp when recording, Sailia uses the current server time.

Record a usage entry

Send a POST request to the meter usage endpoint with the following body:

Field	Type	Required	Description
Meter	string	Yes	The name of the meter (e.g. api-calls, sms-sent, storage-gb)
Usage	number	Yes	The usage amount — must be greater than 0
ExtraInfo	string	No	Optional metadata as a string (e.g. a JSON-encoded payload with additional context)
OccurredAt	integer	No	A Unix timestamp (seconds) for when the event occurred. Defaults to the current time if omitted

{
  "Meter": "api-calls",
  "Usage": 1,
  "ExtraInfo": "{\"endpoint\": \"/bookings\"}",
  "OccurredAt": 1742860800
}

A successful request returns a 201 response with the created entry:

{
  "data": {
    "ID": 42,
    "Meter": "api-calls",
    "Usage": 1.0
  }
}

Validation

• Meter must be a non-empty string.
• Usage must be numeric and greater than 0.
• OccurredAt, if provided, must be a valid Unix timestamp integer.

Validation errors return a 422 response with details about which fields failed.

Get a usage summary

Send a GET request to the meter usage endpoint with from and to query parameters in YYYY-MM-DD format:

GET /api/v2/usage/meters?from=2026-03-01&to=2026-03-31

The response includes totals per meter, along with the overall usage and event count for the period:

{
  "data": {
    "Period": {
      "From": "2026-03-01",
      "To": "2026-03-31",
      "FromTimestamp": 1740787200,
      "ToTimestamp": 1743465599
    },
    "Totals": {
      "Usage": 1250.0,
      "Events": 340
    },
    "Meters": [
      {
        "Meter": "api-calls",
        "TotalUsage": 1000.0,
        "EventCount": 300
      },
      {
        "Meter": "sms-sent",
        "TotalUsage": 250.0,
        "EventCount": 40
      }
    ]
  }
}

Field	Description
Period	The requested date range with both human-readable dates and Unix timestamps
Totals.Usage	Sum of all usage amounts across all meters in the period
Totals.Events	Total number of usage entries recorded across all meters
Meters	A list of per-meter breakdowns, sorted by total usage (highest first)

Query parameters

Parameter	Type	Required	Description
from	string	Yes	Start date in YYYY-MM-DD format (inclusive, from 00:00:00)
to	string	Yes	End date in YYYY-MM-DD format (inclusive, through 23:59:59)

The to date must be on or after the from date. Both parameters are required — omitting either returns a 422 error.

Built-in meters

Sailia automatically records usage entries for certain platform events. These meters appear in your usage summaries alongside any custom meters you define — no additional setup is required.

Meter	Trigger	Extra info
order-completed	A customer completes a purchase and payment succeeds	BasketID — the ID of the completed basket
waitlist-notified	A waitlist notification email is sent to a customer	WaitlistID, MultiBookingID — identifiers for the waitlist entry and booking
workflow-email-sent	An automated workflow sends an email on your behalf	None

Example summary with built-in meters

{
  "data": {
    "Period": {
      "From": "2026-03-01",
      "To": "2026-03-31"
    },
    "Totals": {
      "Usage": 135.0,
      "Events": 135
    },
    "Meters": [
      {
        "Meter": "order-completed",
        "TotalUsage": 72.0,
        "EventCount": 72
      },
      {
        "Meter": "workflow-email-sent",
        "TotalUsage": 50.0,
        "EventCount": 50
      },
      {
        "Meter": "waitlist-notified",
        "TotalUsage": 13.0,
        "EventCount": 13
      }
    ]
  }
}

Built-in meter entries include an ExtraInfo field with a JSON-encoded payload containing contextual identifiers. You can use these to cross-reference events with other parts of the system.

Error handling

All error responses follow the standard problem detail format:

{
  "type": "https://sailia.dev/problems/validation",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Meter is required",
  "instance": "/api/v2/usage/meters"
}

Common error scenarios:

Status	Cause
422	Missing or invalid fields — check the detail message for specifics
403	You do not have permission to access this resource