Meters API

Create and manage meters that define how events are aggregated.

List meters

GET/v1/meters

Returns all meters for the authenticated tenant. Response is paginated.

json

{
  "data": [
    {
      "id": "01HQXYZ...",
      "slug": "api-requests",
      "event_type": "api_request",
      "aggregation": { "type": "count" },
      "window_size": "hour",
      "value_property": null,
      "group_by": [],
      "filters": [],
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "has_more": false,
  "next_page_token": null
}

Create a meter

POST/v1/meters

Field	Type	Required	Description
`slug`	string	Yes	Unique identifier ([a-z0-9_-]+)
`event_type`	string	Yes	Which events to aggregate
`aggregation`	object	Yes	{ "type": "count" } or { "type": "count_unique", "on_property": "user_id" } or { "type": "percentile", "percentile": 99 }. Types: count, sum, count_unique, max, min, average, last, percentile
`window_size`	string	Yes	"minute" \| "hour" \| "day" \| "billing_period" \| "custom"
`value_property`	string	No	Property path for sum/max/min aggregations
`group_by`	string[]	No	Properties to group results by
`filters`	object[]	No	Event filters (property, operator, value)

Response

json

{
  "id": "01HQXYZ...",
  "tenant_id": "01HQABC...",
  "slug": "api-requests",
  "event_type": "api_request",
  "aggregation": { "type": "count" },
  "value_property": null,
  "group_by": [],
  "window_size": "hour",
  "filters": [],
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}

Filter operators

Operator	Description
`eq`	Equals
`neq`	Not equals
gt` / `gte	Greater than / greater or equal
lt` / `lte	Less than / less or equal
in` / `not_in	In set / not in set
`contains`	Substring match

The contains operator is useful for substring matching on string properties.

Get a meter

GET/v1/meters/:slug

Returns a single meter by its slug.

Delete a meter

DELETE/v1/meters/:id

Permanently deletes a meter. Existing aggregated data is not removed.