Questions · Updated 2026-09-28

How do I put a spending limit on an AI agent that sends email?

Put a spending limit on an AI agent by giving it its own API key and setting budget_per_period on that key with PATCH /limits/keys/{id}. The limit counts messages per period and is enforced before the send; GET /usage shows what the agent has consumed and when the period resets.

Put a spending limit on an AI agent by creating a key for it with POST /api-keys and setting budget_per_period on that key with PATCH /limits/keys/{id}. The limit is counted in messages per period, checked before each send, and a send past it is refused with agent_budget_exceeded. GET /usage returns what the agent has consumed against it. There is no money counter; the limit is a count of messages.

What the limit counts

Two fields on PATCH /limits/keys/{id} are ceilings. budget_per_period is messages per period, and period is hourly, daily or monthly. rate_ceiling_per_minute is messages per rolling minute. Both count messages; neither counts currency. The operation summary states who may move them: "Set or clear this key’s period budget and per-minute ceiling. An API key may lower its own; raising one is a person’s decision, made in the console." Create the agent's key with permission: "sending_access" so it can send and cannot edit limits.

The account's plan inclusion is a separate ceiling that applies to every key. When it is spent the code is plan_limit_reached. What each plan includes is on the pricing page, and GET /billing/plan returns the plan on the account.

Watch it before it hits

GET /usage returns one row per key with budget_per_period, consumed_in_period, remaining, resets_at, used_percent and paused. Its summary: "This period usage, per key: budget, consumed, remaining, rate window, last used. The bill, made legible." GET /limits/keys/{id} returns the same ceiling and consumption for one key.

curl -sS -X GET https://api.agentisend.com/usage \
  -H "Authorization: Bearer $AGENTISEND_API_KEY"
200
{
  "account": {},
  "keys": [],
  "period_started_at": "2026-09-04T09:14:00Z"
}
Response

Two events arrive on a webhook before and at the wall. Budgets and the kill switch says limit.warning fires on the way up, before the budget is spent, and limit.exceeded fires the first time the budget refuses a send. Subscribe to both with POST /webhooks; the first one leaves time to act.

What the agent sees at the limit

The catalogue message for agent_budget_exceeded is "Key budget for the current period is exhausted." The fix is "Wait for the period to reset — get_agent_budget and GET /limits/keys/:id both say when. Raising a budget is a person’s decision, made in the console; a key cannot raise its own." retryable is false, so the agent stops and waits for resets_at. Over MCP the same numbers come from get_agent_budget, and set_limit can only lower a ceiling. The longer page on budgets, with the request bodies, is Agent email budgets.

Next