Create Meter

Create a new meter to track usage events with configurable aggregation and filtering.

POST /v1/meters

Create Meter

cURL

curl --request POST \
  --url https://api.example.com/v1/meters \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "event_name": "<string>",
  "aggregation": {
    "aggregation.type": "<string>",
    "aggregation.field": "<string>",
    "aggregation.expression": "<string>",
    "aggregation.multiplier": "<string>",
    "aggregation.bucket_size": "<string>",
    "aggregation.group_by": "<string>"
  },
  "filters": [
    {
      "filters[].key": "<string>",
      "filters[].values": [
        {}
      ]
    }
  ],
  "reset_usage": "<string>"
}
'

200

{
  "id": "<string>",
  "name": "<string>",
  "tenant_id": "<string>",
  "event_name": "<string>",
  "aggregation": {},
  "filters": [
    {}
  ],
  "reset_usage": "<string>",
  "status": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>"
}

Request Body

name · string · required

Human-readable name for the meter.

Example: "API Usage Meter"

event_name · string · required

Name of the event to track. Must match the event name sent via the events API.

Example: "api_request"

aggregation · object · required

Defines how to aggregate the usage events.

Show aggregation properties

aggregation.type · string · required

Aggregation method to apply.

Options: "COUNT", "SUM", "MAX", "UNIQUE_COUNT", "LATEST"

aggregation.field · string

Property name in event data to aggregate (required for SUM, MAX, LATEST).

Example: "tokens"

aggregation.expression · string

Optional CEL expression to compute per-event quantity from event properties. When set, replaces field-based extraction.

Example: "token * duration * pixel"

aggregation.multiplier · string

Decimal multiplier to apply to the aggregated value.

Example: "1.5"

aggregation.bucket_size · string

Window size for bucketed aggregations.

Options: "HOUR", "DAY", "MONTH"

aggregation.group_by · string

Property name to group by before aggregating (currently only supported for MAX with bucket_size).

Example: "user_id"

filters · array

Array of filters to apply before aggregation.

Show filter properties

filters[].key · string · required

Property name in event data to filter on.

Example: "region"

filters[].values · array · required

Array of values to match (OR condition).

Example: ["us-east-1", "us-west-2"]

reset_usage · string · required

Determines when usage resets.

Options: "BILLING_PERIOD", "NEVER"

Response

id · string

Unique identifier for the meter.

Example: "meter_550e8400e29b41d4a716446655440000"

name · string

Human-readable name for the meter.

tenant_id · string

Tenant ID that owns this meter.

event_name · string

Name of the event being tracked.

aggregation · object

Aggregation configuration.

filters · array

Array of filters applied to events.

reset_usage · string

Usage reset configuration.

status · string

Status of the meter.

Values: "published", "draft", "archived"

created_at · string

ISO 8601 timestamp when the meter was created.

updated_at · string

ISO 8601 timestamp when the meter was last updated.

Example Request

cURL

curl --request POST \
  --url https://api.flexprice.io/v1/meters \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "API Usage Meter",
    "event_name": "api_request",
    "aggregation": {
      "type": "COUNT"
    },
    "filters": [
      {
        "key": "method",
        "values": ["GET", "POST"]
      }
    ],
    "reset_usage": "BILLING_PERIOD"
  }'

Example Response

{
  "id": "meter_550e8400e29b41d4a716446655440000",
  "name": "API Usage Meter",
  "tenant_id": "tenant_123",
  "event_name": "api_request",
  "aggregation": {
    "type": "COUNT"
  },
  "filters": [
    {
      "key": "method",
      "values": ["GET", "POST"]
    }
  ],
  "reset_usage": "BILLING_PERIOD",
  "status": "published",
  "created_at": "2024-03-20T15:04:05Z",
  "updated_at": "2024-03-20T15:04:05Z"
}