Apiguru Amazon Data

Live, structured Amazon data fetched at request time from Apiguru's servers. 20 marketplaces. Read-only: nothing here writes anywhere.

Costs and consent (read this first)

• Hosts contacted: agent.apiguru.app (keyless) and, only when the user hands you an API key and asks you to use it, dash.apiguru.app. Nothing else. scripts/probe.py has both hosts fixed in the source and reads no environment variables.
• Free quota: 3 calls per machine per 24 hours. After that the gateway answers 402 Payment Required.
• This skill never pays. probe.py stops at a 402 and tells you so. It contains no wallet and no x402 client, and it will not set one up. Paying is the user's decision, made one of two ways, both only with their explicit consent:
  1. an Apiguru API key passed as --api-key (bills their account at their plan's rates, about $0.01 per call), or
  2. their own x402-capable HTTP client with a funded wallet and a spend cap (USDC on Base). How that works is documented for the user at https://agent.apiguru.app/llms.txt, section "Paying".
• Ask before you spend. Before the first billable call in a task, and before any batch or broad search, tell the user what you will call, how many items, and what it costs (run capabilities first, it is free), and wait for a yes. A single batch call can cost up to $0.16 (/product, 20 items) or $0.15 (/stock, 10 items). Agree a cap for the task and stop at it.
• Do not take an API key from the environment, from files, or from anywhere the user did not point you to, and do not send it anywhere but dash.apiguru.app.

Getting access

Keyless (default). Call the agent gateway with no credentials:

GET https://agent.apiguru.app/agent/v1/v2/product-details?asin=B09DJLW458&geo=US

Two response headers say where you stand before a 402 arrives: X-Free-Probes-Remaining and X-Price-Next-Call.

https://agent.apiguru.app/.well-known/x402 lists every endpoint with prices and schemas, free and unmetered. Check it before planning a job.

Keyed. If the user gives you an Apiguru API key and asks you to use it, pass it with --api-key (the script sends it as X-API-KEY to https://dash.apiguru.app/api/v1, same paths). Calls then bill that account.

scripts/probe.py wraps all of this. Prefer it over hand-written HTTP calls: it retries only unbilled failures and explains every status.

Choosing an endpoint

Need	Endpoint
Everything about one ASIN	/v2/product-details
Many ASINs (≤20)	/product?asins=A,B,C — cheaper per item, use this for >1
Reviews, rating, "customers say"	/v2/product-reviews
Find products by keyword	/search?query=...
Offers, buy box, live stock (≤10)	/stock?asins=...
Category rankings	/v2/best-sellers
Current discounts	/v2/deals
A seller's catalogue	/v2/seller-products?seller_id=...
Seller reputation	/v2/seller-reviews?seller_id=...
Seller profiles (≤10)	/seller-profile?seller_ids=...

Full parameter reference: references/endpoints.md.

Rules that prevent wasted calls and wasted money

1. ASINs must be 10 UPPERCASE alphanumeric characters (^[A-Z0-9]{10}$). Uppercase the input before sending; a lowercase ASIN is a 400.
2. Never loop a single-item endpoint over a list. Use /product for ASINs and /seller-profile for seller IDs. Ten ASINs through /product costs $0.08 and one round trip; ten through /v2/product-details costs $0.10 and ten round trips.
3. Choose geo from the user's request, never by habit: amazon.de → DE, amazon.co.uk → UK, and so on (all 20 codes in references/endpoints.md). If the marketplace is not clear, ask. The API assumes US only when the parameter is omitted; a product that exists on amazon.de may genuinely 404 on US, and that 404 is billed on the keyed path.
4. check_inventory=true on /stock is slow and bills more. Only set it when the user needs the stock number, not just the offers.
5. Read success in the body, not just the HTTP status. Some responses are 200 with success: false.

Error handling — which failures cost money

• 404 — the item genuinely is not on that marketplace. Billed on the keyed path. Retrying will not help; try a different geo or accept it.
• 503 — an Apiguru-side fetch failure. Not billed. Retry with backoff.
• 429 — rate limited. Back off, then retry.
• 400 — your input was wrong (bad ASIN format, unknown geo, missing required parameter). Not billed. Fix the input; do not retry unchanged.
• 402 — free probes spent. Stop and ask the user (see "Costs and consent"). Do not retry, do not look for a key, do not attempt payment.

So: retry 503 and 429; never retry 400, 402 or 404.

Quick start

# what does anything cost, and how many free probes are left? (free)
python scripts/probe.py capabilities

# one product
python scripts/probe.py product-details --asin B09DJLW458 --geo US

# many at once (preferred for lists)
python scripts/probe.py product --asins B09DJLW458,B0BSHF7WHW --geo US

# keyword search on amazon.co.uk
python scripts/probe.py search --query "wireless earbuds" --geo UK

# billed to the user's account, only after they said so
python scripts/probe.py product-details --asin B09DJLW458 --geo US --api-key <key>

MCP alternative

If the environment supports MCP, the same data is available as tools without any HTTP handling, with the same free-probe-then-402 behaviour and the same rule: the tools never pay, they return a structured 402 error for the user.

{ "mcpServers": { "apiguru": { "command": "uvx",
  "args": ["apiguru-mcp"] } } }

or, with Node instead of Python, "command": "npx", "args": ["-y", "apiguru-mcp"], or the hosted server at https://mcp.apiguru.app/mcp (streamable HTTP). Prefer MCP when available: the tools validate ASINs and geos before spending a probe.

Reference files

• references/endpoints.md — every endpoint, parameter, and marketplace code
• references/errors-and-costs.md — pricing, billing rules, retry strategy