Skip to main content
Glama

Apiguru Amazon Data

by app.apiguru
OverviewDiscussionsAdmin

Live offers and inventory for up to 10 ASINs

offers_stock
Read-onlyIdempotent

Use to compare sellers' current offers and see who holds the buy box, and, with check_inventory, how many units a buyer can add to the cart now. The stock number is not a sales estimate. Not for the listing's own details (product_details). Returns the current offer list per ASIN (seller, price, condition, buy-box winner) and, optionally, the actual purchasable stock quantity. Price: $0.0045 per item (max 10). Billed per lookup, which is more than one per ASIN when check_inventory is true. offers_count=winner returns only the offer flagged is_buybox_winner (offers_total keeps the full count); it used to scope only the inventory check and return every offer. /scrape is a legacy alias for the same handler. When Amazon will not return the offer list for an ASIN, the result carries source=product_page: the featured (buy-box) offer read from the product page, offers_on_amazon (how many offers Amazon says exist) and a note; other sellers' offers and stock are then not included. With check_inventory, a cart check that cannot read a quantity is retried once on another session; one that still fails says so on the offer, inventory_response {"error": "cart check failed", "code": "cart_check_failed", "retryable": true}, is not billed, and never reads as a quantity of 0. Each offer carries ships_from (the "Ships from" name: Amazon for FBA, else the seller), delivery_message (the offer's own delivery promise, e.g. "FREE delivery Friday, October 16 on orders shipped by Amazon over $35") and delivery_message_secondary (the "Or fastest delivery ..." line), null when the offer shows none. delivery is the same value as ships_from, kept for existing integrations; it never held delivery information. A row for an ASIN that could not be answered carries error, code, http_status, billed, retryable and next_step, like a top-level error: upstream_unavailable (not billed, retry that ASIN), no_offers ("No offers found": the offer list holds no offer that can be bought as is -- customizable listings have none; billed like a 404) or asin_redirected (Amazon answers the ASIN with another listing's offers; billed like a 404). On agent.apiguru.app the answer also carries success and _links (self, and details_url per row); billable_requests_count is there on your own key only.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
geoNoMarketplace country code.US
asinsYesComma-separated ASIN list, maximum 10. Each must be 10 uppercase alphanumeric characters; malformed entries are rejected with 400. An Amazon product URL (…/dp/ASIN) works too, in place of an ASIN; lower case is fine. A URL's domain sets the marketplace unless geo says otherwise.
conditionNoComma-separated condition filter: ALL, NEW, USED_LIKE_NEW, USED_VERY_GOOD, USED_GOOD, USED_ACCEPTABLE (case-insensitive). Omit for every offer. An unknown value is a free 400 listing the allowed ones; it used to be silently treated as ALL.
offers_countNo'all' for every offer (default), 'winner' for the buy-box offer only, or a specific alphanumeric Offer ID. Every offer carries is_buybox_winner; with 'winner' the per-ASIN data holds that one offer and offers_total says how many exist. An ASIN with no featured offer answers an empty list with an explanatory error. The response echoes filters_applied.all
check_inventoryNoAdd each offer's purchasable stock quantity (`inventory_response`), read with a cart check. Slower, and each check that reads a quantity is billed, so leave off unless you need the number.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultsNo
request_idNo
country_codeNo
response_timeNo
filters_appliedNo
amazon_request_countNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / check_inventory / description
      Previous value: -"Resolve the true purchasable stock quantity. Slower and bills more lookups, so leave off unless you need the number."New value: +"Add each offer's purchasable stock quantity (`inventory_response`), read with a cart check. Slower, and each check that reads a quantity is billed, so leave off unless you need the number."
  2. Changed1 schema field changed
    • changedInput schema / properties / geo / enum
      Previous value: -[
-  "US",
-  "CA",
-  "DE",
-  "MX",
-  "UK",
-  "FR",
-  "IT",
-  "ES",
-  "AU",
-  "BR",
-  "IN",
-  "JP",
-  "NL",
-  "AE",
-  "PL",
-  "SA",
-  "SG",
-  "SE",
-  "TR",
-  "BE"
-]New value: +[
+  "US",
+  "CA",
+  "DE",
+  "MX",
+  "UK",
+  "FR",
+  "IT",
+  "ES",
+  "AU",
+  "BR",
+  "IN",
+  "JP",
+  "NL",
+  "AE",
+  "PL",
+  "SA",
+  "SG",
+  "SE",
+  "TR",
+  "BE",
+  "IE",
+  "ZA",
+  "EG"
+]
  3. Changed2 schema fields changed
    • changedInput schema / properties / asins / description
      Previous value: -"Comma-separated ASIN list, maximum 10. Each must be 10 uppercase alphanumeric characters; malformed entries are rejected with 400."New value: +"Comma-separated ASIN list, maximum 10. Each must be 10 uppercase alphanumeric characters; malformed entries are rejected with 400. An Amazon product URL (…/dp/ASIN) works too, in place of an ASIN; lower case is fine. A URL's domain sets the marketplace unless geo says otherwise."
    • removedInput schema / properties / asins / pattern
      Removed value: -"^[A-Z0-9]{10}(,[A-Z0-9]{10})*$"
  4. Changed1 schema field changed
    • changedInput schema / properties / check_inventory / description
      Previous value: -"Resolve the true purchasable stock quantity. Slower and bills more upstream requests, so leave off unless you need the number."New value: +"Resolve the true purchasable stock quantity. Slower and bills more lookups, so leave off unless you need the number."
  5. Changed2 schema fields changed
    • changedInput schema / properties / offers_count / description
      Previous value: -"'all' for every offer, 'winner' for the buy-box offer only, or a specific alphanumeric Offer ID."New value: +"'all' for every offer (default), 'winner' for the buy-box offer only, or a specific alphanumeric Offer ID. Every offer carries is_buybox_winner; with 'winner' the per-ASIN data holds that one offer and offers_total says how many exist. An ASIN with no featured offer answers an empty list with an explanatory error. The response echoes filters_applied."
    • addedOutput schema / properties / filters_applied
      Added value: +{
+  "default": null,
+  "title": "Filters Applied"
+}
  6. Changed1 schema field changed
    • changedInput schema / properties / condition / description
      Previous value: -"Comma-separated condition filter. Any of ALL, NEW, USED_LIKE_NEW, USED_VERY_GOOD, USED_GOOD, USED_ACCEPTABLE. Unrecognised values silently fall back to ALL."New value: +"Comma-separated condition filter: ALL, NEW, USED_LIKE_NEW, USED_VERY_GOOD, USED_GOOD, USED_ACCEPTABLE (case-insensitive). Omit for every offer. An unknown value is a free 400 listing the allowed ones; it used to be silently treated as ALL."
  7. Changed1 schema field changed
    • addedInput schema / properties / asins / pattern
      Added value: +"^[A-Z0-9]{10}(,[A-Z0-9]{10})*$"
  8. First observed

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover safety (readOnly, idempotent, non-destructive), and the description layers on the costly specifics: pricing ($0.0045/item, billed per lookup, multiplied by check_inventory), retry/billing rules for failed cart checks, the product_page fallback when Amazon withholds the offer list, per-ASIN error codes and their billing treatment, and the /scrape legacy alias. This is exactly the extra context annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and cost are front-loaded, but the remainder is a dense unbroken block mixing output-field semantics, error taxonomy, deprecation history and billing minutiae. Most sentences carry real information, yet the lack of paragraphing/headers makes it harder to scan than it needs to be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter, multi-marketplace, billable lookup with complex failure modes, the description covers fallbacks, error codes, billing edge cases and result-field meaning (ships_from vs delivery, inventory_response shape). Even though an output schema exists, nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3 and the schema already defines geo, asins, condition, offers_count and check_inventory. The description mostly restates those semantics; it adds marginal value via the offers_count=winner behavior change and the per-check billing note, but not enough to lift above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource+scope: compare sellers' current offers and identify the buy-box winner, optionally with purchasable stock. It explicitly distinguishes itself from sibling product_details ("Not for the listing's own details"), so an agent can route correctly without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States when to use it (comparing offers, buy box, stock), when not to (listing details → product_details), and gives a conditional for the expensive path (check_inventory "leave off unless you need the number"). Alternatives and exclusions are both explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Apiguru Amazon Data toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources