Every API key and every assistant connection has a daily spend cap in credits. Credits are the units in your 50heads balance that pay for answers. The default for a new connection is 5,000 credits.

You can add two more limits to a key or connection:

  • a monthly cap, over the calendar month (UTC);
  • a per-question cap, the most a single question may cost.

What happens at a cap

An ask that would take the connection past any of its caps is refused: the API answers 402 with spend_cap_reached (the MCP server reports it as spend_cap_exceeded). The error says how much is left and, for the daily and monthly caps, when it resets. Nothing is spent. Reading results still works. A question that is canceled or refunded gives its credits back to the cap.

Checking what's left

The balance check in your assistant, and GET /v1/billing/balance, return capRemaining for the key or connection you're using: the smaller of what is left today and this month. A well-behaved agent checks before it asks, but the cap is enforced whether it checks or not. GET /v1/connections/current shows the connection's caps and what it has spent today and this month.

Changing a cap

In Developers, open Scopes and caps on a key or Caps and scopes on a connection and set new caps. The change takes effect right away.

On a team, the owner or an admin can change the cap of a key or app another member made. Open Keys and apps in Team, or for a Zapier connection, Settings, then Integrations. See Your team.

Old keys made before caps existed have no cap. They are listed under Legacy keys in Developers so you can revoke them, and we will retire them after 90 days' notice. Make a new key with a cap instead.

Alerts

Under Developers, Alerts, choose which of these emails you want. They go to your account email, and each email has an unsubscribe link that turns that alert off.

  • A connection reaches 80% of its daily cap (or of its monthly cap, if it has one).
  • Errors spike: a connection had at least 50 calls yesterday and more than a fifth of them failed.
  • A new agent connects.

The alerts are on Developers, not under Settings, then Emails.

Account limits

Caps on keys sit inside your account's own limits: an agent can't spend more than your balance. For a key or connection made for a team, the asks spend the team's credits, and a member's monthly limit in the team applies too.