Back to Blog
Use this skill to cut down your GTM costs by 20%

Use this skill to cut down your GTM costs by 20%

TutorialsSeptember 14, 2026·Haoyang

AIsa's Similarweb endpoints now quote the cost of a call before you pay for it. Here is the cheat sheet to paste into your agent, the installable skill, and five real runs where it cut agent run time by 18% and cost by 24%.

AIsaSimilarwebagent skillscost quotingspending controlsbudgetAI agentsClaude Code

We recently collaborated with Similarweb to provide high-quality market data to our users. However, many users have reported that the cost per API call is hard to predict, and their agent often misunderstands how to construct an effective call.

Today that changes. We've built a cost-quoting mechanism into our API endpoints, so your agent knows how much it will spend before any actual charges are incurred.

We've packaged this capability in three formats you and your agent can use:

  1. A copy-and-paste-ready cheat sheet: just send it to your agent, and it will know how to construct cost-effective Similarweb calls from then on.
  2. An installable skill with pre-built workflows your agent can use out of the box.
  3. An experiment we've run so you can see, intuitively, how much better your agent would perform with a customized skill.

Now let's dig in ⬇️

Similarweb cheat sheet

Copy the text below directly to your agent; it can then estimate API costs before actually running them.

AIsa × Similarweb — protocol for agents

Base `https://api.aisa.one/apis/v1/similarweb` · header `Authorization: Bearer $AISA_API_KEY` · the account needs the Hive GTM subscription.

COST RULE — never state or assume a price. Prices come only from a quote (before a call) or the cost header (after).

CONTRACT RULE — never assume a parameter. Build every request from the live contract.

DISCOVER — at session start, and again whenever a request built from the contract is rejected

1. Contract (public): GET `https://aisa.one/docs/openapi/similarweb.json`. Cache it with its ETag and revalidate with `If-None-Match` (304 = unchanged). On MCP, `tools/list` on `https://mcp.aisa.one/similarweb/mcp` returns the same schemas.
2. For each route, read its required parameters, enums, defaults, maximums, and description — date-window rules are written there.
3. Latest month M (free): take the route whose description requires the latest month (e.g. `/website/technologies`), send its required parameters with the dates set to `2000-01` → 400 whose `meta.error_message` names the allowed month.

CALL — every request, in order

4. Build the smallest request that answers the question: the fewest months, metrics, and rows the contract allows.
5. Quote it (free): same request + header `X-AISA-Cost-Mode: quote` → `estimated_cost_micros_usd` (1000000 = $1). A 400 on a contract-built request means the contract changed: re-fetch (step 1) and rebuild.
6. Before widening scope (months, metrics, rows, domains), quote the wider variant too; pick the one that answers the question at the lowest quote.
7. Show the user the quote; if it exceeds their budget (ask for one if none is set), wait for approval.
8. Call with headers `X-AISA-Max-Price-USD: <approved USD>` and `Idempotency-Key: <uuid>`. 402 = estimate above the cap, 409 = key already used; neither is billed.
9. Report the cost from response header `x-aisa-customer-cost-micros-usd` and the data month (`meta.last_updated` or `meta.end_date`). Reconcile spend with GET `https://api.aisa.one/v1/usage?start_time=<unix>`.

READING RESPONSES — the errors below are not billed

- 400 with `meta.error_message` on a real call: a date-window rule that quotes do not check. The message states the rule or the allowed range; use it to fix the dates and retry.
- 400 with `error.supported`: `error.message` names the parameter and `supported` lists the valid values.
- 503 with `retryable: true`: retry once with a new Idempotency-Key. Never retry a 200.
- Make paid calls over REST: that is where the cost header is returned.

AIsa × Similarweb protocol card for agents: discover, quote, then pay

Similarweb skill

We've also pre-packaged a skill that includes the protocol described above, along with executable scripts so your agent can make more precise calls to Similarweb's API endpoints:

github.com/AIsa-team/agent-skills/tree/main/marketing/use-similarweb

If you have any issues using the skill, feel free to reach us at developer@aisa.one; we'll get back to you as soon as possible.

How would your agent perform with vs. without the skill?

We used five real-world use cases to test the skill. Here are the overall results:

  1. Agent run time was reduced by at least 18%
  2. Costs, including Similarweb API costs and model costs, were reduced by 24%

What's more important is that with the skill, your agent is more prudent when spending your money: it quotes the estimated price first and respects the budget you set more rigorously.

Here are the use cases we used:

  • Compare last month's visits, bounce rate, pages per visit, and average visit duration for notion.so, coda.io, and clickup.com
  • Who are linear.app's real competitors? Give me its top 5 similar sites and the top 10 domains that compete with it for search keywords, with whatever scores the API returns.
  • I have a budget of $2 for this. Which countries drive canva.com's traffic, and what is its age and gender mix?
  • How has stripe.com's traffic and engagement trended over the last quarter? I want the trajectory, not just a snapshot.
  • Which parts of ycombinator.com actually get the traffic? Break it down by subdomain.

If you're interested in how the experiment was set up, here is a detailed report generated with Claude using intermediate data we collected during the experiment:

Download the full experiment report (PDF, 13 pages)

Feedback is very welcome! Tell us how we can do better by emailing developer@aisa.one. We'll get back to you ASAP!