Limits

Rate limits

Calls are counted over 60 seconds by Cloudflare's rate limiter, separately in each Cloudflare location, so the numbers are approximate. Over a limit, the answer is 429 rate_limited with a Retry-After: 60 header.

Other routes have no rate limit of their own. If the rate limiter itself fails, the call goes through.

API calls are counted

• Every call to a paid-service route (phone, email, address lookup, domains, AI worker boxes, publishing) counts as one API call, per key per day (UTC). So do calls to /api/v1/credits and /api/v1/affiliate, and each git clone, fetch, pull or push. They're charged the next night at the API calls price on the dashboard's Rates page.
• A call is counted once it passes the account checks, before the key's operation is checked. A call refused at that point, or by a rate limit, still counts.
• Not counted: the team list, website leads, the account, check-ins, updates, device reports and deleting the company.
• API calls are general usage, so they stop when the company's or the person's general spending limit is used up.

Spending limits

A charge has to fit under every limit that applies to it.

• Two kinds. The company and each person have one limit for AI models and one for General: calls, texts, email, address lookup, API calls, AI worker boxes and everything else that isn't AI.
• Periods. A monthly limit starts over on the 1st, a weekly one on Monday, at 00:00 UTC. A key's limit resets daily, weekly or monthly, also in UTC.
• Whose limit. A person's own key counts toward that person. The company app's shared key counts toward the signed-in person when the call carries their sign-in, and otherwise only toward the company.
• When it's checked. In the same database write that reserves the charge, so calls made at the same moment can't all slip under it. Paid-service routes also refuse up front once the company's or the person's general limit is used up.
• Reminders. A limit can have reminder amounts. Each sends one email a period and stops nothing.
• Adding funds doesn't lift a limit. Raise it, or wait for the reset. A key's limit is on its page under API Keys; the others are on Usage & limits.

AI worker box caps

Set when you start a box (POST /api/v1/sandboxes or the start_box tool):

• A budget lowers the time cap to the minutes it covers at the box's price. A budget that doesn't cover one minute answers 400 budget_too_small.
• Every started minute is charged, the first one when the box starts. Each minute goes through the spending limits and the key's check. A minute that's refused stops the box.
• A stopped box says why in stopReason, for example idletime_capbudgetspending_limitfundskey_changedstopped.
• A command waits 1 second to 10 minutes (timeoutMs, default 2 minutes). Output is cut at 200,000 characters. One file write is up to 5,000,000 characters.

Boxes running at once, per company:

One more answers 429 too_many_boxes. Stop a box first, or ask us to raise it.

402 Payment Required

payment_required with a pay block: there aren't enough funds for this charge. The answer says what's needed, in dollars, and how to pay:

{
  "error": "payment_required",
  "message": "…",
  "needed": 0.03,
  "balance": 0,
  "pay": {
    "method": "POST",
    "url": "/api/v1/credits",
    "headers": { "Idempotency-Key": "<unique-purchase-id>" },
    "instructions": "…",
    "body": { "amount": 5 },
    "alternatives": ["sharedPaymentToken"]
  },
  "then": "…"
}

• amount is what's missing, rounded up to whole dollars, at least $5 and at most $5,000.
• The key can buy only if an owner turned on Add funds for it, within its limits for one purchase and for the month. Send a new Idempotency-Key for each purchase, and the same one only to retry that purchase.
• Once the purchase is paid, send the original request again.

Other 402 answers:

• payment_required without a pay block: the account is locked for a missed payment (an owner updates the card on Plans), or it pays only from prepaid funds and they're used up (add funds in Billing, or turn off prepaid only).
• needs_managed_plan: calling, texting, email, address lookup and hosting need a card on file (pay as you go, $0 to start) and a paid-up account.
• card_required: publishing needs a card on file.

429 Too Many Requests

• rate_limited: over a rate limit. Wait the Retry-After seconds.
• spend_limit_reached: a spending limit is reached: the company's, the person's or this key's. The message says which limit, what's left and when it resets. Adding funds doesn't help.
• too_many_boxes: your plan's boxes at once are all running.
• lookup_limit: the same address pick is still loading. Try again in a moment.

A key whose own spending limit is already used up is refused before any of this, with 401 invalid_key.