---
title: "Set a usage threshold"
method: POST
path: "/v1/projects/{project_id}/usage/thresholds"
tags: ["Projects"]
---

# Set a usage threshold

`POST /v1/projects/{project_id}/usage/thresholds`

## Request

- Base URL: `https://api.naturali.ai`
- URL: `https://api.naturali.ai/v1/projects/{project_id}/usage/thresholds`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.naturali.ai/authorize`, token URL `https://api.naturali.ai/token`, scopes: `mcp:access`)

Creates an alert on this project's windowed usage. Crossing it fires usage.threshold_crossed once per window — a calendar_month threshold fires at most once in a month, and a rolling_24h one re-arms when the windowed total falls back below 90% of the threshold, so a total hovering at the line does not alert repeatedly.

Requires the admin role: an alerting rule belongs to the account that pays, not to one member.

## Request body

- UsageThresholdCreate
  - `metric` 'cost_usd' | 'tokens', required
  - `window` 'calendar_month' | 'rolling_24h', required
  - `threshold` number, required: Must be greater than zero.

## Response `201`

The threshold was created.

- UsageThreshold: An alert on this project's windowed usage.
  - `id` string, required
  - `project_id` string, required
  - `metric` 'cost_usd' | 'tokens', required: What is measured — cost_usd across every meter type, or tokens (input + output + cached).
  - `window` 'calendar_month' | 'rolling_24h', required: The current UTC calendar month, or the trailing 24 hours.
  - `threshold` number, required: The value the windowed aggregate must cross to fire.
  - `last_fired_at` string, date-time, nullable: When it last fired; null until the first time.
  - `fired_window_key` string, nullable: The YYYY-MM window of the last fire, which is what keeps a calendar_month threshold to one alert per month. Null for rolling_24h and before the first fire.
  - `created_at` string, date-time

## Other responses

- `400`: An unknown metric or window, or a threshold that is not above zero.
- `401`: Missing or invalid credentials.
- `403`: The caller is a `member`; an alerting rule needs `admin`.
- `404`: The resource does not exist (existence is not leaked).

---

[API](https://skmtc.dev/naturali/apis/naturali-ai-api.md) · [All operations](https://skmtc.dev/naturali/apis/naturali-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/naturali/apis/naturali-ai-api/revisions/e4905b78f422?raw)