Skip to main content

​
Overview

Notification rules let you set up alerts when agents exceed usage thresholds. You can monitor token consumption or costs over different time periods and choose to receive notifications, block requests, or both.

​
List Notification Rules

Retrieve all notification rules for a specific agent, including their trigger history.

​
Query Parameters

​
agent_name
string
required
Name of the agent to retrieve rules for

​
Response Fields

​
id
string
Unique identifier for the rule
​
agent_name
string
Name of the agent this rule monitors
​
metric_type
string
Type of metric to monitor. Either tokens or cost
​
threshold
number
Threshold value that triggers the alert. For tokens, this is the total token count. For cost, this is USD.
​
period
string
Time window for threshold calculation. One of: hour, day, week, month
​
action
string
Action to take when threshold is exceeded. One of:
  • notify - Send email notification only
  • block - Block agent requests until threshold resets
  • both - Send notification and block requests
​
is_active
boolean
Whether the rule is currently active
​
trigger_count
number
Number of times this rule has been triggered
​
created_at
string
ISO 8601 timestamp of rule creation
​
updated_at
string
ISO 8601 timestamp of last update

​
Example Request

curl -X GET 'https://api.manifest.build/api/v1/notifications?agent_name=my-agent' \
  -H 'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN'

​
Example Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "agent_name": "my-agent",
    "metric_type": "tokens",
    "threshold": 1000000,
    "period": "day",
    "action": "notify",
    "is_active": true,
    "trigger_count": 3,
    "created_at": "2024-03-04T10:30:00",
    "updated_at": "2024-03-04T10:30:00"
  },
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "agent_name": "my-agent",
    "metric_type": "cost",
    "threshold": 10.0,
    "period": "week",
    "action": "both",
    "is_active": true,
    "trigger_count": 0,
    "created_at": "2024-03-04T11:00:00",
    "updated_at": "2024-03-04T11:00:00"
  }
]

​
Create Notification Rule

Create a new notification rule for an agent.

​
Request Body

​
agent_name
string
required
Name of the agent to monitor. Must be an existing agent in your workspace.
​
metric_type
string
required
Type of metric to monitor:
  • tokens - Monitor total token usage (input + output)
  • cost - Monitor cost in USD
​
threshold
number
required
Threshold value that triggers the alert. Must be greater than or equal to 1.
  • For tokens: Total token count
  • For cost: USD amount (e.g., 10.5 for $10.50)
​
period
string
required
Time window for threshold calculation:
  • hour - Rolling 60-minute window
  • day - Rolling 24-hour window
  • week - Rolling 7-day window
  • month - Rolling 30-day window
​
action
string
default:"notify"
Action to take when threshold is exceeded:
  • notify - Send email notification
  • block - Block agent API requests
  • both - Send notification and block requests

​
Example Request

curl -X POST 'https://api.manifest.build/api/v1/notifications' \
  -H 'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_name": "my-agent",
    "metric_type": "cost",
    "threshold": 50,
    "period": "month",
    "action": "both"
  }'

​
Example Response

{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "agent_name": "my-agent",
  "tenant_id": "tenant-001",
  "agent_id": "agent-001",
  "user_id": "user-123",
  "metric_type": "cost",
  "threshold": 50,
  "period": "month",
  "action": "both",
  "is_active": true,
  "created_at": "2024-03-04T12:00:00",
  "updated_at": "2024-03-04T12:00:00"
}

​
Update Notification Rule

Update an existing notification rule. All fields are optional.

​
Path Parameters

​
id
string
required
The unique identifier of the rule to update

​
Request Body

​
metric_type
string
Change the metric type. Either tokens or cost.
​
threshold
number
Update the threshold value. Must be greater than or equal to 1.
​
period
string
Change the time window: hour, day, week, or month
​
is_active
boolean
Enable or disable the rule without deleting it
​
action
string
Change the action: notify, block, or both

​
Example Request

curl -X PATCH 'https://api.manifest.build/api/v1/notifications/770e8400-e29b-41d4-a716-446655440002' \
  -H 'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "threshold": 100,
    "is_active": false
  }'

​
Example Response

{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "agent_name": "my-agent",
  "tenant_id": "tenant-001",
  "agent_id": "agent-001",
  "user_id": "user-123",
  "metric_type": "cost",
  "threshold": 100,
  "period": "month",
  "action": "both",
  "is_active": false,
  "created_at": "2024-03-04T12:00:00",
  "updated_at": "2024-03-04T12:15:00"
}

​
Delete Notification Rule

Permanently delete a notification rule.

​
Path Parameters

​
id
string
required
The unique identifier of the rule to delete

​
Example Request

curl -X DELETE 'https://api.manifest.build/api/v1/notifications/770e8400-e29b-41d4-a716-446655440002' \
  -H 'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN'

​
Example Response

{
  "deleted": true
}

​
How Thresholds Work

​
Rolling Windows

All time periods use rolling windows, not calendar boundaries:
  • Hour: Usage in the last 60 minutes from now
  • Day: Usage in the last 24 hours from now
  • Week: Usage in the last 7 days from now
  • Month: Usage in the last 30 days from now

​
Threshold Checking

Rules are evaluated every 5 minutes by a background cron job. When usage exceeds the threshold:
  1. Notify action: An email is sent to the configured notification email address
  2. Block action: Subsequent OTLP requests from the agent are rejected with a 429 status
  3. Both action: Email is sent and requests are blocked

​
Cost Calculation

Cost thresholds use the model pricing data configured in your workspace. Costs are calculated as: 
total_cost = (input_tokens × input_price) + (output_tokens × output_price)
Prices are in USD per million tokens and pulled from the model_pricing table.

​
Use Cases

​
Development Safety Net

Prevent runaway costs during development: 
{
  "agent_name": "dev-agent",
  "metric_type": "cost",
  "threshold": 5,
  "period": "day",
  "action": "both"
}

​
Production Monitoring

Get notified about unusual spikes without blocking production: 
{
  "agent_name": "prod-agent",
  "metric_type": "tokens",
  "threshold": 10000000,
  "period": "hour",
  "action": "notify"
}

​
Budget Enforcement

Hard cap on monthly spending: 
{
  "agent_name": "any-agent",
  "metric_type": "cost",
  "threshold": 500,
  "period": "month",
  "action": "block"
}

​
Notes

  • You must configure an email provider before creating rules with notify or both actions
  • Rules are tenant-scoped — you can only create rules for agents you own
  • Deleting an agent also deletes all its notification rules
  • The trigger_count field tracks historical triggers and never decreases
  • Blocked requests return HTTP 429 with a descriptive error message

Build docs developers (and LLMs) love

Get started for freeTalk to us