use-similarweb

AIsa Similarweb 📡

Similarweb website intelligence for agents — discovered at runtime, spent deliberately. Powered by AIsa.

This skill holds no endpoint parameters and no prices, because both change over time. The agent reads them from the API instead: parameters from the live contract at https://aisa.one/docs/openapi/similarweb.json, cost from a free quote before each call and the cost header after it. A 20-line version of this protocol for pasting into any agent is references/agent-rules.txt.

Requirements

export AISA_API_KEY="sk-aisa-..."

Base URL https://api.aisa.one/apis/v1/similarweb; header Authorization: Bearer $AISA_API_KEY.
The key's account needs the Go-to-Market Plan subscription. https://aisa.one/solutions/go-to-market
Never print or commit the key. If it is missing, ask the user to set AISA_API_KEY.

Quick Start

python3 scripts/similarweb_client.py discover                     # route index from the live contract
python3 scripts/similarweb_client.py describe ROUTE               # one route: parameters, enums, limits, date rules
python3 scripts/similarweb_client.py window                       # latest complete data month
python3 scripts/similarweb_client.py check ROUTE name=value …     # validate against the contract, no API call
python3 scripts/similarweb_client.py quote ROUTE name=value …     # free price estimate
python3 scripts/similarweb_client.py call  ROUTE name=value … --max-usd "$APPROVED_USD"
python3 scripts/similarweb_client.py usage --days 1               # charged USD for reconciliation

ROUTE is a path from discover (without the /similarweb prefix). Every name=value comes from describe. {baseDir}/scripts/similarweb_client.py is the same path in harnesses that substitute {baseDir}.

Two rules

Cost rule — never state or assume a price. Prices come only from a quote (before a call) or the x-aisa-customer-cost-micros-usd response header (after it).
Contract rule — never assume a parameter. Build every request from the live contract.

The protocol

Discover — at session start, and again whenever a contract-built request is rejected

Fetch the contract — discover. It downloads the contract once, caches it with its ETag and revalidates with If-None-Match (a 304 means unchanged). discover --refresh forces a new copy.
Read each route you need — describe ROUTE shows required and optional parameters, enums, defaults, maximums and the route description. Date-window rules are written in the description.
Find the latest data month — window. It finds the route whose description requires the latest month, sends it an old month, and reads the allowed month from the free 400 message.

Call — every request, in order

Build the smallest request that answers the question — the fewest months, metrics and rows the contract allows — and check it.
Quote it — quote (free). A 400 on a contract-built request means the contract changed: the client re-fetches the contract and reports what now differs.
Compare before widening — to add months, metrics, rows or domains, quote the wider variant too and pick the one that answers the question at the lowest quote.
Get approval — show the user the quote. Ask for a budget if none is set; above it, wait for approval.
Call with a cap — call … --max-usd <approved USD> sets X-AISA-Max-Price-USD and an Idempotency-Key. call without --max-usd only quotes.
Report and reconcile — report cost_usd (from the cost header) and data_month; reconcile with usage.

How discovery works

You need	Where it comes from
Routes and parameters	The contract JSON — `discover`, `describe`
Whether a request is valid	`check` against the contract, then a free quote
Date-window rules	The route description, and the message of the free 400 a real call returns if a rule is broken
Latest data month	`window`
Valid values after a 400	`error.supported` in the response
Price before a call	`quote` (`X-AISA-Cost-Mode: quote`)
Actual cost	`cost_usd` (`x-aisa-customer-cost-micros-usd`)
Data month	`data_month` (`meta.last_updated` or `meta.end_date`)
Spend to date	`usage` (`GET /v1/usage`)

Verified on 2026-09-13 across all 23 routes: every request built from the contract alone was accepted, every required parameter was enforced exactly as declared, and every declared optional parameter was accepted. Details, including the MCP alternative: references/discovery.md.

Reading responses

400 with meta.error_message on a real call — a date-window rule quotes do not check. The message states the rule or the allowed range; use it to fix the dates and retry. Not billed.
400 with error.supported — error.message names the parameter, supported lists valid values. Not billed.
402 — the estimate is above your cap. Not billed.
409 — the Idempotency-Key was already used. Not billed.
503 with retryable: true — retry once with a new key. Not billed.
Never retry a 200. Make paid calls over REST, where the cost header is returned.

Cost-control detail: references/cost-control.md.

When to use / when not to

Use when the question is about a website's traffic, audience, sources, technology or search footprint.
For keyword volumes and difficulty use the DataForSEO or Semrush skills; for backlinks, Ahrefs.

Output

call prints JSON: status, quoted_usd, cost_usd, request_id, latency_s, data_month, note (the API's own explanation when a rule or value was rejected) and data (the Similarweb response). Report the data month with every number.

API Reference

Contract: https://aisa.one/docs/openapi/similarweb.json — the source of truth for routes and parameters
Human reference: Similarweb API docs (each page embeds the same contract)
MCP: https://mcp.aisa.one/similarweb/mcp (tools/list returns the same schemas)
Cost control: quote header X-AISA-Cost-Mode: quote · cap header X-AISA-Max-Price-USD · cost header x-aisa-customer-cost-micros-usd · usage GET https://api.aisa.one/v1/usage?start_time=<unix>

See the full AIsa API Reference.

License

MIT — see LICENSE at the category root.