From 5ca1476025ae8fce6fc399ebebfc5ed339113843 Mon Sep 17 00:00:00 2001 From: Kevin Wang Date: Fri, 14 Aug 2026 18:26:57 -0700 Subject: [PATCH 1/2] Document the per-1,000-request price denomination Every static discovery offer now publishes its maximum twice: `maxUsd` for one request and `maxPer1kUsd` for 1,000 of them, with `failoverMaxPer1kUsd` as the twin of `failoverMaxUsd`. Lane-level `pricing` objects carry `maxPer1kUsd` too. The docs enumerated only the per-request half, so a reader building against discovery could not find the field AnyAPI quotes customers in. Per 1,000 requests is the customer-facing standard because most of the catalog costs a fraction of a cent per call. Each page that lists the discovery pricing fields now also states that adapters read the published per-1k figure rather than multiplying `maxUsd`, which drifts in floating point, that `baseUsd` and `perUnitUsd` have no per-1k twin, and that amounts naming what a specific call costs stay per request. Co-Authored-By: Claude Opus 5 (1M context) --- agent-skills.mdx | 2 +- cli.mdx | 20 +++++++++++++++----- index.mdx | 32 ++++++++++++++++++++++++++++++++ mcp-server.mdx | 39 +++++++++++++++++++++++++++++---------- n8n.mdx | 9 +++++++++ quickstart.mdx | 11 +++++++++++ sdks.mdx | 10 ++++++++++ 7 files changed, 107 insertions(+), 16 deletions(-) diff --git a/agent-skills.mdx b/agent-skills.mdx index d1da310..eab5c4e 100644 --- a/agent-skills.mdx +++ b/agent-skills.mdx @@ -81,7 +81,7 @@ it asks which email to tie the account to and mints a key — no dashboard trip. Ask your agent for third-party data — "get the top posts in r/golang", "scrape this - TikTok profile" — and it will discover the right API, check the per-request USD + TikTok profile" — and it will discover the right API, check its published USD price, and run it. diff --git a/cli.mdx b/cli.mdx index 38a182a..02c2e7c 100644 --- a/cli.mdx +++ b/cli.mdx @@ -51,11 +51,21 @@ customer-safe USD offer returned by discovery; they never expose an internal accounting unit or upstream provider. Static discovery pricing is nested. `pricing.from` is either a flat offer -(`model`, `unit: "request"`, `maxUsd`) or a linear offer (`model`, `unit`, -`baseUsd`, `perUnitUsd`, `maxUsd`). `pricing.failoverMaxUsd` is the greatest -fallback ceiling. The optional `failover` boolean reports whether AnyAPI currently -has an alternate route. Use the displayed unit when estimating a linear call, or -run `anyapi describe ` to inspect the complete offer before execution. +(`model`, `unit: "request"`, `maxUsd`, `maxPer1kUsd`) or a linear offer (`model`, +`unit`, `baseUsd`, `perUnitUsd`, `maxUsd`, `maxPer1kUsd`). `pricing.failoverMaxUsd` +is the greatest fallback ceiling, published beside its per-1,000-request twin +`pricing.failoverMaxPer1kUsd`. The optional `failover` boolean reports whether AnyAPI +currently has an alternate route. Use the displayed unit when estimating a linear +call, or run `anyapi describe ` to inspect the complete offer before execution. + +Every maximum arrives in two denominations: `maxUsd` for one request and +`maxPer1kUsd` for 1,000 of them. **Per 1,000 requests is the denomination AnyAPI +quotes customers in**, because most of the catalog costs a fraction of a cent per call +and per-request figures cannot be compared by eye. Read the published per-1k field +instead of multiplying `maxUsd`, which drifts in floating point (`0.0966 * 1000` is +`96.60000000000001` in most languages). `baseUsd` and `perUnitUsd` have no per-1k +twin, because they are charged per billable item inside one call, and the `costUsd` of +a completed run and the balance from `anyapi balance` stay per request. ## Gateway and CLI responsibilities diff --git a/index.mdx b/index.mdx index 6224402..9b88249 100644 --- a/index.mdx +++ b/index.mdx @@ -89,6 +89,38 @@ while `pricing.failoverMaxUsd` is the greatest fallback ceiling. Linear offers n their billable `unit` and include `baseUsd`, `perUnitUsd`, and `maxUsd`, so you can budget before making a call. Simple lookups are flat per request. +### Every static price in two denominations + +Every static discovery offer publishes its maximum twice: + +| Field | What it means | +|---|---| +| `pricing.from.maxUsd` | The most one request can be billed | +| `pricing.from.maxPer1kUsd` | That same maximum per 1,000 requests | +| `pricing.failoverMaxUsd` | The greatest fallback ceiling for one request | +| `pricing.failoverMaxPer1kUsd` | That same fallback ceiling per 1,000 requests | + +Lane-level `pricing` objects carry `maxPer1kUsd` too. + +**Per 1,000 requests is the denomination AnyAPI quotes customers in.** Most of the +catalog costs a fraction of a cent per call, and per-request figures at that scale +cannot be compared by eye. When you show a catalog price to a person, read +`maxPer1kUsd` and label it `/1k req` - for example `$96.60/1k req` rather than +`$0.0966 per request`. + +Read the published per-1k field instead of multiplying `maxUsd` yourself. AnyAPI +derives it with exact fixed-point arithmetic, while a floating-point multiplication +drifts: in most languages `0.0966 * 1000` is `96.60000000000001`, and live catalog +prices land on that case. + +`baseUsd` and `perUnitUsd` have **no** per-1k twin. They are charged per billable +item inside a single call, so a per-1,000-request version of them would describe +nothing you can be billed. + +Amounts that state what one specific call costs stay per request and are never +scaled to 1,000: a price quote's `maxCostUsd` and `minCostUsd`, the `costUsd` on a +completed run, and your wallet balance. Report those exactly as returned. + ## For AI agents If you are an AI agent (or are setting one up), AnyAPI's whole catalog is available diff --git a/mcp-server.mdx b/mcp-server.mdx index e571bc6..611317b 100644 --- a/mcp-server.mdx +++ b/mcp-server.mdx @@ -302,9 +302,11 @@ and `structuredContent` with these shapes: "from": { "model": "flat", "unit": "request", - "maxUsd": 0.003 + "maxUsd": 0.003, + "maxPer1kUsd": 3 }, - "failoverMaxUsd": 0.003 + "failoverMaxUsd": 0.003, + "failoverMaxPer1kUsd": 3 }, "failover": true, "relevance": 1 @@ -320,11 +322,25 @@ and `structuredContent` with these shapes: so browsing and searching stay token-cheap. Reach for `list_apis` when you want to enumerate rather than search. -This API's `pricing.from.model` is `flat`, so its maximum is per request. `failover` -is the gateway's authoritative routing fact; do not infer it from lanes. A linear -offer instead carries `unit`, `baseUsd`, `perUnitUsd`, and `maxUsd`. For example, -an API billed per result reports `unit: "result"`; the actual successful charge is -the base plus the per-unit amount, capped at `maxUsd`. +This API's `pricing.from.model` is `flat`, so `maxUsd` is what one request is billed. +`failover` is the gateway's authoritative routing fact; do not infer it from lanes. A +linear offer instead carries `unit`, `baseUsd`, `perUnitUsd`, `maxUsd`, and +`maxPer1kUsd`. For example, an API billed per result reports `unit: "result"`; the +actual successful charge is the base plus the per-unit amount, capped at `maxUsd`. + +Every static offer publishes its maximum twice: `maxUsd` for one request and +`maxPer1kUsd` for 1,000 of them, with `failoverMaxPer1kUsd` as the twin of +`failoverMaxUsd`. Lane-level `pricing` objects carry `maxPer1kUsd` too. +**Per 1,000 requests is the denomination AnyAPI quotes customers in**, because most of +the catalog costs a fraction of a cent per call and per-request figures cannot be +compared by eye. Surface `$3.00/1k req` rather than `$0.003 per request`, and read the +published field instead of multiplying `maxUsd`, which drifts in floating point +(`0.0966 * 1000` is `96.60000000000001` in most languages). + +`baseUsd` and `perUnitUsd` have no per-1k twin, because they are charged per billable +item inside one call. Amounts that state what a specific call costs stay per request +and are never scaled to 1,000: a price quote's `maxCostUsd` and `minCostUsd`, the +`costUsd` `run_api` returns, and the `balanceUsd` from `get_balance`. ```json // get_api {"sku_id": "reddit.search"} → structuredContent (schemas abridged) @@ -339,9 +355,11 @@ the base plus the per-unit amount, capped at `maxUsd`. "from": { "model": "flat", "unit": "request", - "maxUsd": 0.003 + "maxUsd": 0.003, + "maxPer1kUsd": 3 }, - "failoverMaxUsd": 0.003 + "failoverMaxUsd": 0.003, + "failoverMaxPer1kUsd": 3 }, "failover": true, "description": "Search Reddit posts across all subreddits by query.", @@ -350,7 +368,8 @@ the base plus the per-unit amount, capped at `maxUsd`. "pricing": { "model": "flat", "unit": "request", - "maxUsd": 0.003 + "maxUsd": 0.003, + "maxPer1kUsd": 3 } } ], diff --git a/n8n.mdx b/n8n.mdx index e973a7b..9b959d1 100644 --- a/n8n.mdx +++ b/n8n.mdx @@ -117,6 +117,15 @@ ceiling, and `failover` reports whether AnyAPI currently has an alternate route. does not calculate these values from `lanes`, and input and output schemas pass through as opaque JSON Schema objects. +Each static maximum is published in two denominations: `maxUsd` for one request and +`maxPer1kUsd` for 1,000 of them, with `failoverMaxPer1kUsd` beside `failoverMaxUsd`. +**Per 1,000 requests is the denomination AnyAPI quotes customers in**, because most of +the catalog costs a fraction of a cent per call and per-request figures cannot be +compared by eye. Read the published per-1k field rather than scaling `maxUsd` yourself, +which drifts in floating point (`0.0966 * 1000` is `96.60000000000001` in most +languages). `baseUsd` and `perUnitUsd` have no per-1k twin, because they are charged per +billable item inside one call, and the `costUsd` on a completed run stays per request. + ## Response budget options (Run API) **Run API** has three optional controls under **Options** that shrink the response payload so a diff --git a/quickstart.mdx b/quickstart.mdx index b9cfdcf..5d92bb9 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -156,6 +156,17 @@ Browse and search results report `provider: "AnyAPI"` and nested USD `pricing`. fallback ceiling, and `failover` reports whether AnyAPI currently has an alternate route. +Each of those maximums arrives in two denominations. `pricing.from.maxUsd` and +`pricing.failoverMaxUsd` are what one request can be billed; +`pricing.from.maxPer1kUsd` and `pricing.failoverMaxPer1kUsd` are the same ceilings per +1,000 requests. **Per 1,000 requests is the denomination AnyAPI quotes customers in**, +because most of the catalog costs a fraction of a cent per call and per-request figures +cannot be compared by eye. Show `$96.60/1k req` rather than `$0.0966 per request`, and +read the published per-1k field instead of multiplying `maxUsd`, which drifts in +floating point (`0.0966 * 1000` is `96.60000000000001` in most languages). `baseUsd` +and `perUnitUsd` have no per-1k twin, because they are charged per billable item inside +one call. The `costUsd` on a completed run and your wallet balance stay per request. + These values come from the gateway. The gateway owns input validation, provider selection, route and lane order, failover, pricing, health semantics, and billing. Do not infer failover from the number of lanes or recompute `pricing.from` from lane diff --git a/sdks.mdx b/sdks.mdx index bc8b19f..3ff42cb 100644 --- a/sdks.mdx +++ b/sdks.mdx @@ -135,6 +135,16 @@ Treat `pricing.from`, `pricing.failoverMaxUsd`, `failover`, lane order, and heal gateway-published facts. `failover` reports whether AnyAPI currently has an alternate route. Do not derive it from the lane count or recompute pricing from individual lanes. +Discovery publishes each static maximum in two denominations: `maxUsd` is what one +request can be billed and `maxPer1kUsd` is that same maximum per 1,000 requests, with +`failoverMaxPer1kUsd` as the twin of `failoverMaxUsd`. **Per 1,000 requests is the +denomination AnyAPI quotes customers in**, because most of the catalog costs a fraction +of a cent per call and per-request figures cannot be compared by eye. Display the +published per-1k field rather than multiplying `maxUsd`, which drifts in floating point +(`0.0966 * 1000` is `96.60000000000001` in most languages). `baseUsd` and `perUnitUsd` +have no per-1k twin, because they are charged per billable item inside one call, and +`costUsd` and the wallet balance stay per request. + ## Async (Python) The TypeScript SDK is promise-based, so every method is already `await`-able. In Python, From 1307827c9746e18f04a1a44465ef0a9d5c14140f Mon Sep 17 00:00:00 2001 From: Kevin Wang Date: Fri, 14 Aug 2026 18:31:31 -0700 Subject: [PATCH 2/2] Bring the reddit.search examples to the live price The worked examples showed maxUsd 0.003 where production publishes 0.0009, and a failover ceiling of 0.003 where production publishes 0.0036. The per-1k figures added alongside were internally consistent with the stale number, so the page taught the right rule with the wrong price. Verified against GET /catalog today: reddit.search is $0.0009 per request, $0.90/1k req, failover ceiling $0.0036 and $3.60/1k req. The run_api costUsd example follows the same price. --- mcp-server.mdx | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/mcp-server.mdx b/mcp-server.mdx index 611317b..bb92ab6 100644 --- a/mcp-server.mdx +++ b/mcp-server.mdx @@ -302,11 +302,11 @@ and `structuredContent` with these shapes: "from": { "model": "flat", "unit": "request", - "maxUsd": 0.003, - "maxPer1kUsd": 3 + "maxUsd": 0.0009, + "maxPer1kUsd": 0.9 }, - "failoverMaxUsd": 0.003, - "failoverMaxPer1kUsd": 3 + "failoverMaxUsd": 0.0036, + "failoverMaxPer1kUsd": 3.6 }, "failover": true, "relevance": 1 @@ -333,7 +333,7 @@ Every static offer publishes its maximum twice: `maxUsd` for one request and `failoverMaxUsd`. Lane-level `pricing` objects carry `maxPer1kUsd` too. **Per 1,000 requests is the denomination AnyAPI quotes customers in**, because most of the catalog costs a fraction of a cent per call and per-request figures cannot be -compared by eye. Surface `$3.00/1k req` rather than `$0.003 per request`, and read the +compared by eye. Surface `$0.90/1k req` rather than `$0.0009 per request`, and read the published field instead of multiplying `maxUsd`, which drifts in floating point (`0.0966 * 1000` is `96.60000000000001` in most languages). @@ -355,11 +355,11 @@ and are never scaled to 1,000: a price quote's `maxCostUsd` and `minCostUsd`, th "from": { "model": "flat", "unit": "request", - "maxUsd": 0.003, - "maxPer1kUsd": 3 + "maxUsd": 0.0009, + "maxPer1kUsd": 0.9 }, - "failoverMaxUsd": 0.003, - "failoverMaxPer1kUsd": 3 + "failoverMaxUsd": 0.0036, + "failoverMaxPer1kUsd": 3.6 }, "failover": true, "description": "Search Reddit posts across all subreddits by query.", @@ -368,8 +368,8 @@ and are never scaled to 1,000: a price quote's `maxCostUsd` and `minCostUsd`, th "pricing": { "model": "flat", "unit": "request", - "maxUsd": 0.003, - "maxPer1kUsd": 3 + "maxUsd": 0.0009, + "maxPer1kUsd": 0.9 } } ], @@ -393,7 +393,7 @@ and are never scaled to 1,000: a price quote's `maxCostUsd` and `minCostUsd`, th { "output": { "posts": [ { "title": "…", "url": "…", "score": 123 } ] }, "provider": "AnyAPI", - "costUsd": 0.003, + "costUsd": 0.0009, "items": 25, "replayed": false }