---
title: "List usage thresholds"
method: GET
path: "/v1/projects/{project_id}/usage/thresholds"
tags: ["Projects"]
---

# List usage thresholds

`GET /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`)

The spend alerts this project has set. A threshold fires the usage.threshold_crossed event when the project's windowed usage crosses it, so one is only useful alongside a webhook subscribed to that event.

## Query parameters

- `limit` integer
- `offset` integer

## Response `200`

One page of thresholds.

- object
  - `data` UsageThreshold[], required
    - `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
  - `total` integer, required
  - `limit` integer, required
  - `offset` integer, required

## Other responses

- `401`: Missing or invalid credentials.
- `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)