Usage limits & threshold alerts

Store a usage limit per customer and get alerted when consumption approaches it. The building block for pay-as-you-go platforms that give each end user a soft cap.

Why this matters

Platforms that resell usage, such as an AI product giving each end user a monthly token budget, need to know when a customer approaches their cap before the invoice lands. Usage limits store the cap per customer inside Solvimon, next to the consumption data it is measured against, and a workflow fires as thresholds are crossed. Your application decides what to do with the signal: warn the user, throttle, or upsell.

Usage limits are soft caps: Solvimon tracks consumption against the limit and alerts on thresholds, but does not block ingestion or enforce the cap. Enforcement stays in your application.

How it works

A UsageLimit links a customer_id to a meter value calculation with a limit (a number, amount or credits) and a scope:

Scope	Meaning
`SELF`	Limits the customer’s own usage.
`CHILDREN`	Sets a default limit for each child customer, resolved by walking up the hierarchy to the nearest parent.

A child’s own SELF limit for the same metric overrides its parent’s CHILDREN default, so you can set one default for a whole platform and still cap individual seats differently.

Alerting is configured through a USAGE workflow trigger: the workflow holds the thresholds (percentages of the resolved limit, or absolute values) while the limit itself stays per customer. One platform-level workflow therefore covers every customer and seat. Each threshold crossing fires the workflow’s actions once per billing period.

Implementation

Create a usage limit

Create the limit with POST /v1/usage-limits:

Create a usage limit for a customer

curl -X POST https://test.api.solvimon.com/v1/usage-limits \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_AbD3DqausjOYiMNDZY11F",
    "meter_value_calculation_id": "mvc_5RmXe2QbtKfYuA9DcNH3P",
    "scope": "SELF",
    "limit": {
      "number": "1000000"
    }
  }'

Response

{
  "object_type": "USAGE_LIMIT",
  "id": "usl_8LmPc5XrvNbTeK4QjYZ9H",
  "customer_id": "cust_AbD3DqausjOYiMNDZY11F",
  "meter_value_calculation_id": "mvc_5RmXe2QbtKfYuA9DcNH3P",
  "scope": "SELF",
  "limit": {
    "number": "1000000"
  }
}

To give every end user of a platform the same default cap, create one limit with scope: "CHILDREN" on the parent customer instead of one per child. Model each end user as a processing-only child customer; see Parent-child relationships.

Alert on thresholds

Create a USAGE workflow carrying the thresholds, then attach an action, typically a SEND_WEBHOOK action so your platform receives a usage.threshold_reached notification with the customer, the metric, the threshold that was crossed, the resolved limit and the consumption.

For scripted provisioning, POST /v1/workflows/init idempotently ensures a workflow and its actions exist by reference: it creates them when missing and leaves them untouched otherwise, so the call is safe to run on every deploy.

Read consumption against the limit

GET /v1/usage-limits/status returns the current-period consumption against the resolved limit per customer, giving you the numbers for an in-product usage dashboard:

Read usage against limits for a hierarchy

curl "https://test.api.solvimon.com/v1/usage-limits/status?customer_id=cust_AbD3DqausjOYiMNDZY11F&include_children=true" \
  -H "X-API-KEY: <apiKey>"

Pass include_children=true to cover a whole hierarchy in one call.

Edge cases

Limits are evaluated per billing period, and each workflow threshold fires at most once per period.
A child with its own SELF limit for a metric is not covered by the parent’s CHILDREN default for that metric; the child’s limit wins.
Usage limits alert but never block: event ingestion and invoicing continue past the limit.