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.

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:

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:

$
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"
>
    }
>
  }'

1
{
2
  "object_type": "USAGE_LIMIT",
3
  "id": "usl_8LmPc5XrvNbTeK4QjYZ9H",
4
  "customer_id": "cust_AbD3DqausjOYiMNDZY11F",
5
  "meter_value_calculation_id": "mvc_5RmXe2QbtKfYuA9DcNH3P",
6
  "scope": "SELF",
7
  "limit": {
8
    "number": "1000000"
9
  }
10
}

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:

$
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.

See also: Workflows, Workflow actions, Designing your meters & events.