Skip to main content
POST
Add a usage alert
It is recorded in your team’s audit log. Each goes to the address the recipient signs in with.
  • Owners and Admins only. An API key needs team:manage.
  • trigger: calls (in a UTC day), included_calls_percent (of the day’s included calls), overage (cents of overage in the billing period), budget_percent (of the overage budget) or cap_reached. Percentages are 1 to 1000.
  • recipients: roles, everyone in them when it sends, and member_ids, verified members of your team (members who have joined it). At least one. Alerts in dollars (overage, budget_percent) email only the Owners and Admins among them.
  • A team keeps up to 50 alerts.
  • Callers: an API key, an MCP OAuth token or a Dashboard session.
  • Permission: team:manage; an API key also needs team:manage.
  • Effect: Creates or changes something.
  • Errors: business_account_required, role_permission_missing, and the errors any request can get.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
trigger
object
required

What sets it off: calls or included_calls_percent each UTC day, overage or budget_percent (dollars, Owners and Admins only) each billing period, or cap_reached when the daily cap refuses runs

recipients
object
required

At least one role or member

on
boolean

Default true

Response

The alert

id
string
required
trigger
object
required

What sets it off: calls or included_calls_percent each UTC day, overage or budget_percent (dollars, Owners and Admins only) each billing period, or cap_reached when the daily cap refuses runs

window
enum<string>
required

It is emailed at most once in each: a UTC day, or a billing period

Available options:
day,
billing_period
on
boolean
required
recipients
object
required
on_changed_at
string
required

When it was created, or last turned on or off

last_sent_at
string | null
required

ISO 8601 UTC