> ## Documentation Index
> Fetch the complete documentation index at: https://sailia-mintlify-5b02008a.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 |

```json theme={null}
{
  "Meter": "api-calls",
  "Usage": 1,
  "ExtraInfo": "{\"endpoint\": \"/bookings\"}",
  "OccurredAt": 1742860800
}
```

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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) |

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

## 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](/customers/campaigns) send | `campaignID`, `campaignUUID`, `campaignName` — identifiers and the campaign's internal name |

### Example summary with built-in meters

```json theme={null}
{
  "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
      }
    ]
  }
}
```

<Note>
  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.
</Note>

## Error handling

All error responses follow the standard problem detail format:

```json theme={null}
{
  "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                   |