Metrics API

The Metrics API allows you to define, manage, and query metrics that track customer usage. These metrics are the foundation for usage-based billing, real-time feature entitlement checks, and analytics.

Overview

Metrics are definitions that tell the system how to calculate a value from the events you send. They can be:

• Simple: Aggregations (SUM, COUNT, etc.) of a single event.
• Indexed: Pre-computed aggregations for faster queries.
• Complex: Custom SQL queries for more advanced calculations.

Authentication

All API requests require authentication via merchant credentials.

Endpoints

List all Metric Definitions

Retrieves a list of all metric definitions for the authenticated merchant.

GET https://api.getlumen.dev/v1/metrics

Response

[
  {
    "id": "metric_123",
    "name": "API Calls",
    "description": "Total number of API calls.",
    "queryType": "simple",
    "aggregationType": "COUNT",
    "eventName": "api_call",
    "valueType": "NUMERIC"
  }
]

Get a Specific Metric Definition

Retrieves a single metric definition by its ID.

GET https://api.getlumen.dev/v1/metrics/{id}

Parameters

Create a Metric Definition

Creates a new metric definition.

POST https://api.getlumen.dev/v1/metrics

Request Body

{
  "name": "API Calls",
  "description": "Total number of API calls.",
  "queryType": "simple",
  "aggregationType": "COUNT",
  "eventName": "api_call",
  "valueType": "NUMERIC"
}

Update a Metric Definition

Updates an existing metric definition. Some fields like aggregationType and valueType are immutable and cannot be changed after creation.

POST https://api.getlumen.dev/v1/metrics/{id}/update

Delete a Metric Definition

Soft deletes a metric definition.

POST https://api.getlumen.dev/v1/metrics/{id}/delete

Get Metric Value

Calculates and retrieves the current value of a metric for a specific customer, with an optional time frame.

GET https://api.getlumen.dev/v1/metrics/{id}/value?customerId={customerId}

Query Parameters

Response

{
  "id": "metric_123",
  "name": "API Calls",
  "customerId": "cust_456",
  "value": 1250,
  "queryType": "simple",
  "timeframe": { "type": "ALL" }
}