Meter usage tracking

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

Record usage — send a usage entry with a meter name and amount whenever a billable or trackable event occurs.
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
`campaign-email-sent`	Recipients are queued for a marketing campaign send	`campaignID`, `campaignUUID`, `campaignName` — identifiers and the campaign’s internal name

Example summary with built-in meters

{
  "data": {
    "Period": {
      "From": "2026-03-01",
      "To": "2026-03-31"
    },
    "Totals": {
      "Usage": 155.0,
      "Events": 137
    },
    "Meters": [
      {
        "Meter": "order-completed",
        "TotalUsage": 72.0,
        "EventCount": 72
      },
      {
        "Meter": "workflow-email-sent",
        "TotalUsage": 50.0,
        "EventCount": 50
      },
      {
        "Meter": "campaign-email-sent",
        "TotalUsage": 20.0,
        "EventCount": 2
      },
      {
        "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

Overview

Usage

OTA

Meter usage tracking

How it works

Record a usage entry

Validation

Get a usage summary

Query parameters

Built-in meters

Example summary with built-in meters

Error handling

​How it works

​Record a usage entry

​Validation

​Get a usage summary

​Query parameters

​Built-in meters

​Example summary with built-in meters

​Error handling

How it works

Record a usage entry

Validation

Get a usage summary

Query parameters

Built-in meters

Example summary with built-in meters

Error handling