MegalaniaBlog
  1. Blog
  2. AI agents
  3. Agent spend

Cap what an AI agent spends on web pages

Stop a looping AI agent from burning credits on web pages. A free price check, a cap per page, a budget per run and a monthly cap, measured on our Lab.

Jordan HayesDeveloper Relations
8 min read
AI agents
A robot head walks a loop of arrows past web pages. A meter beside the loop reads 20, then 0, and a gate with a padlock closes the loop.

The short answer: to limit AI agent API cost on web pages, set four limits, from small to large. Ask the price of a site first, for free. Cap what one page may cost with max_credits; a page above it is refused before any try, for free. Give each agent run a budget in your own tool, and pass what is left as max_credits. Then set a monthly spend cap on the account. On our test store, lab.megalania.io, a 20-credit budget stopped a 25-call loop at call 20, and a browser call over the cap cost 0.

Where an agent’s credits go

An agent does not spend on purpose. It spends when it:

  • loops: reads the same page again and again, because it forgot the answer or a step failed;
  • climbs: a page needs a browser or a residential exit, which costs more than plain HTTP;
  • fans out: one batch call with hundreds of URLs;
  • guesses: invents URLs that do not exist. A target’s 404 is still a page we delivered.

Each limit below stops one of these. None of them needs the model to behave.

Ask the price first: free

Our MCP server has check_site. The agent calls it with a host, and gets the price of each route and how well each route worked there:

Tool call
{"name": "check_site", "arguments": {"host": "lab.megalania.io"}}
Part of the answer
{"price": {"host": "lab.megalania.io", "price": 1, "tier": 1,
           "quotes": {"datacenter": 1, "residential": 8, "browser": 15, "browser_residential": 32}},
 "success": {"days": 7, "requests": 159,
             "breakdown": [{"engine": "http", "tier": "datacenter", "block_share": 0.0}]}}

Our balance was the same before and after the call. With REST, the same answers are GET /v1/tier and GET /v1/stats/domain, also free. Now the agent knows a plain page costs 1 credit here and a browser page 15, before it spends anything. More on the setup in Give your AI agent web access with an MCP server.

Cap each page: max_credits

max_credits is the most one page may cost. We skip every route above it. If no route is left, the answer is a 400 before any try:

cURL
curl -s -H "Authorization: Bearer $MEG_API_KEY" \
  "https://get.megalania.io/v1?url=https://lab.megalania.io/deals/&engine=browser&max_credits=8"
Output, report link cut
{"error":{"code":"max_credits_too_low","field":"max_credits","message":"max_credits is below the lowest price on this site, 15 credits. You are not charged. Raise max_credits to at least 15, or remove it."}}

No X-Credits-Charged, and our balance did not move. The message names the lowest price, so an agent can decide to stop, or to ask you.

A page whose bytes would cost more than max_credits is not refused: it comes back cut at the bytes the cap pays for, with X-Truncated: max_credits. Either way, one page never costs more than the cap.

Free beta, by invite76,000 credits for 30 days, no card. Apply, and we email your invite.Apply for the beta

Cap each run: a budget in your tool

A cap per page does not stop a loop. Twenty pages at 1 credit is still 20 credits. So keep a budget for the run in the tool your agent calls, and send what is left as max_credits. The tool can never spend more than the budget, whatever the model asks:

budget.py
import os

import requests

H = {"Authorization": f"Bearer {os.environ['MEG_API_KEY']}"}
left = 20


def read_page(url, page_cap=8, **params):
    global left
    cap = min(page_cap, left)
    if cap < 1:
        return "stopped: this run spent its credits"
    r = requests.get("https://get.megalania.io/v1", headers=H, timeout=90,
                     params={"url": url, "response_types": "markdown", "max_credits": cap, **params})
    spent = int(r.headers.get("X-Credits-Charged", 0))
    left -= spent
    if r.status_code != 200:
        return f"{r.status_code} {r.json()['error']['code']}, {spent} credits"
    return f"{r.status_code} {r.headers.get('X-Cache')}, {spent} credits"


pages = ["https://lab.megalania.io/shop/", "https://lab.megalania.io/deals/"]
print("browser:", read_page(pages[1], engine="browser"), "| left", left)
for i in range(25):
    print(i + 1, read_page(pages[i % 2]), "| left", left)

The loop plays a stuck agent: it reads the same two pages 25 times. What it printed, with the middle cut:

Output
browser: 400 max_credits_too_low, 0 credits | left 20
1 200 miss, 1 credits | left 19
2 200 miss, 1 credits | left 18
3 200 hit, 1 credits | left 17
...
19 200 hit, 1 credits | left 1
20 200 hit, 1 credits | left 0
21 stopped: this run spent its credits | left 0
...
25 stopped: this run spent its credits | left 0
  • The browser call was free. The cap of 8 is below the 15 the browser costs here.
  • The run spent 20 credits, not 25. From call 21, the tool answers without a request.
  • Repeats hit our cache. Calls 3 to 20 got a copy fetched in the last 5 minutes (X-Cache: hit). A hit costs the cache price of your plan, never more than the fetch it copies. Here the fetch was 1 credit, so the hit was too. On the browser route the gap is large: we fetched the FAQ page with the browser for 15 credits, then the same request again, a hit, for 1.

Return the “stopped” text to the model as the tool’s answer, so it stops and answers with what it has. Keep your framework’s step limit too, like stopWhen: stepCountIs(5) in the AI SDK.

Caps our tools set for you

Our agent tools already do part of this. The model cannot change these numbers; you set them when you make the tools:

Package Per page Per batch call
@megalania/ai-sdk maxCredits, default 128 maxPages, default 100
langchain-megalania max_credits, default 128 max_pages, default 100

The Vercel AI SDK post shows a call that asked for max_credits: 100 and still met the cap of 8. In LangChain, the cap works the same way. These are caps per page and per batch, not per run. For a run, use the budget above.

On our MCP server, max_credits is an argument of scrape, extract, create_batch and the other fetching tools, and the model fills it. A client like Claude or Cursor has no budget of its own there. That is why the next limit exists.

Cap the month: the spend cap

The account owner can set the most credits the account may spend in one UTC month:

cURL
curl -s -X PATCH "https://api.megalania.io/v1/account" \
  -H "Authorization: Bearer $MEG_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spend_cap": 50000}' | jq .caps.spend_cap
  • A request that would take the month past the cap answers 402 spend_cap, for free. A batch item ends failed with the same error.
  • It needs an account key (meg_ak_) from an owner. A member can read the cap but not change it.
  • Set alerts.webhook_url on the account, and we send a signed POST at 50, 80 and 100% of the cap, and once when a request is stopped.
  • It resets at 00:00 UTC on the 1st. The dashboard sets it on Plan and billing too.

We read caps.spend_cap on our test account with GET /v1/account, which is free. No cap was set there, so this run did not hit a 402.

The spend cap is per account. There is no budget per key today. So give each agent its own key, and keep the budget in its tool. A key you revoke stops working in about 1 second.

What is free, and what is not

Call Credits
check_site, GET /v1/tier, GET /v1/stats/domain 0
get_usage, GET /v1/account 0
A request over max_credits (400 max_credits_too_low) 0
A request over the spend cap (402 spend_cap) 0
A block we detect, and every error of ours 0
A page from the Lab, datacenter route 1
A copy from our cache, of a 1-credit page 1
The FAQ page with the browser, fresh 15
The same, again within 5 minutes (cache hit) 1
A page that does not exist (the target’s 404) 1

The Lab does not block anyone, so this run saw no block. A block we detect answers 422 blocked with X-Billing: blocked, and costs 0. Two more limits come with every plan: a daily usage limit (429 daily_cost_cap), and a daily share of free failed browser and residential tries (429 free_failures_spent). Both reset at 00:00 UTC. All the rules are in Credits. Plans are on the pricing page.

Watch what it spent

Every answer has X-Credits-Charged, so your tool can count. To ask after the fact, the agent can call get_usage on our MCP server, for free. It returns your balance, the credits held by work still running, today’s free failures, and one row per site: requests, pages delivered, pages blocked, credits, and credits per page delivered. The same rows are GET /v1/account/sites and the dashboard’s Usage page.

If an agent should read prices on a store, give it rules, not whole pages: Scrape product prices with an AI agent gets 8 products for 2 credits.

How we measured: our dev cluster on 16 Nov 2026, the Lab store on our dev domain. budget.py ran once, with Python 3 and requests 2.32.3. check_site and get_usage were called once each over our MCP server, with get_usage before and after check_site. The browser fetch, the cache hit and the 404 were single GET /v1 calls.

Limits

  • The budget in budget.py lives in one process. Two workers need a shared counter, or one key each with its own budget.
  • A cache hit is not free. It costs the cache price. Only the first fetch of a costly page saves much.
  • The spend cap counts the whole account, monitors and batches too. It is not a budget for one agent.
  • We cannot stop a model from asking. We can only make the answer cheap, or zero.

Fetch public pages only. Read the site’s terms and robots.txt, and follow them.

Jordan HayesDeveloper RelationsPublished 16 Nov 2026 · measured on our dev cluster, 16 Nov 2026, 25 requests to our test store and 2 free MCP tool calls

See also

Keep reading