Projects

Set a usage threshold

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.

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)

Request body

metric'cost_usd' | 'tokens' required
window'calendar_month' | 'rolling_24h' required
thresholdnumber required

Must be greater than zero.

Example request

{
  "threshold": 250
}

Response

The threshold was created.

idstring required
project_idstring 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.

thresholdnumber required

The value the windowed aggregate must cross to fire.

last_fired_atstring date-time nullable

When it last fired; null until the first time.

fired_window_keystring 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_atstring date-time

Example response

{
  "id": "uth_V1StGXR8Z5jdHi6B",
  "threshold": 250
}

Changes

No recorded changes to this operation across all 1 revision of this API.