> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.solvimon.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server.

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

> **Note**
>
> 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](/platform-guides/meter-and-event-design/meter/meter-values) 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](/platform-guides/customers-and-billing/customer/parent-child-relationships) 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](/platform-guides/workflows/workflow-triggers): 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.

```mermaid
flowchart LR
    A[Usage limit per customer] --> C{Threshold crossed?}
    B[Thresholds on USAGE workflow] --> C
    C -- yes --> D[Workflow actions run once per period]
    D --> E[SEND_WEBHOOK: USAGE_LIMIT.THRESHOLD_REACHED]
```

## Implementation

### Create a usage limit

Create the limit with [POST /v1/usage-limits](https://docs.solvimon.com/api-docs/configuration-api/usage-limits/post-usage-limits):

**`Create a usage limit for a customer`**

```bash 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`**

```json 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](/platform-guides/customers-and-billing/customer/parent-child-relationships).

### Alert on thresholds

Create a `USAGE` workflow that contains the thresholds. Then attach an action, typically a [`SEND_WEBHOOK` action](/platform-guides/workflows/workflow-actions). Your platform then receives a `USAGE_LIMIT.THRESHOLD_REACHED` notification with the customer, the metric, the crossed threshold, 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](https://docs.solvimon.com/api-docs/event-api/usage-limits/get-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`**

```bash 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.

---

See also: [Workflows](/platform-guides/workflows/workflows), [Workflow actions](/platform-guides/workflows/workflow-actions), [Designing your meters & events](/platform-guides/meter-and-event-design/designing-meters-and-events).