docs: require approval before paid API calls

agent-quickstart.mdx

@@ -10,6 +10,36 @@ This page helps locate the relevant technical source. Reading it is not independ
 
 Goal: get the agent to the smallest verifiable next step without loading broad documentation indexes.
 
+<span id="paid-api-approval-first"></span>
+## IMPORTANT: Paid and high-cost API approval-first contract
+
+This contract applies to every paid, dynamically priced, or potentially high-cost API endpoint, whether invoked directly, through an Agent Skill, or through an MCP data tool.
+
+```xml
+<IMPORTANT id="paid-api-approval-first">
+  <before-paid-data-call>
+    Read the matching endpoint documentation and published pricing declaration.
+    Docs, /v1/models, and capability or MCP discovery are allowed before approval.
+    STOP: a request to collect, research, or report data is not approval. State
+    the exact endpoint and scope, formula or rate, and documented maximum USD
+    exposure; then wait for a separate user message explicitly approving that
+    scope and cap.
+    If a provider-controlled dimension has no documented upper bound, do not
+    execute: an example or user-stated budget is not an enforceable cap.
+  </before-paid-data-call>
+  <prohibited>
+    Do not run a paid data call in the planning turn, use the initial request as
+    consent, or use a paid call to discover price, probe, test, or "just check".
+  </prohibited>
+  <after-approval>
+    Execute only the approved request. If its endpoint, scope, or maximum
+    changes, present the new details and obtain new approval.
+  </after-approval>
+</IMPORTANT>
+```
+
+**Classic example — SimilarWeb:** read the matching endpoint's [`x-aisa-pricing`](https://aisa.one/openapi.yaml) metadata, calculate only a bounded request, and obtain explicit approval before the data call.
+
 ## Minimal setup facts
 
 AIsa provides two endpoint families:

guides/pricing.mdx

@@ -2,15 +2,15 @@
 title: AIsa Pricing – Usage-Based Billing for LLMs & Data APIs
 excerpt: >-
   AIsa pricing overview covering token-based billing for 100+ AI models and
-  flat per-call pricing for search, financial, Twitter, and data APIs. No
-  subscriptions — pay only for what you use.
+  fixed and variable data-API pricing. No subscriptions — pay only for what
+  you use.
 ---
 AIsa uses a usage-based billing system. Charges are applied based on the type of API you use.
 
-There are two distinct pricing models:
+There are two pricing categories:
 
 1. **AI Model (LLM) Pricing:** billed per token
-2. **Per-Call API Pricing:** billed per request
+2. **Data API Pricing:** fixed per request for many APIs; some providers use a credit formula based on request dimensions or returned rows
 
 This page provides a high-level overview of both models and links to their detailed pricing pages.
 
@@ -39,15 +39,15 @@ This pricing model applies to:
 
 For the full model pricing table and detailed billing explanation, see **AI Model Pricing**
 
-## 2. Per-Call API Pricing
+## 2. Data API Pricing
 
-All non-LLM APIs use a fixed per-request billing model.
+Many non-LLM APIs use a fixed per-request billing model. Some data providers have a variable credit-based model instead.
 
 ![Twitter API page on AIsa showing each endpoint with its fixed per-call price](/images/bdd00244-twitter-api-per-call.png)
 
-Each API page lists its endpoints with the price attached to each one — in the Twitter example above, `/apis/v1/twitter/user/last_tweets` is billed at \$0.0036 per call while `/apis/v1/twitter/user/followers` is billed at \$0.036 per call.
+For fixed-price APIs, each API page lists its endpoints with the price attached to each one — in the Twitter example above, `/apis/v1/twitter/user/last_tweets` is billed at \$0.0036 per call while `/apis/v1/twitter/user/followers` is billed at \$0.036 per call.
 
-Each successful request to an endpoint incurs a predefined charge, regardless of response size.
+For those APIs, each successful request to an endpoint incurs a predefined charge, regardless of response size.
 
 This pricing model applies to APIs such as:
 
@@ -58,16 +58,18 @@ This pricing model applies to APIs such as:
 * Twitter APIs
 * Other structured data and retrieval services
 
-For endpoint-level pricing details and billing behavior, see **Per-Call API Pricing**
+For endpoint-level pricing details and billing behavior, see [Per-Call API Pricing](/guides/pricing/per-call-api-pricing).
+
+Some paid data APIs, including SimilarWeb, use a credit formula rather than a fixed per-call price. Read the matching endpoint documentation and pricing declaration before a paid request; if a maximum is not documented, do not execute it under the approval-first contract.
 
 ## Choosing the Correct Pricing Model
 
 If your API request:
 
 * Uses a language model to generate text → **Token-based pricing applies**
-* Retrieves structured data or performs a search → **Per-call pricing applies**
+* Retrieves structured data or performs a search → **Read that API's pricing model**; it may be fixed per call or formula-based.
 
-The Models catalog shows per-token prices, and each API page shows the per-call price of every endpoint.
+The Models catalog shows per-token prices. Fixed-price API pages show per-call prices; formula-priced APIs publish their formula and cost controls with the endpoint documentation.
 
 ## Usage Tracking and Transparency
 

guides/pricing/per-call-api-pricing.mdx

@@ -1,15 +1,19 @@
 ---
-title: Per-Call API Pricing – Search, Financial, Twitter & Data APIs
+title: Per-Call API Pricing – Fixed-Price Search, Financial, Twitter & Data APIs
 excerpt: >-
-  Fixed per-request pricing for AIsa's non-LLM APIs including web search,
-  financial data, Twitter, YouTube, and scholar endpoints. Simple flat-rate
-  billing with no token counting.
+  Fixed per-request pricing for eligible AIsa data APIs including web search,
+  financial data, Twitter, YouTube, and scholar endpoints. Variable-cost data
+  APIs have their own documented cost model.
 ---
-This page explains the pricing model for all non-LLM APIs available through AIsa.
+This page explains the fixed-price model for eligible non-LLM APIs available through AIsa.
+
+<Warning>
+  **IMPORTANT:** This page does not make every data API fixed-price. Some paid data APIs, including SimilarWeb, are priced from request dimensions or returned rows. Read the matching endpoint documentation and published pricing declaration before a paid request, then obtain explicit approval when the cost can be material.
+</Warning>
 
 ![Tavily Search API page on AIsa showing each endpoint with its flat per-call price](/images/6bd32ad1-tavily-search-per-call.png)
 
-These APIs use a **fixed per-request billing model**. Each successful request to an endpoint incurs a predefined charge, independent of response size, token count, or processing time. In the Tavily Search example above, crawl, extract, map, and search each cost \$0.0096 per call regardless of how much data comes back.
+These eligible APIs use a **fixed per-request billing model**. Each successful request to an endpoint incurs a predefined charge, independent of response size, token count, or processing time. In the Tavily Search example above, crawl, extract, map, and search each cost \$0.0096 per call regardless of how much data comes back.
 
 Per-call pricing applies to APIs such as:
 
@@ -47,7 +51,7 @@ If a request fails before processing (for example, due to authentication errors)
 
 Each per-call API endpoint has its own defined cost.
 
-On each API page, every endpoint listing displays:
+On each fixed-price API page, every endpoint listing displays:
 
 * HTTP method and endpoint name
 * API path
@@ -109,6 +113,6 @@ This allows you to:
 * All prices are listed in USD.
 * Billing is triggered per successful API request.
 * There is no token-based billing for these endpoints.
-* Response size does not impact cost.
+* Response size does not impact cost for the fixed-price APIs covered by this page.
 * Pricing may change as endpoints evolve.
 * Refer to the API pages for up-to-date pricing.

llms.txt

@@ -13,6 +13,10 @@ Use this index to choose the smallest relevant documentation set. For product di
 - [Errors](https://aisa.one/docs/api-reference/errors): error formats and handling.
 - [Rate Limits](https://aisa.one/docs/api-reference/rate-limits): limits and relevant headers.
 
+<IMPORTANT id="paid-api-approval-first">
+For any paid, dynamically priced, or potentially high-cost API endpoint, first read the matching endpoint documentation and published pricing source. Docs, `/v1/models`, and capability or MCP discovery are allowed before approval. STOP: a request to collect, research, or report data is not approval. Before a data call, state the exact scope, formula or rate, and documented maximum USD exposure, then wait for a separate user message explicitly approving that scope and cap. If a provider-controlled dimension has no documented upper bound, do not execute: an example or user-stated budget is not an enforceable cap. Do not send an unapproved probe, test, or price-discovery request. SimilarWeb is a classic dynamic-cost example: read its matching `x-aisa-pricing` metadata.
+</IMPORTANT>
+
 ## Navigate by Goal
 
 - [Capabilities by Goal](https://aisa.one/docs/by-goal): choose models, Skills, and APIs from the outcome an agent needs.
@@ -52,6 +56,7 @@ Use this index to choose the smallest relevant documentation set. For product di
 - [Twitter API](https://aisa.one/docs/api-reference/twitter/get_twitter-user-info): X/Twitter read and authenticated write routes.
 - [Scholar API](https://aisa.one/docs/api-reference/scholar/post_scholar-search-scholar): academic and mixed-source search.
 - [Prediction Market API](https://aisa.one/docs/api-reference/prediction-market/get_polymarket-events): Polymarket and Kalshi data.
+- [SimilarWeb API](https://aisa.one/docs/api-reference/similarweb/get_similarweb-website-similar-sites): digital-intelligence data.
 
 ## Machine Discovery
 

zh/agent-quickstart.mdx

@@ -10,6 +10,30 @@ description: >-
 
 目标：让 Agent 走到**最小且可验证**的下一步，而不是一次性加载完整文档索引。
 
+<span id="paid-api-approval-first"></span>
+## 重要：付费和高成本 API 的先批准后执行合同
+
+该合同适用于每一个付费、动态计价或可能高成本的 API endpoint，无论它是直接调用、通过 Agent Skill，还是通过 MCP 数据工具调用。
+
+```xml
+<IMPORTANT id="paid-api-approval-first">
+  <before-paid-data-call>
+    先阅读匹配的 endpoint 文档和公开计价说明。docs、/v1/models 以及 capability 或 MCP
+    discovery 可在批准前查看。停止：用户要求收集、调研或输出数据，不等于批准。明确 endpoint
+    和 scope、公式或费率、已记录的最高 USD 暴露后，必须等待用户在下一条消息中明确批准该 scope 与上限。
+    如果 provider 控制的维度没有已记录的最大上限，不得执行：示例或用户给出的预算都不是可执行的上限。
+  </before-paid-data-call>
+  <prohibited>
+    不得在规划的同一轮调用付费数据 API，不得把初始请求当作同意，也不得为了价格发现、"probe"、"test" 或“先探一下”而调用付费 endpoint。
+  </prohibited>
+  <after-approval>
+    只能执行已批准的请求；如果 endpoint、scope 或最高费用变化，必须重新展示细节并取得新的明确批准。
+  </after-approval>
+</IMPORTANT>
+```
+
+**典型场景 — SimilarWeb：** 请读取匹配 endpoint 的 [`x-aisa-pricing`](https://aisa.one/openapi.yaml) 元数据；只有请求可界定时才计算成本，并在数据调用前取得明确批准。
+
 ## 最小设置事实
 
 AIsa 提供两类端点：

zh/guides/pricing.mdx

@@ -1,15 +1,15 @@
 ---
 title: "AIsa 价格 - LLM 与数据 API 的按量计费"
 excerpt: >-
-  AIsa 价格总览：100+ AI 模型按 token 计费，搜索、金融、Twitter 和数据 API 按次调用计费。无订阅费，只为实际使用付费。
+  AIsa 价格总览：100+ AI 模型按 token 计费，数据 API 可能是固定按次计费或公式计费。无订阅费，只为实际使用付费。
 ---
 
 AIsa 使用按量计费系统。费用会根据你使用的 API 类型计算。
 
-主要有两种计费模型：
+主要有两类计费方式：
 
 1. **AI Model（LLM）价格：** 按 token 计费。
-2. **按次调用 API 价格：** 按请求计费。
+2. **数据 API 价格：** 许多 API 按固定请求计费；部分 provider 按请求维度或返回行数使用 credit 公式计费。
 
 本页提供两种计费模型的高层概览，并链接到对应的详细价格页面。
 
@@ -38,15 +38,15 @@ AI 模型 API 根据 token 用量计费。
 
 完整模型价格表和详细计费说明请查看 [AI 模型价格](/zh/guides/pricing/ai-model-pricing-llm-inference)。
 
-## 2. 按次调用 API 价格
+## 2. 数据 API 价格
 
-所有非 LLM API 使用固定的按请求计费模型。
+许多非 LLM API 使用固定的按请求计费模型；部分数据 provider 则使用可变的 credit 计费模型。
 
 ![AIsa 上的 Twitter API 页面，每个 endpoint 都标注了固定的按次调用价格](/images/bdd00244-twitter-api-per-call.png)
 
-每个 API 页面都会逐个列出 endpoint 及其价格 —— 以上面的 Twitter 为例，`/apis/v1/twitter/user/last_tweets` 每次调用 \$0.0036，`/apis/v1/twitter/user/followers` 每次调用 \$0.036。
+对于固定价格 API，每个 API 页面都会逐个列出 endpoint 及其价格 —— 以上面的 Twitter 为例，`/apis/v1/twitter/user/last_tweets` 每次调用 \$0.0036，`/apis/v1/twitter/user/followers` 每次调用 \$0.036。
 
-对某个 endpoint 的每次成功请求都会产生预设费用，与响应大小无关。
+对于这些 API，某个 endpoint 的每次成功请求都会产生预设费用，与响应大小无关。
 
 该计费模型适用于这类 API：
 
@@ -57,16 +57,18 @@ AI 模型 API 根据 token 用量计费。
 * Twitter APIs。
 * 其他结构化数据和检索服务。
 
-如需查看 endpoint 级别的价格细节和计费行为，请查看 [按次调用 API 价格](/zh/guides/pricing/per-call-api-pricing)。
+如需查看固定按次计费 API 的 endpoint 级价格细节和计费行为，请查看[按次调用 API 价格](/zh/guides/pricing/per-call-api-pricing)。
+
+部分付费数据 API（包括 SimilarWeb）使用 credit 公式，而不是固定的按次价格。发起付费请求前，请阅读匹配 endpoint 文档及其机器可读计价说明；如果没有已记录的最大上限，不得按先批准后执行合同调用。
 
 ## 如何选择正确的计费模型
 
 如果你的 API 请求：
 
 * 使用语言模型生成文本 → **适用按 token 计费**。
-* 检索结构化数据或执行搜索 → **适用按次调用计费**。
+* 检索结构化数据或执行搜索 → **先阅读对应 API 的计费模型**；它可能是固定按次计费，也可能是公式计费。
 
-模型目录页会显示每个模型的按 token 价格，每个 API 页面会显示各 endpoint 的按次调用价格。
+模型目录页会显示每个模型的按 token 价格。固定价格 API 页面会显示按次价格；公式计费 API 会在端点文档中展示公式和成本控制方式。
 
 ## 用量追踪和透明度
 

zh/guides/pricing/per-call-api-pricing.mdx

@@ -1,14 +1,18 @@
 ---
-title: "按次调用 API 价格 - 搜索、金融、Twitter 与数据 API"
+title: "按次调用 API 价格 - 固定价格的搜索、金融、Twitter 与数据 API"
 excerpt: >-
-  AIsa 非 LLM API 的固定按请求价格，包括网页搜索、金融数据、Twitter、YouTube 和学术 endpoint。简单的固定费率计费，无需计算 token。
+  适用的 AIsa 数据 API 的固定按请求价格，包括网页搜索、金融数据、Twitter、YouTube 和学术 endpoint。可变费用数据 API 有单独的计费说明。
 ---
 
-本页说明 AIsa 中所有非 LLM API 的计费模型。
+本页说明 AIsa 中适用的非 LLM API 的固定价格计费模型。
+
+<Warning>
+  **重要（IMPORTANT）：** 本页不代表所有数据 API 都是固定价格。部分付费数据 API（包括 SimilarWeb）会按请求维度或返回行数计费。发起付费请求前，请阅读匹配 endpoint 文档和公开计价说明；成本可能较高时必须取得明确批准。
+</Warning>
 
 ![AIsa 上的 Tavily Search API 页面，每个 endpoint 都标注了固定的按次调用价格](/images/6bd32ad1-tavily-search-per-call.png)
 
-这些 API 使用 **固定按请求计费模型**。对某个 endpoint 的每次成功请求都会产生预设费用，与响应大小、token 数量或处理时间无关。以上面的 Tavily Search 为例，crawl、extract、map 和 search 每次调用都是 \$0.0096，与返回的数据量无关。
+这些适用的 API 使用 **固定按请求计费模型**。对某个 endpoint 的每次成功请求都会产生预设费用，与响应大小、token 数量或处理时间无关。以上面的 Tavily Search 为例，crawl、extract、map 和 search 每次调用都是 \$0.0096，与返回的数据量无关。
 
 按次调用价格适用于这类 API：
 
@@ -46,7 +50,7 @@ excerpt: >-
 
 每个按次调用 API endpoint 都有自己的定义价格。
 
-在每个 API 页面中，每个 endpoint 条目会显示：
+在每个固定价格 API 页面中，每个 endpoint 条目会显示：
 
 * HTTP 方法和 endpoint 名称。
 * API path。
@@ -108,6 +112,6 @@ Group 级别的价格规则或 ratio（如果已配置）会在计费时自动
 * 所有价格均以 USD 标价。
 * 每次成功 API 请求都会触发计费。
 * 这些 endpoint 不使用按 token 计费。
-* 响应大小不会影响费用。
+* 本页涵盖的固定价格 API 不会因响应大小改变费用。
 * 随着 endpoint 演进，价格可能变化。
 * 请以各 API 页面上的最新价格为准。