Agents decide at run time how many calls a task needs, so the bill depends on model behaviour as much as on traffic. A model that keeps refining a query or loops on an empty result makes more calls than you planned. Per-call pricing is fine. The unbounded loop is the problem, and the fix is a ceiling the loop can't pass.

Prepaid credits help because the account itself has a ceiling. The service is prepaid: purchased credits last 12 months, with no subscription and no seats. When the balance runs out, calls return insufficient_credits (402) and nothing more is debited, so a runaway agent stops at the balance you loaded. A per-run cap keeps one run from eating that whole balance.

How do you calculate credits per agent task?

Count the calls one task needs, multiply by the credits per call, and keep two figures: the typical case and the capped worst case. For endpoints that cost 1 credit, calls and credits are the same number. Check the cost shown on each endpoint you give the agent, because the cap should be in credits if any endpoint costs more than 1.

Take an example agent that answers a research question. Assume it typically makes 8 calls per task and you cap it at 20. These are example figures for the arithmetic, not measurements. Per run, that's 8 credits typical and 20 credits worst case.

Run counts follow from the credits. The free tier's 1,000 credits cover 125 typical runs (1,000 ÷ 8) or 50 capped runs (1,000 ÷ 20). The Starter pack's 12,500 credits cover 1,562 typical runs or 625 capped runs. At 500 tasks a month, typical spend is 4,000 credits, and the cap bounds the worst case at 10,000 credits, which fits inside the Starter pack's 12,500.

Why don't failed calls count against the budget?

A failed call returns an HTTP status, a JSON error body and the header X-Credits-Used: 0. Only a successful response debits credits. So the retries an agent makes after a rate_limited (429, the status RFC 6585 defines for too many requests) or source_error (502) response don't change the credit total.

Take a run that makes 8 successful calls and hits 3 errors along the way: 8 credits, not 11. The three failed attempts cost nothing in credits. They still cost time and model tokens, so they should count toward a separate attempt cap.

That second cap matters. An agent that retries an invalid_parameters (422) response forever will never be billed for it, and it will never finish either. See the error reference and the rate limit docs.

How do you build AI agent API cost control in code?

Put the cap in the function that executes the agent's tool calls. The wrapper below counts credits and attempts, refuses to send a request that would pass either limit, and raises BudgetExceeded so the agent loop stops and returns what it has. It counts each successful call at the endpoint's listed cost, which you pass in as credits_per_call.

import os
import requests


class BudgetExceeded(Exception):
    pass


class CallBudget:
    def __init__(self, max_credits, max_attempts, credits_per_call=1):
        self.max_credits = max_credits
        self.max_attempts = max_attempts
        self.credits_per_call = credits_per_call
        self.spent = 0
        self.attempts = 0

    def call(self, url, params=None, method="GET"):
        if self.spent + self.credits_per_call > self.max_credits:
            raise BudgetExceeded(f"credit cap reached: {self.spent}/{self.max_credits}")
        if self.attempts >= self.max_attempts:
            raise BudgetExceeded(f"attempt cap reached: {self.attempts}/{self.max_attempts}")

        self.attempts += 1
        try:
            response = requests.request(
                method,
                url,
                params=params,
                headers={"X-API-Key": os.environ["API_KEY"]},
                timeout=30,
            )
        except requests.RequestException as error:
            raise BudgetExceeded(f"request failed, stopping the run: {error}") from error
        if response.status_code == 402:
            raise BudgetExceeded("account is out of credits")
        if response.ok:
            self.spent += self.credits_per_call
        return response

Use one CallBudget per run and hand its call method to the agent as the only way to reach the API.

budget = CallBudget(max_credits=20, max_attempts=30)
url = os.environ["ENDPOINT_URL"]  # copied from the endpoint's page

try:
    response = budget.call(url, params={"q": "example"})
    print(response.status_code, f"{budget.spent} credits spent")
except BudgetExceeded as stop:
    print("stopping the run:", stop)

A timeout or connection error counts as an attempt and ends the run cleanly instead of crashing the loop. The credit count is a local estimate: it adds the endpoint's listed cost for each successful response and doesn't read anything from the response. Treat it as a ceiling check, and compare it with the X-Credits-Remaining header, which every successful response carries with your balance after the call.

Set max_attempts above max_credits so a few free failures can retry, and keep the gap small. Here 20 credits allow 20 successful calls, and the 10 extra attempts allow up to 10 failures before the run stops. See also the requests docs.

What changes when the agent calls through MCP?

The MCP server at https://api.perceptlayer.com/mcp exposes three tools, search_endpoints, get_endpoint and call_endpoint. search_endpoints and get_endpoint only look things up in the catalogue and cost nothing, so call_endpoint is the one tool that needs a budget check. A successful call_endpoint costs the credits shown on its endpoint, failed calls cost nothing, and its result reports the credits used and the balance remaining. The MCP docs cover the tools.

The cap needs your own agent loop, because the loop is where tool calls get executed. Route every call_endpoint the model requests through a budget check, and let the loop stop when it raises. The sketch below assumes your MCP client gives you a function send_call_endpoint(arguments) that runs the tool and returns its result; credits_per_call is the cost listed on the endpoint.

class McpBudget:
    def __init__(self, max_credits, credits_per_call=1):
        self.max_credits = max_credits
        self.credits_per_call = credits_per_call
        self.spent = 0

    def call_endpoint(self, send_call_endpoint, arguments):
        if self.spent + self.credits_per_call > self.max_credits:
            raise BudgetExceeded(f"credit cap reached: {self.spent}/{self.max_credits}")
        try:
            result = send_call_endpoint(arguments)
        except Exception as error:
            raise BudgetExceeded(f"tool call failed, stopping the run: {error}") from error
        if not getattr(result, "isError", False):
            self.spent += self.credits_per_call
        return result

MCP marks a failed tool call with isError in its result (see the MCP tools specification), which is what the wrapper checks before counting credits. In the loop, when the model asks for call_endpoint, call budget.call_endpoint(...) instead of the client directly. Catch BudgetExceeded outside the loop and return what the agent has so far. As with the HTTP wrapper, the credit count is a local estimate, not a figure read from the response.

The related walkthrough, Claude MCP Web Search: Live Results for an Agent, shows the tools in use.

How should you size a balance for an agent?

Size the balance for the capped worst case, then watch the typical case. Take runs per month × cap × credits per call. For 500 runs capped at 20 calls, that's 10,000 credits, which the Starter pack's 12,500 credits cover for $10. For 5,000 runs, it's 100,000 credits at the cap and 40,000 at 8 calls per run. One Growth pack (83,000 credits, $50) covers the typical 40,000. Two Growth packs (166,000 credits, $100) cover the 100,000-credit worst case. A Scale pack ($200) holds 400,000 credits at a lower rate per call, so it only pays off if you'll use most of it within the 12 months credits last.

Start on the free tier. Every month after you verify an email address you get 1,000 free credits, with no credit card, which is enough to measure your real calls per task with a cap in place.

The credits docs and the pricing page have the details and the packs. Get a free API key, add the wrapper above, and run 20 tasks before you decide on a pack. More agent guides are in the AI agents category.

You need a Perceptlayer API key, the claude CLI or the Claude Agent SDK for Python, and an environment variable holding the key. Keys start with sk_live_. Every account gets 1,000 free credits each month after verifying an email address, with no credit card, so you can run everything below without paying. Get a free API key first, then export it.

export API_KEY="sk_live_..."

The same key authenticates plain HTTP calls with the X-API-Key header and the MCP server with an Authorization: Bearer header. The authentication docs cover both, plus the api_key query parameter for cases where headers aren't possible.

How does a Claude agent search the web over MCP?

The Model Context Protocol lets an agent discover and call tools on a remote server. Perceptlayer's server speaks Streamable HTTP, the protocol's standard transport for remote servers, and gives the agent access to a catalogue of 248 websites and 1,659 endpoints, all returning JSON.

The server's tools are search_endpoints, get_endpoint and call_endpoint. The MCP section of the docs describes the server, and the protocol site describes MCP itself.

Step 1: How do you add the MCP server to Claude Code?

Run one command. It registers the server under the name perceptlayer, using the HTTP transport and your key as a Bearer token. Claude Code stores the entry in its MCP configuration.

claude mcp add --transport http perceptlayer https://api.perceptlayer.com/mcp \
  --header "Authorization: Bearer $API_KEY"

Confirm the server connected:

claude mcp list

You should see perceptlayer in the list. Inside a Claude Code session, the /mcp command shows the connection status of the server. If you want the entry scoped to a project instead of your user, the Claude Code MCP documentation lists the scope options.

Ask a question that needs live search

Start claude and ask something the model can't know from training, such as: "Use Perceptlayer to search Google for the latest Claude Code release notes and list the top five result titles with their URLs."

If Claude Code prompts you about the MCP tools, allow search_endpoints, get_endpoint and call_endpoint so the agent can reach the Google Search endpoint.

Step 2: Which Google Search endpoint should the agent use?

The Google Search API has 7 endpoints, and every one costs 1 credit per successful call. For an agent answering open questions, start with /v1/google-search/search, which takes a required query and optional parameters for country (gl), language (hl), result count and paging. The others fit narrower jobs, so tell the agent which to prefer if you care.

Note that google-ai-mode-search uses q where the others use query. A hard-coded script needs to get that right. The Google Search API page lists all seven, including search-advanced and search-advanced-place, and the search engines hub shows related sources.

Step 3: How do you check the endpoint outside the agent?

Call the endpoint directly with cURL before trusting an agent with it. If the request works from your terminal, any later failure is in the agent's prompt or tool use, not in the data call. The -i flag prints the response headers so you can see the status.

curl -i "https://api.perceptlayer.com/v1/google-search/search?query=claude%20code%20release%20notes" \
  -H "X-API-Key: $API_KEY"

The endpoint returns the search results as JSON. To see a real response for your own query before you wire up the agent, run it in the playground on the Google Search API page, which calls the endpoint with your key and shows the result; the Search endpoint page lists every parameter.

Break the call on purpose to see the failure shape. Send a bad key and you get HTTP 401 with a body like {"error": {"code": "invalid_api_key", ...}}, and the response carries X-Credits-Used: 0. The errors section of the docs lists every code.

Step 4: How do you build a Python agent that uses the server?

Use the Claude Agent SDK, point mcp_servers at the Perceptlayer URL, and allow the three tools by name. The script below asks one question, prints the answer, and counts how many times the agent called call_endpoint. The script counts every call_endpoint call and assumes 1 credit each, which holds for every Google Search endpoint and for nearly all others. It doesn't count search_endpoints or get_endpoint calls, and it counts failed calls too, which are free. Treat the total as an estimate, not a bill.

Install the SDK with pip install claude-agent-sdk, then save this as agent.py:

import asyncio
import os

from claude_agent_sdk import (
    AssistantMessage,
    ClaudeAgentOptions,
    TextBlock,
    ToolUseBlock,
    query,
)

QUESTION = "What changed in the latest Claude Code release? Cite the result URLs you used."

SYSTEM_PROMPT = (
    "You answer questions with live web search. "
    "Use the perceptlayer MCP tools to find and call a Google Search endpoint. "
    "Make at most 3 search calls per question. Cite the URLs you relied on."
)

OPTIONS = ClaudeAgentOptions(
    system_prompt=SYSTEM_PROMPT,
    mcp_servers={
        "perceptlayer": {
            "type": "http",
            "url": "https://api.perceptlayer.com/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['API_KEY']}"},
        }
    },
    allowed_tools=[
        "mcp__perceptlayer__search_endpoints",
        "mcp__perceptlayer__get_endpoint",
        "mcp__perceptlayer__call_endpoint",
    ],
)

CREDITS_PER_CALL = 1  # every Google Search endpoint costs 1 credit; failed calls cost 0


async def main():
    data_calls = 0
    async for message in query(prompt=QUESTION, options=OPTIONS):
        if not isinstance(message, AssistantMessage):
            continue
        for block in message.content:
            if isinstance(block, ToolUseBlock) and block.name.endswith("call_endpoint"):
                data_calls += 1
            elif isinstance(block, TextBlock):
                print(block.text)
    print(f"\ndata calls: {data_calls}, credits (estimate): {data_calls * CREDITS_PER_CALL}")


asyncio.run(main())

The Agent SDK documentation covers the options used above.

Step 5: What does the script print?

Run it with python agent.py. The agent's answer text prints as it arrives, followed by one summary line in this format, where each <n> is a number from your run:

data calls: <n>, credits (estimate): <n>

Compare that number with the cap in the system prompt. If the count is higher than the cap, tighten the prompt.

Why cap the number of search calls?

Each successful search call costs 1 credit, so the number of calls sets the credit cost of a question. The prompt line "at most 3 search calls per question" bounds that spend at 3 credits, and the counter shows whether the agent respects it. Treat the cap as a guardrail, not a guarantee, and check the printed count while you tune the prompt.

What does each question cost?

A successful call_endpoint call to a Google Search endpoint costs 1 credit, so an agent that searches twice spends 2 credits. The figures below count only those search calls; they leave out search_endpoints and get_endpoint calls. The free tier of 1,000 credits a month covers 1,000 search calls, and purchased credits last 12 months with no subscription and no seats. The table below counts Perceptlayer credits only. Claude model tokens are billed separately by Anthropic, so the real cost of a question is higher than the credit figure.

Packs are bought whole. The Starter pack is $10 for 12,500 credits, an effective $0.80 per 1,000 calls, and it covers the 10,000 calls in the third row. The Growth pack is $50 for 83,000 credits, an effective $0.60 per 1,000 calls, and it covers the 15,000 calls in the last row. The Scale pack is $200 for 400,000 credits, or $0.50 per 1,000 calls. The pricing page has all three, and the credits section of the docs explains how a call is billed.

Because failed calls are free, a rate-limited or erroring call doesn't add to the total. Only a successful response debits credits.

What happens when a call fails?

A failed call returns an HTTP status and a JSON body with error.code, error.message and error.request_id, and it costs nothing. Give the agent a rule for each case in the system prompt so it knows whether to retry, change the query, or stop, and doesn't loop.

Add a sentence such as "If a tool call fails with insufficient_credits or invalid_api_key, stop and say so" to SYSTEM_PROMPT. Retries on the transient codes are safe for your balance because failures aren't billed.

Next step: point the same server at more sources

The server isn't limited to Google Search. The same key and the same three tools reach the rest of the catalogue, so the agent can move from a search result to a listing, a review page or a price without a new integration. Some endpoints, covering social, personal and SEO data, need you to accept the restricted-endpoint terms in the dashboard first.

Add the server with the command in step 1, ask your agent a question that needs live data, and check the credit count it prints. To read more about how agents pick and call endpoints, see the MCP docs, and for a worked example of one data source end to end, read how to get Zillow listings as JSON.

Zillow Group runs a developer site that lists APIs for MLS listings, rentals feeds, public data and Zestimates, offered to the public and to partners. Those programs have their own terms and eligibility. If your use fits one, check that route first, because it's the authoritative one.

If you aren't, or you need a plain search-by-location call returning JSON today, that's the gap the Perceptlayer Zillow API fills. It exposes 10 endpoints under one key, with the same authentication and credit model as every site in the catalogue: Zillow is one of 248 websites and 1,659 endpoints in the catalogue.

Data is collected from publicly available sources and returned as found at the time of the call. Listing fields can change between calls, so store the timestamp of each pull.

How do you get a key and make the first call?

Sign up, verify your email and copy a key that starts with sk_live_. Send it in the X-API-Key header on every request. If you can't set headers, the api_key query parameter works instead. The free tier is 1,000 credits a month, enough for 1,000 Zillow calls, so you can run everything below without paying. The authentication docs cover both options.

Get a free API key, export it, then run this search for listings within 5 miles of a point in Seattle (latitude 47.6062, longitude -122.3321):

export API_KEY=sk_live_your_key_here

curl "https://api.perceptlayer.com/v1/zillow/search?latitude=47.6062&longitude=-122.3321&radius_mi=5&listing_category=category1&page_size=20" \
  -H "X-API-Key: $API_KEY"

The response is JSON with a data object. The listings sit in data.listings, one object per property. The requests docs explain the general conventions that apply to every endpoint.

Which parameters does the search endpoint take?

/v1/zillow/search has no required parameters, but you'll always want to say where to look. Use a centre point with radius_mi, a bounding box made of four coordinates, region_ids[], or a polygon string. Everything else narrows the results by price, size, status or keyword. The table groups all 29 parameters by job.

sort_order accepts one of baths, yearBuilt, price, relevance, beds, daysOn, featured, livingArea, lotArea, nearby, recentlyChanged, rentalDays or rentalPriorityScore.

The reference doesn't say what category1 and category2 select, so try each on your area and compare the results before you build on one. The example request above uses category1.

Narrowing the search

Add filters as plain query parameters. This request asks for homes with at least 3 bedrooms and 2 bathrooms between $500,000 and $900,000, sorted by price:

curl "https://api.perceptlayer.com/v1/zillow/search?latitude=47.6062&longitude=-122.3321&radius_mi=5&min_price=500000&max_price=900000&min_beds=3&min_baths=2&sort_order=price&sort_ascending=true&page_size=20" \
  -H "X-API-Key: $API_KEY"

A tight filter can return few or no listings, so loosen one filter at a time if a search comes back thin. The search endpoint also takes an allow_empty boolean.

What does a search response look like?

The response wraps results in data.listings. Each listing carries a zpid (the property ID), a location, an address, a media block with photo links, and the facts a valuation or lead tool needs: bedrooms, bathrooms, livingArea, yearBuilt, propertyType, a listing status object and a price object. This is a trimmed excerpt of a recorded response to the Seattle request above:

{
  "data": {
    "listings": [
      {
        "zpid": 2068074790,
        "location": {
          "latitude": 47.592564,
          "longitude": -122.386925
        },
        "address": {
          "streetAddress": "1124 Sunset Avenue SW",
          "zipcode": "98116",
          "city": "Seattle",
          "state": "WA"
        },
        "media": { … },
        "currency": "usd",
        "country": "usa",
        "bestGuessTimeZone": "America/Los_Angeles",
        "bathrooms": 6,
        "bedrooms": 4,
        "livingArea": 7870,
        "yearBuilt": 2015,
        "lotSizeWithUnit": {
          "lotSize": 0.2652,
          "lotSizeUnit": "acres"
        },
        "propertyType": "singleFamily",
        "listing": {
          "listingStatus": "forSale",
          "marketingStatus": "active",
          "palsId": "39001_2591845"
        },
        "price": {
          "value": 14000000,
          "pricePerSquareFoot": 1779
        …

Field names are camelCase and nested. Price is at price.value, the street at address.streetAddress, and the lot size is an object with a value and a unit. The excerpt also holds media flags and recommendation blocks that we've cut with …. Treat any field you don't see in your own response as absent, and check for it in code rather than assuming it's there.

How do you fetch one property by ID?

Take the zpid from a search result and pass it to /v1/zillow/property. The endpoint has no required parameters and accepts a zpid[] list. Per-endpoint pages, such as Zillow API: Property, list the parameters and let you try the call.

curl "https://api.perceptlayer.com/v1/zillow/property?zpid[]=2068074790" \
  -H "X-API-Key: $API_KEY"

We haven't recorded a property response for this guide, so we won't show one. Run the call on your own key and inspect the JSON before you map fields.

The other Zillow endpoints follow the same pattern:

How do you call it from Python?

The same request in Python needs only requests. This script searches around the same Seattle point, then prints address, bedrooms and price for each listing. It reads the key from the environment and checks the status before parsing, so a failed call raises an error instead of returning bad data.

import os
import requests

resp = requests.get(
    "https://api.perceptlayer.com/v1/zillow/search",
    headers={"X-API-Key": os.environ["API_KEY"]},
    params={
        "latitude": 47.6062,
        "longitude": -122.3321,
        "radius_mi": 5,
        "listing_category": "category1",
        "page_size": 20,
    },
    timeout=30,
)
resp.raise_for_status()

for item in resp.json()["data"]["listings"]:
    print(
        item.get("zpid"),
        (item.get("address") or {}).get("streetAddress"),
        item.get("bedrooms"),
        (item.get("price") or {}).get("value"),
    )

To page through more results, increase page and keep page_size fixed. Each page is its own call and its own credit, so pick the smallest page_size that covers your need.

What does it cost per 1,000 calls?

Every Zillow endpoint costs 1 credit per successful call, so 1,000 search calls use 1,000 credits. Failed calls cost nothing and come back with X-Credits-Used: 0. The free tier of 1,000 credits a month covers 1,000 calls. Beyond that, purchased credits last 12 months, with no subscription and no seats. The credits docs and pricing page have the detail.

A worked example: refreshing 10 search areas twice a day for 30 days is 10 × 2 × 30 = 600 calls, or 600 credits, which fits inside the free tier. A job making 10,000 calls a month uses 10,000 credits, within the Starter pack's 12,500, at $0.80 per 1,000 calls.

What happens when a call fails?

A failed call returns an HTTP status and a JSON body shaped as {"error": {"code", "message", "request_id"}}, and it isn't billed. The codes you'll most likely meet are invalid_api_key (401), insufficient_credits (402), invalid_parameters (422), rate_limited (429) and source_error (502). The errors docs list all of them.

Handle them by code, not by message text. Retry rate_limited, source_error and temporarily_unavailable (503) with a growing delay between attempts. A 429 is the standard "too many requests" status, defined in RFC 6585 (2012). Fix invalid_parameters before you retry, since repeating the same request will fail the same way. See the rate limits docs for the limits on your key.

Can an AI agent call these endpoints?

Yes. The MCP server at https://api.perceptlayer.com/mcp exposes search_endpoints, get_endpoint and call_endpoint, so an agent can find the Zillow search endpoint and call it without custom glue code. In Claude Code, add it with the command below, then ask for listings in a city. The MCP docs cover other clients.

claude mcp add --transport http perceptlayer https://api.perceptlayer.com/mcp --header "Authorization: Bearer $API_KEY"

Only successful calls are billed and failed calls cost nothing, so cap the number of calls a task may make. For more real estate sources, see the real estate APIs.

Ready to try it? Get a free API key, run the Seattle search above, and check the Zillow API page for the other nine endpoints.