Skip to main content
View on GitHub → Website intelligence, spent deliberately. The skill contains no endpoint parameters or prices. The agent reads parameters from the live Similarweb contract, gets a free quote before each call, sends the approved amount as an admission check, and reports the actual cost afterward.

​
Install

After installing, start a new agent session so the skill loads.

​
What can agents do with it?

Domain traffic

“How many visits did cnn.com get last month? Quote it first.”

Competitors and search

“Who are nike.com’s keyword competitors and which landing pages win?”

Audience and sources

“Show cnn.com’s referral sources and its audience overlap with bbc.com. Ask me before spending.”

Site footprint

Technologies, popular pages, subdomains, top geographies, PPC spend, and ad networks.

​
Requirements

  • Python 3
  • An AIsa account with balance; Similarweb calls are pay-as-you-go. The Go-to-Market plan is optional.
  • Requests go to https://api.aisa.one/apis/v1/similarweb with Authorization: Bearer $AISA_API_KEY.

​
Quick start

ROUTE is a path from discover, without the /similarweb prefix. Every name=value comes from describe. call without --max-usd only quotes.

​
The protocol

Discover at session start, and again whenever a contract-built request is rejected:
  1. discover downloads the contract from https://aisa.one/docs/openapi/similarweb.json and caches it (revalidated with its ETag; --refresh forces a new copy).
  2. describe ROUTE shows required and optional parameters, enums, defaults, maximums, and date-window rules.
  3. window finds the latest complete data month.
Call, for every request:
  1. Build the smallest request that answers the question and check it.
  2. quote it (free, via X-AISA-Cost-Mode: quote).
  3. To widen months, metrics, rows, or domains, quote the wider variant too and pick the cheapest one that answers the question.
  4. Show the quote and get approval against your budget.
  5. call … --max-usd <approved> sends X-AISA-Max-Price-USD and an Idempotency-Key. The header rejects a call whose pre-execution estimate is above the approved amount; it does not cap the final charge on usage-metered routes (see Quote, review, then execute). Before approving, check the route’s billing rules on its API reference page to confirm the maximum possible charge, and set a spending limit on the key as the hard ceiling.
  6. Report cost_usd (from the x-aisa-customer-cost-micros-usd header) and data_month, and reconcile with usage.
call prints JSON with status, quoted_usd, cost_usd, request_id, latency_s, data_month, note, and data.

​
Reading responses

Before retrying a 503, check the original request in Usage & Logs or your balance. Retry only once you know it did not complete; keep the same Idempotency-Key and payload unless the endpoint’s rules say otherwise, since a new key can create a second billed call. See Retry guidance. Never retry a 200. Make paid calls over REST, where the cost header is returned.

​
When to use

Use this skill when the question is about a website’s traffic, audience, sources, technology, or search footprint. For keyword volumes and difficulty, use SEO Keyword Research (DataForSEO) or the Semrush APIs; for backlinks, use the Ahrefs APIs.

​
Get started

  1. Sign up at aisa.one, add balance (or optionally subscribe to the Go-to-Market plan), and create an API key in the console.
  2. Set it in your shell: export AISA_API_KEY="your-key".
  3. Install the skill with one of the commands under Install, then start a new agent session.

Similarweb API reference

Every Similarweb route with its parameters.

Quotes and charges

Quote mode, price caps, and the cost header.

Product Selection

Uses Similarweb for channel fit in product research.