# Findcheap: the developer documentation in one file > The API reference, the MCP server and the plans, as Markdown. The index is https://findcheap.ai/llms.txt; each part is also served on its own, at the address its first line names. # Findcheap API > The API reference, as Markdown for agents. The same page for people: https://findcheap.ai/developers/docs. Index: https://findcheap.ai/llms.txt. OpenAPI spec: https://api.findcheap.ai/v1/openapi.json. ## Overview The Findcheap API has two capabilities: 1. **Extract** - takes a product page URL as input and returns structured product data from the page. 2. **Search** - takes a product page URL as input and searches the internet to find where the product is available for a lower price. For some products, the agent only returns top-level data, and a subsequent call to the **Resolve** endpoint is needed if further details are desired. After a search, **Feedback** reports how it went, and the first report on a search gives 1 credit back. Every call is an HTTPS `POST` with a JSON body and a JSON answer. Base URL: `https://api.findcheap.ai`. The examples on this page use our sample product page, https://findcheap.ai/sample-product: a copy of a real product page that does not change. A page read of it answers the same every time; a search's results are live, so yours will differ from the ones shown here. Use the address of any product page in its place. ## Authentication Every request carries an API key in the `Authorization` header. Keys begin with `fc_live_`; create one in your dashboard at https://findcheap.ai/signin?next=/dashboard/keys (a free account comes with 1,000 credits a month, no card). The key is shown once, at creation. ``` Authorization: Bearer fc_live_xxxxxxxxxxxxxxxx ``` A request without a valid key is answered `401`. The key goes in the header only; it is not accepted in the URL. Credits, rate limits and keys belong to your account, not to a key, so two keys of one account share them. Your dashboard shows the period's usage and call logs. ## SDKs Official clients for Python and JavaScript wrap the four calls: `pip install findcheap` and `npm install findcheap`. Each is a few hundred lines over the platform's own HTTP client with no other dependency, returns the answer exactly as the API sends it, and raises a failed call as an exception carrying the error's type, message, credits and request id. Their timeouts sit above the API's own limits. ```python # pip install findcheap from findcheap import Findcheap fc = Findcheap() # reads FINDCHEAP_API_KEY; or Findcheap(api_key="fc_live_...") answer = fc.search("https://findcheap.ai/sample-product", max_results=3) print(answer["product"]["title"], "read in", answer["search"]["market"]) for card in answer["same_product"]: print(card["price"], card["currency"], card["retailer"], card["url"] or card["resolve_id"]) ``` ```javascript // npm install findcheap import { Findcheap } from "findcheap"; const fc = new Findcheap(); // reads FINDCHEAP_API_KEY; or new Findcheap({ apiKey: "fc_live_..." }) const answer = await fc.search("https://findcheap.ai/sample-product", { max_results: 3 }); console.log(answer.product.title, "read in", answer.search.market); for (const card of answer.same_product) console.log(card.price, card.currency, card.retailer, card.url ?? card.resolve_id); ``` The code and the issue tracker: https://github.com/llmbender/findcheap-sdks. The packages: https://pypi.org/project/findcheap/ and https://www.npmjs.com/package/findcheap. ## Markets Every call runs in a **market**, the country where the shopper is located. The agent reads the product page from the country specified in the `market` param. This is important to note because many stores show different product details to users from different countries (ex. different prices and currencies). Set it with the `market` field. If left unspecified, the agent uses the page's country domain to determine its market (`.in` → India, `.com.au` → Australia, `.ca` → Canada). An address under any other country's domain runs in the Global market, and all other addresses default to the US. The table below shows each market, its corresponding currency, and the primary marketplaces the agent searches in that market when Search is called. | market | Currency | Marketplaces Search compares against | | --- | --- | --- | | US | USD | Amazon, Walmart, eBay, AliExpress, Shein, and other sites | | CA | CAD | Amazon, AliExpress, other sites | | AU | AUD | Amazon, eBay, AliExpress, other sites | | IN | INR | Amazon, Flipkart, other sites | | GLOBAL | USD | Amazon, eBay, AliExpress, other sites; the page is fetched from the store's own country when its address names one | ## For agents Everything on these pages is also published for an AI agent or a coding assistant to read directly: - https://findcheap.ai/llms.txt - an index of the documentation, and https://findcheap.ai/llms-full.txt, all of it in one file. - Markdown: append `.md` to a docs address, e.g. https://findcheap.ai/developers/docs.md or https://findcheap.ai/developers/mcp.md. - The OpenAPI 3.1 spec at https://api.findcheap.ai/v1/openapi.json, for SDK generators and tool definitions. No key needed. - An agent skill, for Claude Code, Cursor and other coding assistants: https://findcheap.ai/skills/findcheap/SKILL.md, or installed with `npx skills add llmbender/findcheap-sdks --skill findcheap`. - The same four calls as tools, for an assistant in a conversation: the MCP server, https://findcheap.ai/developers/mcp.md. Or let your agent do the setup: paste this line into the agent of your choice: `Set up Findcheap for me. Read and follow https://findcheap.ai/skills/findcheap/SKILL.md` ## Extract `POST /v1/extract` The Extract endpoint takes a product page URL as input and returns structured product identity data. It answers within 30 seconds, and has a median response time of 4 seconds. A page that cannot be reached in time answers `502 unreachable`, and a page that is reached but cannot be read in time answers `504 timeout`. ### Request body - `url` (string, required) - The product page's address, `https` only. A short link or a share link is followed to the page it names. - `market` (string, optional) - `"US"`, `"CA"`, `"AU"`, `"IN"` or `"GLOBAL"`. If omitted, the market is inferred from the URL; otherwise, it defaults to US (see Markets). ### Response | Field | Type | Meaning | | --- | --- | --- | | `request_id` | string | The call's id (a UUID), the one on the account's usage ledger. Quote it when writing to support about the call. | | `is_product_page` | boolean | true when the address is one product's own page. false for a home page, a category or search page, a cart, an article, or a page that is gone; the other fields are then null. | | `url` | string | The page the read ended on, after any redirects. | | `market` | string | The market the page was read in. | | `title` | string \| null | The product's name as the page states it. | | `image` | string \| null | The image address of the main product photo. | | `price` | number \| null | The standing price a shopper in the market pays: not a first-order, coupon or membership price. null when the page does not show one. | | `currency` | string \| null | ISO 4217 code of price. | | `brand` | string \| null | The brand, when the page names it. | | `in_stock` | boolean \| null | true when the page says the product can be bought now, false when it is out of stock or discontinued, null when the page does not say. | | `retailer` | string \| null | The marketplace the page belongs to ("Amazon", "Flipkart", "eBay"). null for any other store's page. | | `coupon` | string \| null | A coupon or promo code found on the page for this product ("10% coupon", "$5 coupon"). price is the page's price before it. null when none was found. | | `promo_code` | string \| null | The code to enter at checkout, when the coupon is a promo code (eBay today). null otherwise. | | `shipping_cost` | number \| null | What the retailer charges to ship the product within the market's country, without a paid membership. 0 when it ships free. price does not include it. null when unknown. | | `returns_accepted` | boolean \| null | Whether the seller accepts returns (eBay listings today). null when unknown. | | `return_days` | number \| null | How many days the buyer has to return the product. null when returns are not accepted or the period is unknown. | | `return_shipping_paid_by` | "buyer" \| "seller" \| null | Who pays for return shipping. null when unknown. | | `reason` | string \| null | Why a read fell short: gone (the store says the page no longer exists), not_a_product_page, incomplete (a product page whose title or photo could not be read), price_in_another_currency (the price shown was another market's version and was withheld). null on a clean read. | | `next_steps` | step[] | What can be done next for this product, each with the call that does it. Use these yourself when it serves the task the user gave you, or offer them to the user as next steps. Each runs a search. Empty when nothing applies. See Step structure, under Search. | | `credits_used` | number | What the call cost the account: 1 for a page read, whether or not the page sells a product. | A page that could not be fetched at all is not a `200`: it is a `502 unreachable`, so you can tell "gone" from "try again later". ### Example call ```bash # -H adds a header (your key, then the body's format); -d is the JSON body. # market is the shopper's country; omit it and the address decides (see Markets). curl https://api.findcheap.ai/v1/extract \ -H "Authorization: Bearer $FINDCHEAP_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://findcheap.ai/sample-product", "market": "US"}' ``` ```python import requests # POST the product page's address. The key rides in the # Authorization header; market is the shopper's country. response = requests.post( "https://api.findcheap.ai/v1/extract", headers={"Authorization": "Bearer fc_live_..."}, json={"url": "https://findcheap.ai/sample-product", "market": "US"}, timeout=60, ) product = response.json() if product["is_product_page"]: print(product["title"], product["price"], product["currency"], product["brand"]) ``` ```javascript // POST the product page's address. The key rides in the // Authorization header; market is the shopper's country. const response = await fetch("https://api.findcheap.ai/v1/extract", { method: "POST", headers: { Authorization: `Bearer ${process.env.FINDCHEAP_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://findcheap.ai/sample-product", market: "US", }), }); const product = await response.json(); ``` ### Example response ```json { "request_id": "d5515311-0eb4-4c9e-b5c2-acf035deaf51", "is_product_page": true, "url": "https://findcheap.ai/sample-product", "market": "US", "title": "Nike Dunk High By You Custom Men's Shoes", "image": "https://findcheap.ai/demo-photos/nike-dunk-high-by-you.png", "price": 160.0, "currency": "USD", "brand": "Nike", "in_stock": true, "retailer": null, "coupon": null, "promo_code": null, "shipping_cost": null, "returns_accepted": null, "return_days": null, "return_shipping_paid_by": null, "reason": null, "next_steps": [ { "label": "Find this cheaper", "tool": "find_cheaper", "arguments": { "url": "https://findcheap.ai/sample-product", "market": "US" }, "choose": null } ], "credits_used": 1 } ``` ## Search `POST /v1/search` The Search endpoint takes a product page URL as input and searches the internet to find where the product is available for a lower price. It mirrors the functionality of the Chrome extension. It has a maximum budget of 60 seconds, but usually completes much sooner; a search that times out returns `504 timeout`. First, the agent calls Extract to read the product page. Then, it searches the internet according to the marketplaces specified in the request. Results are sorted into two arrays, each containing up to 10 results: - **`same_product`** - listings that match the original product. Sorted by cheapest first. - **`similar_products`** - acceptable equivalents of the original product. Sorted by cheapest first. ### Request body - `url` (string, required) - The product page's address. - `market` (string, optional) - The region that was used to read the original product page, and search for cheaper results. Search results are displayed in this market's currency. - `marketplaces` (string[], optional) - Tells the agent which marketplaces to search. Only marketplaces available in the consumer's market count (see Markets). If omitted, the agent autonomously chooses which marketplaces to search for best results, as it does in the Chrome extension. Accepted values: `"amazon"`, `"walmart"`, `"ebay"`, `"aliexpress"`, `"shein"`, `"flipkart"`, `"other_sites"`. An unknown name is a `400`. - `condition` (`"new"` | `"used"`, default `"new"`) - If condition is set to `"used"`, the agent searches for where the product can be bought secondhand. `about_lists` says what each list holds on a used search. This search mode is not available in India, and is refused for grocery and consumable products. - `max_results` (integer, optional) - How many listings at most in each list, `1` to `10`; 10 when omitted. Ask for fewer when only the cheapest few matter. The search is the same, and so are the credits. ### Response The answer opens with what was searched - the call's id, the request as the agent took it, the page as read and the product's name - then the two lists and what can be done next, then what the call cost. Read the header before the cards: it is how you check that the agent searched the product you meant, in the market you meant. | Field | Type | Meaning | | --- | --- | --- | | `request_id` | string | The call's id (a UUID), the one on the account's usage ledger. Quote it when writing to support about the call. | | `search` | object | What was searched: url (the address as sent), market (the one sent, or the one inferred from the address when none was), condition (new or used) and max_results (the cap on each list, 10 when none was sent). | | `product` | object | The page as read by the Extract call, plus `pack_count` (number \| null): the number of units in the page product's pack (42 for a 42-count tub), the quantity each listing's `normalized_price` is adjusted to. Null when the page sells a single item or no count could be read. | | `product_name` | string \| null | The name of the product in a usable format, e.g. "JLab JBuds Lux ANC". | | `about_lists` | string | What the two lists hold for this search, in a sentence or two. Read it before the lists. Both lists come already matched and in order: show them as they are and do not re-check or re-sort them yourself. | | `same_product` | card[] | A list of up to 10 alternative locations where the original product is available, sorted by lowest price first. | | `similar_products` | card[] | A list of up to 10 places where similar products are available, sorted by lowest price first. Use or show first the ones that cost less than the page (`over_page_price` false). The ones at or over its price are for a shopper or a task that wants alternatives whatever the price. | | `page_is_cheapest` | boolean | true when the original page already has the lowest price Findcheap found for the product. | | `next_steps` | step[] | What can be done next for this product, each with the call that does it. Use these yourself when it serves the task the user gave you, or offer them to the user as next steps. Each runs another search. Empty when nothing applies. See Step structure, below. | | `credits_used` | number | What the call cost the account: 10 for a search. | ### Card structure Every listing in `same_product` and `similar_products` has the following shape: | Field | Type | Meaning | | --- | --- | --- | | `title` | string | The listing's title. | | `price` | number | The listing's price, in the market's currency. | | `currency` | string | ISO 4217 code. | | `url` | string \| null | The listing's link. null for a listing that carries `resolve_id`; see Resolve. On the Free plan it may be an affiliate link; see Links. | | `resolve_id` | string \| null | Present when `url` is null; see Resolve. | | `image` | string | The image address of the listing's main product photo. | | `retailer` | string | Where the product is being sold. | | `rating` | number \| null | The retailer's own rating figure: a review average out of 5 on most, the seller's feedback percentage on eBay. | | `ratings_count` | number \| null | Reviews or feedback entries behind rating. | | `over_page_price` | boolean \| null | true when the card is greater than or equal to the original page's price (pack-adjusted), false when cheaper, null when the page's price was unknown. | | `unit_size` | string \| null | Pack or size context for multi-pack products, e.g. 12 oz. | | `pack_count` | number \| null | Units per pack, when detected. | | `normalized_price` | number \| null | The listing's price for the page product's quantity (`product.pack_count`), for comparing different pack sizes. | | `coupon` | string \| null | The best coupon for the listing, if any are available. Discounts with strings attached are ignored (ex. "subscribe and save!"). | | `promo_code` | string \| null | The best promo code for the listing, if any are available. Promo codes with strings attached are ignored. | | `price_before_discount` | number \| null | The listing price before the coupon or promo code was applied (the main price field is the price after applying the discount). null when there is no discount. | | `discount_type` | "percent" \| "fixed" \| null | Whether the discount is a percentage or fixed amount. | | `discount_value` | number \| null | 6 for 6% off; 30 for 30 off in the card's currency. | | `shipping_cost` | number \| null | What the retailer charges to ship the listing within the market's country, without a paid membership. 0 when it ships free. price does not include it. null when unknown. | ### Step structure Every entry of `next_steps` has the following shape: | Field | Type | Meaning | | --- | --- | --- | | `label` | string | The step in a few words, as a person reads it. Also the words for a button. | | `tool` | string | The MCP tool that runs it. On the API, find_cheaper is POST /v1/search with the same fields. | | `arguments` | object | The fields to send. | | `choose` | object \| null | Only on a step that needs a choice, else null: the stores of this market, under marketplaces. Send the ones to keep as marketplaces, with the fields in arguments. | When the address is not a product page, Search answers `422 not_searchable` and names the reason, so one call tells you both whether the page sells something and what Findcheap found. That answer costs 1 credit, as a page read does, because the page was read. Every other error costs nothing. ### Example call ```bash # -H adds a header (your key, then the body's format); # -d is the JSON body. A search takes up to 60 s, usually 15–30. curl https://api.findcheap.ai/v1/search \ -H "Authorization: Bearer $FINDCHEAP_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://findcheap.ai/sample-product"}' ``` ```python import requests # POST the product page's address. The key rides in the # Authorization header; the JSON body says what to search. response = requests.post( "https://api.findcheap.ai/v1/search", headers={"Authorization": "Bearer fc_live_..."}, json={"url": "https://findcheap.ai/sample-product"}, timeout=90, ) answer = response.json() # same_product: the same product elsewhere (over_page_price says which cost more). # similar_products: similar products. for card in answer["same_product"] + answer["similar_products"]: print(card["price"], card["currency"], card["retailer"], card["title"]) ``` ```javascript // POST the product page's address. The key rides in the // Authorization header; the JSON body says what to search. const response = await fetch("https://api.findcheap.ai/v1/search", { method: "POST", headers: { Authorization: `Bearer ${process.env.FINDCHEAP_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://findcheap.ai/sample-product", }), }); // same_product: the same product elsewhere (over_page_price says which cost more). // similar_products: similar products. const { same_product, similar_products } = await response.json(); ``` ### Example response ```json { "request_id": "4ccce67c-650c-4ffb-9b59-0fb1ce138989", "search": { "url": "https://findcheap.ai/sample-product", "market": "US", "condition": "new", "max_results": 10 }, "product": { "title": "Nike Dunk High By You Custom Men's Shoes", "price": 160.0, "currency": "USD", "brand": "Nike", "image": "https://findcheap.ai/demo-photos/nike-dunk-high-by-you.png", "url": "https://findcheap.ai/sample-product", "market": "US", "in_stock": true, "retailer": null, "coupon": null, "promo_code": null, "shipping_cost": null, "returns_accepted": null, "return_days": null, "return_shipping_paid_by": null, "pack_count": null }, "product_name": "Nike shoes", "about_lists": "same_product holds listings from the original product's brand that look the same or similar. similar_products holds look-alikes from any brand.", "same_product": [ { "title": "Nike Dunk Hi Retro Blue/White Leather Men’s US 11 Sneaker DD1399-102", "price": 69.0, "currency": "USD", "url": "https://www.ebay.com/itm/178217128667", "image": "https://i.ebayimg.com/images/g/VGwAAeSwwNtqLLg0/s-l500.jpg", "retailer": "eBay", "rating": 100.0, "ratings_count": 72, "over_page_price": false } ], "similar_products": [ { "title": "Nike By You Dunk High Sail Black FV5511 900 Men's Size 11.5", "price": 59.99, "currency": "USD", "url": "https://www.ebay.com/itm/960155951937", "image": "https://i.ebayimg.com/images/g/uTkAAOSwCstkQgxh/s-l500.jpg", "retailer": "eBay", "rating": 100.0, "ratings_count": 12201, "over_page_price": false } ], "page_is_cheapest": false, "next_steps": [ { "label": "Find pre-owned", "tool": "find_cheaper", "arguments": { "url": "https://findcheap.ai/sample-product", "market": "US", "condition": "used" }, "choose": null }, { "label": "Filter stores", "tool": "find_cheaper", "arguments": { "url": "https://findcheap.ai/sample-product", "market": "US", "condition": "new" }, "choose": { "marketplaces": ["amazon", "walmart", "ebay", "aliexpress", "shein", "other_sites"] } } ], "credits_used": 10 } ``` ## Resolve `POST /v1/resolve` For some results, the Search endpoint only returns top-level data, to maximize search efficiency. These results carry a `resolve_id` instead of a `url`. Calling the Resolve endpoint with a `resolve_id` returns a direct link to the corresponding product on the merchant's website and the merchant's name. An id is valid for up to two hours after the search that produced it. In rare cases, it may expire sooner, so it is advised to resolve any desired ids shortly after the search has completed. ### Request body - `id` (string, required) - The card's `resolve_id`. ### Response | Field | Type | Meaning | | --- | --- | --- | | `request_id` | string | The call's id (a UUID), the one on the account's usage ledger. Quote it when writing to support about the call. | | `resolved` | boolean | true when url holds the retailer's link. | | `url` | string \| null | The product's link on the merchant's website, tracking parameters stripped. null when not resolved. On the Free plan it may be an affiliate link; see Links. | | `retailer` | string \| null | The merchant's name, e.g. "B&H Photo". null when not resolved. | | `credits_used` | number | What the call cost the account: 1 when url holds a link, 0 when the id could not be resolved. | An id that is unknown, expired, or could not be resolved answers `{ "resolved": false, "url": null, "retailer": null, "credits_used": 0 }` with a `200`; it is never an error, and it costs nothing. ### Example call ```bash # The id is a Search card's resolve_id (a card whose url is null). curl https://api.findcheap.ai/v1/resolve \ -H "Authorization: Bearer $FINDCHEAP_API_KEY" \ -H "Content-Type: application/json" \ -d '{"id": "7c1f0e2b4d9a4f3e8b6a2c5d9e1f0a3b"}' ``` ```python import requests # card: an entry of same_product or similar_products # from a Search answer, whose url is None. response = requests.post( "https://api.findcheap.ai/v1/resolve", headers={"Authorization": "Bearer fc_live_..."}, json={"id": card["resolve_id"]}, timeout=30, ) link = response.json() if link["resolved"]: print(link["retailer"], link["url"]) ``` ```javascript // card: an entry of same_product or similar_products // from a Search answer, whose url is null. const response = await fetch("https://api.findcheap.ai/v1/resolve", { method: "POST", headers: { Authorization: `Bearer ${process.env.FINDCHEAP_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ id: card.resolve_id }), }); const { resolved, url, retailer } = await response.json(); ``` ### Example response ```json { "request_id": "7a4d2e9c-1f6b-4c3a-8e5d-2b9f0c7a4e13", "resolved": true, "url": "https://www.bhphotovideo.com/c/product/...", "retailer": "B&H Photo", "credits_used": 1 } ``` ## Feedback `POST /v1/search/{request_id}/feedback` The Feedback endpoint takes a report on how a search went: which cards were useful, which do not belong in their list, a cheaper listing found elsewhere, what was missing. The search is named in the path by its `request_id`, the one its answer opens with. Findcheap uses the reports to improve its results. Sending feedback costs nothing, and the first report on a search gives 1 credit back. The limits: - One report per search. A second report on the same search answers `already_reported` and changes nothing. - A report counts for a search made in the last 20 minutes. After that the call answers `404 search_not_found`. - The first report on a search gives 1 credit back, up to 100 credits a day per account, counted on the UTC day. Past that, a report is still recorded and gives no credit back. - An account can switch feedback off in its dashboard, under Account. A report then answers `403 feedback_off`. - In the rate limits, a feedback call counts as one of the other requests. ### Request body - `rating` (`"good"` | `"partial"` | `"bad"`, required) - How the search went: `"good"`, `"partial"` or `"bad"`. - `useful_cards` (object[], optional) - The cards you showed or recommended, each named by its list and its position in it. Each entry is an object with `list` (`"same_product"` or `"similar_products"`) and `position` (the card's place in that list, counting from 1). - `wrong_cards` (object[], optional) - Cards that do not belong in their list, each named by its list and its position in it, with a reason. Each entry is an object with `list`, `position` and `reason`: `"different_product"` (it is not the product the page sells), `"not_equivalent"` (it is not an acceptable equivalent), `"price_differs"` (the listing's price is not the card's), `"unavailable"` (the listing is gone or out of stock) or `"other"`. - `cheaper_elsewhere` (object[], optional) - Cheaper listings you found that the answer did not have, each with its address and its price. Each entry is an object with `url` (the cheaper listing's address) and `price` (its price, in the market's currency; null when you do not know it). - `missing` (string[], optional) - What you expected and did not get, one short sentence each. - `goal` (string, optional) - What the shopper was trying to do, in one sentence. Nothing personal about the shopper. - `note` (string, optional) - Anything else worth knowing about this search, short. Send the rating and at least one other field: a report with nothing but its rating answers `400 invalid_request`. Each list holds at most 20 entries. Text longer than its limit is cut, not refused: `goal` and each `missing` sentence at 300 characters, `note` at 1,000. ### Response | Field | Type | Meaning | | --- | --- | --- | | `request_id` | string | This feedback call's own id (a UUID), the one on the account's usage ledger. Quote it when writing to support about the call. | | `recorded` | boolean | true when this report was recorded. | | `already_reported` | boolean | true when the search already had a report: the first one stands and this one changed nothing. | | `credits_refunded` | number | The credits this report gave back to the account: 1 for the first report on a search, 0 for a later one or once the day's cap is reached. | | `refunded_today` | number | The credits feedback has given back to the account so far today (UTC), this report's included. | | `daily_refund_cap` | number | The most credits feedback gives back to one account in a day (UTC). | | `daily_cap_reached` | boolean | true when the day's cap is reached: a report is still recorded and gives no credit back until the next day (UTC). | | `credits_used` | number | What the call cost the account: 0. Sending feedback costs nothing. | ### Example call ```bash # The id in the path is the request_id of a Search answer, # at most 20 minutes old. curl https://api.findcheap.ai/v1/search/4ccce67c-650c-4ffb-9b59-0fb1ce138989/feedback \ -H "Authorization: Bearer $FINDCHEAP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "rating": "partial", "useful_cards": [{"list": "same_product", "position": 1}], "wrong_cards": [{"list": "similar_products", "position": 1, "reason": "not_equivalent"}], "goal": "The same shoes for under 100 dollars." }' ``` ```python import requests # answer: a Search answer, at most 20 minutes old. # Its request_id names the search in the path. response = requests.post( f"https://api.findcheap.ai/v1/search/{answer['request_id']}/feedback", headers={"Authorization": "Bearer fc_live_..."}, json={ "rating": "partial", "useful_cards": [{"list": "same_product", "position": 1}], "wrong_cards": [{"list": "similar_products", "position": 1, "reason": "not_equivalent"}], "goal": "The same shoes for under 100 dollars.", }, timeout=30, ) report = response.json() print(report["recorded"], report["credits_refunded"]) ``` ```javascript // answer: a Search answer, at most 20 minutes old. // Its request_id names the search in the path. const response = await fetch(`https://api.findcheap.ai/v1/search/${answer.request_id}/feedback`, { method: "POST", headers: { Authorization: `Bearer ${process.env.FINDCHEAP_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ rating: "partial", useful_cards: [{ list: "same_product", position: 1 }], wrong_cards: [{ list: "similar_products", position: 1, reason: "not_equivalent" }], goal: "The same shoes for under 100 dollars.", }), }); const { recorded, credits_refunded } = await response.json(); ``` ### Example response ```json { "request_id": "9b2f6c1e-3d4a-4f7b-8a5c-6e0d1f2a3b4c", "recorded": true, "already_reported": false, "credits_refunded": 1, "refunded_today": 1, "daily_refund_cap": 100, "daily_cap_reached": false, "credits_used": 0 } ``` ## Links On the Free plan, links to some retailers may be affiliate links: they pass through a redirect (`linksredirect.com`) and land on the same listing. Paid plans always return the listing's own address. ## Errors Every error is an HTTP status with one JSON shape: ```json { "error": { "type": "not_searchable", "message": "The address is not a readable product page (not_a_product_page). Billed as a page read: 1 credit.", "credits_used": 1, "request_id": "c3b8e1d4-6a2f-4e9c-b7d0-5f1a8c2e9b34" } } ``` `credits_used` is what the failed call cost: `0` for every error but the two billed as a page read below. `request_id` is the call's id, as on a `200`; quote it when writing to support. | Status | Type | Meaning | | --- | --- | --- | | 400 | `invalid_request` | A malformed body or a missing field; the message names it. | | 400 | `invalid_url` | The url is not a web address we can fetch; the message says why. | | 400 | `unknown_market` | market is not one of US, CA, AU, IN, GLOBAL. | | 401 | `unauthorized` | No key, or a key that is not valid (revoked keys stop within a minute). | | 402 | `credits_exhausted` | The account has used its plan's credits for the period; the message names the plan and the reset date (monthly from the sign-up date on the free plan, the renewal on a paid one). Nothing else changes on the wire. | | 403 | `account_suspended` | The account is suspended; the message says whom to write to. | | 403 | `feedback_off` | Feedback: feedback is switched off for this account, a setting in its dashboard. | | 404 | `search_not_found` | Feedback: no search with this id was made by this account in the last 20 minutes. | | 422 | `not_searchable` | Search: the address is not a readable product page; the message names the reason. Billed as a page read, 1 credit, because the page was read. | | 422 | `refused` | Search: a used-condition search on grocery or consumable products, or one with no determinable brand. Billed as a page read, 1 credit. | | 429 | `rate_limited` | The account is over one of its per-minute limits (see Rate limits). Retry after the number of seconds in the Retry-After header. | | 502 | `unreachable` | The page could not be fetched right now; the store refused or did not answer. A retry later may succeed. | | 504 | `timeout` | The call ran past its time limit on our side: 30 seconds for Extract (the page was reached but not read in time), 60 seconds for Search. Safe to retry. | | 500 | `search_failed` | Something failed on our side. Safe to retry with backoff. | | 503 | `account_service_unavailable` | The key could not be checked right now (the account service did not answer). Safe to retry in a moment. | ## Rate limits Limits are per account and per minute; the month is bounded by the plan's credits. An account over a limit is answered `429` with a `Retry-After` header. The plans and their prices are on the developers page, https://findcheap.ai/developers.md. | Plan | Credits a month | Searches/min | Other requests/min | API keys | | --- | --- | --- | --- | --- | | Free | 1,000 (100 searches) | 5 | 30 | 1 | | Developer | 5,000 (500 searches) | 20 | 100 | 5 | | Startup | 40,000 (4,000 searches) | 150 | 300 | 10 | | Growth | 250,000 (25,000 searches) | 1,000 | 1,000 | 25 | | Enterprise | Custom | Custom | Custom | Custom | ## Versioning and changes The API is versioned in its path (`/v1`) and the MCP server's tools by name. Within a version we only add: new fields, new optional parameters, new tools. We do not remove or rename a field, a parameter or a tool, or change what one means. A breaking change ships as a new version (`/v2`, or a tool under a new name), and the version it replaces keeps working for at least 30 days after we announce it in the list below. A fix for a security or legal problem may ship sooner. ### Changes - November 19, 2026 - Added: feedback on a search, as `POST /v1/search/{request_id}/feedback` and the `find_cheaper_feedback` tool. - November 18, 2026 - This policy takes effect. --- # Findcheap MCP server > The MCP server reference, as Markdown for agents. The same page for people: https://findcheap.ai/developers/mcp. Index: https://findcheap.ai/llms.txt. Every answer's fields: https://findcheap.ai/developers/docs.md. ## Overview The Findcheap MCP server lets an AI assistant find where a product is sold for less. It offers the capabilities of the Findcheap API as four tools that any MCP client (Claude, Claude Code, Cursor and others) can call in a conversation: 1. **find_cheaper** - takes a product page URL as input and searches the internet to find where the product is available for a lower price. 2. **read_product_page** - takes a product page URL as input and returns structured product data from the page. 3. **resolve_listing** - a utility tool that turns a result's `resolve_id` into the merchant's link and name. 4. **find_cheaper_feedback** - records how a search went. The first report on a search gives 1 credit back. Server URL (Streamable HTTP): `https://mcp.findcheap.ai/mcp` Each tool answers exactly what the corresponding API endpoint answers. This page covers how to connect and what each tool takes; every field of the answers is documented in the API reference. The same reference says how the API and these tools are versioned and lists every change, under Versioning and changes. The examples on this page use our sample product page, https://findcheap.ai/sample-product: a copy of a real product page that does not change. Any product page's address works the same way. ## Connect Two ways in, the same account behind both: sign in with your Findcheap account from ChatGPT, Claude.ai, Cursor or any other app that can sign in, or give a developer tool your API key. ### ChatGPT: sign in Findcheap is a plugin in ChatGPT. Open its page there and add it: [Open in ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6afa139e1fec81918f9f5d115c4e28aa) Then sign in: ChatGPT sends you to findcheap.ai, you sign in (or create an account, free) and allow ChatGPT to use it. From then on ChatGPT searches on your plan's credits. ### Claude.ai: sign in In Claude (web, desktop or mobile) open Customize, then Connectors, and add a custom connector: name it Findcheap, enter the server URL below and continue. Under OAuth client choose "Use your own OAuth client" and paste this client ID (there is no secret): - Server URL (Streamable HTTP): `https://mcp.findcheap.ai/mcp` - OAuth client ID for Claude.ai: `d125ba2b-831c-403b-a456-a1141ef32231` Add it, then sign in: Claude sends you to findcheap.ai, you sign in (or create an account, free) and allow Claude to use it. From then on Claude searches on your plan's credits. ### Cursor: sign in Press the button and Cursor asks to add the server: [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=findcheap&config=eyJ1cmwiOiJodHRwczovL21jcC5maW5kY2hlYXAuYWkvbWNwIiwiYXV0aCI6eyJDTElFTlRfSUQiOiIzZTEwZDA2Mi1jMzY2LTRmOGMtYTg1ZC1iODczOTUxNzg3OTMifX0=) Or add it by hand: ```json // .cursor/mcp.json (or the global ~/.cursor/mcp.json) { "mcpServers": { "findcheap": { "url": "https://mcp.findcheap.ai/mcp", "auth": { "CLIENT_ID": "3e10d062-c366-4f8c-a85d-b87395178793" } } } } ``` Then sign in: Cursor sends you to findcheap.ai, you sign in (or create an account, free) and allow Cursor to use it. From then on Cursor searches on your plan's credits. ### Any other app: sign in Any app that can sign in to an MCP server connects with the server URL alone, with no API key. Add the URL in the app: Claude Code: ```bash claude mcp add --transport http findcheap https://mcp.findcheap.ai/mcp claude mcp login findcheap ``` Other apps: ```json // the app's MCP settings file { "mcpServers": { "findcheap": { "url": "https://mcp.findcheap.ai/mcp" } } } ``` Then sign in: the app sends you to findcheap.ai, you sign in (or create an account, free) and allow the app to use it. From then on the app searches on your plan's credits. ### Developer tools: the API key Claude Code, Cursor, the Claude API and your own code take the key the API uses (create one in your dashboard, https://findcheap.ai/signin?next=/dashboard/keys, free). It travels in the `Authorization` header of every request. Claude Code: ```bash claude mcp add --transport http findcheap https://mcp.findcheap.ai/mcp \ --header "Authorization: Bearer fc_live_..." ``` Cursor: ```json // .cursor/mcp.json (or the global ~/.cursor/mcp.json) { "mcpServers": { "findcheap": { "url": "https://mcp.findcheap.ai/mcp", "headers": { "Authorization": "Bearer fc_live_..." } } } } ``` Claude API: ```python import anthropic # The Messages API connects to the server on Anthropic's side: # Claude calls the tools itself, in the middle of the request. client = anthropic.Anthropic() response = client.beta.messages.create( model="claude-opus-5-5", max_tokens=4096, betas=["mcp-client-2025-11-20"], mcp_servers=[{ "type": "url", "url": "https://mcp.findcheap.ai/mcp", "name": "findcheap", "authorization_token": "fc_live_...", }], tools=[{"type": "mcp_toolset", "mcp_server_name": "findcheap"}], messages=[{ "role": "user", "content": "Find these cheaper: https://findcheap.ai/sample-product", }], ) print(response.content[-1].text) ``` Python (the official MCP client): ```python # pip install mcp import asyncio import httpx2 from mcp import Client from mcp.client.streamable_http import streamable_http_client async def main(): headers = {"Authorization": "Bearer fc_live_..."} async with httpx2.AsyncClient(headers=headers, timeout=120) as http: async with Client(streamable_http_client("https://mcp.findcheap.ai/mcp", http_client=http)) as client: result = await client.call_tool("find_cheaper", { "url": "https://findcheap.ai/sample-product", }) for card in result.structured_content["same_product"]: print(card["retailer"], card["price"], card["currency"], card["url"]) asyncio.run(main()) ``` Any other MCP client connects the same way: the server URL above, Streamable HTTP, and the `Authorization` header. ## Authentication Every request carries either your API key or the sign-in token an app holds for you: ``` Authorization: Bearer fc_live_... ``` A request without a valid key or token is answered `401` before anything else happens, which a client reports as a failed connection; the answer also points a client at the server's OAuth metadata, so a client that can sign in knows where to. A key is valid for the API and the MCP server alike, a sign-in for the MCP server, and all of them draw on the same credits and the same rate limits: a `find_cheaper` call costs 10 credits, a `read_product_page` call 1, a `resolve_listing` call 1 and a `find_cheaper_feedback` call nothing (the first report on a search gives 1 credit back); a call that fails costs nothing, except a `find_cheaper` call that stops because the page is not a product page or the used search is refused, which is billed as a page read, 1 credit. The sign-in is standard OAuth 2.1: the server publishes its metadata at `/.well-known/oauth-protected-resource/mcp`, the authorization server is Findcheap's own, an app registers itself (OAuth dynamic client registration, at the `registration_endpoint` in the authorization server's metadata), and PKCE is required. An app's return address is `https`, or `http` on the person's own computer (`localhost`, on any port). ## find_cheaper Takes a product page URL as input and searches the internet for where the product is available for a lower price. It is the Search endpoint as a tool: the agent reads the product page, then searches the marketplaces of the shopper's market. Results are sorted into two arrays, each containing up to 10 results: - `same_product` - listings that match the original product. Sorted by cheapest first. - `similar_products` - acceptable equivalents of the original product. Sorted by cheapest first. It has a maximum budget of 60 seconds, but usually completes much sooner. While it runs, the server sends progress notifications (reading the page, searching, comparing) to clients that display them. Two ways it gets used: - **User-initiated.** A shopper pastes a product link into their assistant and asks for it cheaper; the assistant calls `find_cheaper` and answers with the retailers, prices and links. - **Agent-initiated.** An agent working on a task the user gave it, "buy me a soccer ball", finds a candidate ball on Amazon and calls `find_cheaper` on that page to see whether the same ball, or an equivalent, is sold for less elsewhere before recommending or buying it. In both, there is nothing to build: the assistant decides when to call the tool from its description. ### Parameters - `url` (string, required) - The product page's address (https), as the shopper sees it. - `market` (string) - The shopper's market, the country they are buying in (see Markets in the API reference). If omitted, the market is inferred from the URL; otherwise, it defaults to US. - `marketplaces` (string[]) - Which marketplaces to search. Only marketplaces available in the shopper's market count. If omitted, the agent chooses for the product. Accepted values: `"amazon"`, `"walmart"`, `"ebay"`, `"aliexpress"`, `"shein"`, `"flipkart"`, `"other_sites"`. - `condition` (`"new"` | `"used"`) - Defaults to `"new"`. If set to `"used"`, the agent searches for where the product can be bought secondhand. This search mode is not available in India, and is refused for grocery and consumable products. - `max_results` (integer) - How many listings at most in each list, `1` to `10`; 10 when omitted. Ask for fewer when only the cheapest few matter. The search is the same, and so are the credits. ### Result The Search endpoint's answer, as JSON, in this order: `search` (what was searched: the address, the market, the condition, the cap), `product`, `product_name`, `about_lists` (what the two lists hold for this search), `same_product`, `similar_products`, `page_is_cheapest` and `next_steps` (what can be done next, each with the call that does it). The endpoint's `request_id` and `credits_used` are not in the answer; they are in the result's `_meta` (see The call's id and cost, below). Every field, and the structure of a card, is documented under Search in the API reference (https://findcheap.ai/developers/docs.md). A card whose `url` is `null` carries a `resolve_id` for `resolve_listing`. Each tool also publishes its answer's schema in the tool listing (`outputSchema`: every field, its type and whether it can be null), so a client can check an answer before it shows it. ### Example The call the assistant makes, and the answer trimmed to one card per list: ``` find_cheaper({ "url": "https://findcheap.ai/sample-product" }) ``` ```json { "search": { "url": "https://findcheap.ai/sample-product", "market": "US", "condition": "new", "max_results": 10 }, "product": { "title": "Nike Dunk High By You Custom Men's Shoes", "price": 160.0, "currency": "USD", "brand": "Nike", "url": "https://findcheap.ai/sample-product", "market": "US", "image": "https://findcheap.ai/demo-photos/nike-dunk-high-by-you.png", "in_stock": true, "retailer": null, "coupon": null, "promo_code": null, "shipping_cost": null, "returns_accepted": null, "return_days": null, "return_shipping_paid_by": null, "pack_count": null }, "product_name": "Nike shoes", "about_lists": "same_product holds listings from the original product's brand that look the same or similar. similar_products holds look-alikes from any brand.", "same_product": [ { "title": "Nike Dunk Hi Retro Blue/White Leather Men’s US 11 Sneaker DD1399-102", "price": 69.0, "currency": "USD", "retailer": "eBay", "url": "https://www.ebay.com/itm/178217128667", "resolve_id": null, "image": "https://i.ebayimg.com/images/g/VGwAAeSwwNtqLLg0/s-l500.jpg", "over_page_price": false, "rating": 100.0, "coupon": null, "promo_code": null, "price_before_discount": null, "discount_type": null, "discount_value": null, "shipping_cost": null } ], "similar_products": [ { "title": "Nike By You Dunk High Sail Black FV5511 900 Men's Size 10.5", "price": 59.99, "currency": "USD", "retailer": "eBay", "url": "https://www.ebay.com/itm/354741245174", "resolve_id": null, "image": "https://i.ebayimg.com/images/g/BIAAAOSwl2RkRuKP/s-l500.jpg", "rating": 100.0, "coupon": null, "promo_code": null, "price_before_discount": null, "discount_type": null, "discount_value": null, "shipping_cost": null, "over_page_price": false } ], "page_is_cheapest": false, "next_steps": [ { "label": "Find pre-owned", "tool": "find_cheaper", "arguments": { "url": "https://findcheap.ai/sample-product", "market": "US", "condition": "used" }, "choose": null }, { "label": "Filter stores", "tool": "find_cheaper", "arguments": { "url": "https://findcheap.ai/sample-product", "market": "US", "condition": "new" }, "choose": { "marketplaces": ["amazon", "walmart", "ebay", "aliexpress", "shein", "other_sites"] } } ] } ``` ## read_product_page Takes a product page URL as input and returns structured product data from the page, without searching. It is the Extract endpoint as a tool. It answers within 30 seconds, and has a median response time of 4 seconds. Two ways it gets used: - **User-initiated.** A shopper pastes a product link into their assistant and asks what it sells, what it costs or whether it is in stock; the assistant calls `read_product_page` and answers from the page's data. - **Agent-initiated.** An agent working on a task the user gave it, "compare these three monitors", calls `read_product_page` on each page to get the title, price, brand and stock it needs before comparing them. In both, it answers what the page says and nothing more; `find_cheaper` is the tool that searches. ### Parameters - `url` (string, required) - The product page's address (https). - `market` (string) - The market to read the page from (see Markets in the API reference). If omitted, the market is inferred from the URL; otherwise, it defaults to US. ### Result The Extract endpoint's answer: `is_product_page`, `title`, `image`, `price`, `currency`, `brand`, `in_stock`, `retailer`, `coupon`, `promo_code`, `shipping_cost`, `returns_accepted`, `return_days`, `return_shipping_paid_by`, `url`, `market`, `reason` and `next_steps` (what can be done next for this product: the search for it, with the call that does it). Every field is documented under Extract in the API reference. ### Example ``` read_product_page({ "url": "https://findcheap.ai/sample-product" }) ``` ```json { "is_product_page": true, "url": "https://findcheap.ai/sample-product", "market": "US", "title": "Nike Dunk High By You Custom Men's Shoes", "image": "https://findcheap.ai/demo-photos/nike-dunk-high-by-you.png", "price": 160.0, "currency": "USD", "brand": "Nike", "in_stock": true, "retailer": null, "coupon": null, "promo_code": null, "shipping_cost": null, "returns_accepted": null, "return_days": null, "return_shipping_paid_by": null, "reason": null, "next_steps": [ { "label": "Find this cheaper", "tool": "find_cheaper", "arguments": { "url": "https://findcheap.ai/sample-product", "market": "US" }, "choose": null } ] } ``` ## resolve_listing For some results, `find_cheaper` only returns top-level data, to maximize search efficiency. These results carry a `resolve_id` instead of a `url`. Calling `resolve_listing` with a `resolve_id` returns a direct link to the corresponding product on the merchant's website and the merchant's name. It is the Resolve endpoint as a tool. An id is valid for up to two hours after the search that produced it. In rare cases, it may expire sooner, so it is advised to resolve any desired ids shortly after the search has completed. ### Parameters - `resolve_id` (string, required) - The card's `resolve_id`. ### Result | Field | Type | Meaning | | --- | --- | --- | | `resolved` | boolean | true when url holds the retailer's link. | | `url` | string \| null | The product's link on the merchant's website, tracking parameters stripped. null when not resolved. On the Free plan it may be an affiliate link; see Links in the API reference (https://findcheap.ai/developers/docs.md). | | `retailer` | string \| null | The merchant's name, e.g. "B&H Photo". null when not resolved. | An id that is unknown, expired, or could not be resolved answers `{ "resolved": false, "url": null, "retailer": null }`; it is never an error. ### Example ``` resolve_listing({ "resolve_id": "7c1f0e2b4d9a4f3e8b6a2c5d9e1f0a3b" }) ``` ```json { "resolved": true, "url": "https://www.walmart.com/ip/Soundcore-Q20i/...", "retailer": "Walmart" } ``` ## find_cheaper_feedback Records how a `find_cheaper` search went: which cards were useful, which do not belong in their list, a cheaper listing found elsewhere, what was missing. It is the Feedback endpoint as a tool, and the server's one write tool: it records a report with Findcheap and changes nothing else. A call costs nothing, and the first report on a search gives 1 credit back. The tool names its search by `url`, the product page address the search was run on, because an assistant is shown no call id. The account's latest search of that address in the last 20 minutes is the one meant. The limits are the endpoint's: one report per search, within 20 minutes of it; 1 credit back for the first report on a search, up to 100 credits a day per account, counted on the UTC day; and an account can switch feedback off in its dashboard, under Account. The tool's description says what it records. It does not tell an assistant to send a report. To have an assistant send one after each search, give it the Feedback section of the agent skill, https://findcheap.ai/skills/findcheap/SKILL.md, or call the tool from your own code. ### Parameters - `url` (string, required) - The product page address the search was run on: the `url` you gave `find_cheaper`. - `rating` (`"good"` | `"partial"` | `"bad"`, required) - How the search went: `"good"`, `"partial"` or `"bad"`. - `useful_cards` (object[]) - The cards you showed or recommended, each named by its list and its position in it. Each entry is an object with `list` (`"same_product"` or `"similar_products"`) and `position` (the card's place in that list, counting from 1). - `wrong_cards` (object[]) - Cards that do not belong in their list, each named by its list and its position in it, with a reason. Each entry is an object with `list`, `position` and `reason`: `"different_product"` (it is not the product the page sells), `"not_equivalent"` (it is not an acceptable equivalent), `"price_differs"` (the listing's price is not the card's), `"unavailable"` (the listing is gone or out of stock) or `"other"`. - `cheaper_elsewhere` (object[]) - Cheaper listings you found that the answer did not have, each with its address and its price. Each entry is an object with `url` (the cheaper listing's address) and `price` (its price, in the market's currency; null when you do not know it). - `missing` (string[]) - What you expected and did not get, one short sentence each. - `goal` (string) - What the shopper was trying to do, in one sentence. Nothing personal about the shopper. - `note` (string) - Anything else worth knowing about this search, short. Send the rating and at least one other field. Each list holds at most 20 entries. Text longer than its limit is cut, not refused: `goal` and each `missing` sentence at 300 characters, `note` at 1,000. ### Result The Feedback endpoint's answer: `recorded`, `already_reported`, `credits_refunded`, `refunded_today`, `daily_refund_cap` and `daily_cap_reached`. Every field is documented under Feedback in the API reference. ### Description What the tool tells an assistant about itself, word for word: ``` Record how a find_cheaper search went, so Findcheap can improve its results. Give `url`, the product page address the search was run on, and `rating` (`good`, `partial` or `bad`), with at least one of: `useful_cards` (the cards you showed or recommended), `wrong_cards` (cards that do not belong in their list, each with a `reason`), `cheaper_elsewhere` (a cheaper listing you found that the answer did not have), `missing` (what you expected and did not get), `goal` (what the shopper was trying to do, in one sentence) and `note`. A card is named by its list (`same_product` or `similar_products`) and its position in that list, counting from 1. Keep it short: no page contents, and nothing personal about the shopper. A report counts for a search made in the last 20 minutes, once per search; a second report on the same search changes nothing. The first report on a search gives 1 credit back, up to 100 credits a day. Answers `recorded`, `already_reported`, `credits_refunded` and `daily_cap_reached`. ``` ### Example ``` find_cheaper_feedback({ "url": "https://findcheap.ai/sample-product", "rating": "partial", "useful_cards": [{ "list": "same_product", "position": 1 }], "wrong_cards": [{ "list": "similar_products", "position": 1, "reason": "not_equivalent" }], "goal": "The same shoes for under 100 dollars." }) ``` ```json { "recorded": true, "already_reported": false, "credits_refunded": 1, "refunded_today": 1, "daily_refund_cap": 100, "daily_cap_reached": false } ``` ## The call's id and cost Every result carries two values in its `_meta`, the part of a tool result that a client application can read and an assistant's model is not shown: | Key | Type | Meaning | | --- | --- | --- | | `ai.findcheap/request_id` | string | The call's id (a UUID), the one on the account's usage ledger. Quote it when writing to support about the call. | | `ai.findcheap/credits_used` | number | What the call cost the account: 10 for a search, 1 for a page read, 1 for a link that was resolved, 0 for one that was not, 0 for feedback. | | `ai.findcheap/error` | string | On a tool error only: the error's type, e.g. `not_searchable` (see Errors below). | | `ai.findcheap/searched_at` | string | On a `find_cheaper` answer only: when the search was made, in UTC (`2026-11-14T18:05:09Z`). The prices and links are those of that moment. | A tool error carries the first two as well: the cost is 1 for `not_searchable` and `refused` (the page was read before the search stopped) and 0 for every other error, and the id is absent only when the call was refused before it began (`unauthorized`, `rate_limited`, `account_suspended`, `account_service_unavailable`). The dashboard (https://findcheap.ai/dashboard) lists every recorded call with its id. ## Errors A tool call that cannot be served returns a tool error. Its text is one plain sentence the assistant can read out to the person it is helping, e.g. `This is not a product page, so there is nothing to search for. Send the address of an individual product page to search.` The sentence names no error type and no cost. The type is in the result's `_meta` under `ai.findcheap/error`. The types are the API's (see Errors in the API reference); the API's own messages are worded for developers and differ from these sentences: | Type | Tool | When | | --- | --- | --- | | `invalid_url` | all | The url is not a web address we can fetch; the sentence says why. | | `unknown_market` | all | The market is not one the agent serves. | | `invalid_request` | all | A parameter has the wrong shape, e.g. an unknown marketplace name. | | `not_searchable` | find_cheaper | The page is not a readable product page; the sentence says why. | | `refused` | find_cheaper | A used-condition search for a grocery or consumable product, or for a product with no determinable brand. | | `unreachable` | find_cheaper, read_product_page | The page could not be fetched right now; try again later. | | `timeout` | find_cheaper, read_product_page | The page was reached but could not be read within 30 seconds, or the search did not finish within 60 seconds; try again. | | `rate_limited` | all | The account is over one of its per-minute limits; the sentence says how long to wait. | | `credits_exhausted` | all | The account has used its plan's credits for the period; the sentence names the plan and the reset date (monthly from the sign-up date on the free plan, the renewal on a paid one). | | `unauthorized` | all | The key is missing or wrong (also a 401 when the client connects). | | `account_suspended` | all | The account is suspended; the sentence says whom to write to. | | `account_service_unavailable` | all | The key could not be checked right now; try again in a moment. | | `search_not_found` | find_cheaper_feedback | The account made no search of that address in the last 20 minutes; no feedback is recorded. | | `feedback_off` | find_cheaper_feedback | Feedback is switched off for the account. | ## Rate limits Limits are per account and per minute (the plans are on the developers page, https://findcheap.ai/developers.md). An account has one budget: a `find_cheaper` call counts as a Search request, `read_product_page` as an Extract request, `resolve_listing` as a Resolve request and `find_cheaper_feedback` as a Feedback request, whether made through the MCP server or the API. | Plan | Credits a month | Searches/min | Other requests/min | | --- | --- | --- | --- | | Free | 1,000 (100 searches) | 5 | 30 | | Developer | 5,000 (500 searches) | 20 | 100 | | Startup | 40,000 (4,000 searches) | 150 | 300 | | Growth | 250,000 (25,000 searches) | 1,000 | 1,000 | | Enterprise | Custom | Custom | Custom | --- # Findcheap API: plans and pricing > The developers page, as Markdown for agents. The same page for people: https://findcheap.ai/developers. Index: https://findcheap.ai/llms.txt. The API reference: https://findcheap.ai/developers/docs.md. The MCP server: https://findcheap.ai/developers/mcp.md. ## Give your agents access to Findcheap The world is racing to build computer use agents, and 27% of the tasks that agents are evaluated on involve shopping online (Microsoft's WebTailBench, https://huggingface.co/datasets/microsoft/WebTailBench). Findcheap gives your agent benchmark-smashing intelligence at a fraction of the price. Findcheap takes a product page's address and answers where the product is sold for less: the same product elsewhere, and acceptable equivalents, cheapest first. Four calls: Search, Extract (what a product page sells, without a search), Resolve (a card's merchant link) and Feedback (how a search went). The same four as MCP tools for an assistant. ## Pricing No payment method required. Get started for free: https://findcheap.ai/signin?next=/dashboard/keys (sign in, then create a key). | Plan | Price | Credits a month | Searches a minute | Other requests a minute | API keys | Support | | --- | --- | --- | --- | --- | --- | --- | | Free | $0 | 1,000 | 5 | 30 | 1 | Email | | Developer | $19/month | 5,000 | 20 | 100 | 5 | Email | | Startup | $99/month | 40,000 | 150 | 300 | 10 | Email, Slack | | Growth | $499/month | 250,000 | 1,000 | 1,000 | 25 | Email, Slack | | Enterprise | Custom | Custom | Custom | Custom | Custom | Dedicated support | Enterprise adds custom endpoints, custom rate limits and an SLA, support with affiliate monetization, bulk discounts and zero-data retention: https://findcheap.ai/contact?about=enterprise. Paid plans carry no affiliate links: every link is the listing's own address. On the Free plan, links to some retailers may be affiliate links (see Links in the API reference: https://findcheap.ai/developers/docs.md). A paid plan is a fixed monthly price with no overage: an account at its allotment answers `402` until its credits reset, or upgrades in one click and the new allotment starts at once. The free plan's credits renew monthly from the sign-up date. ### How many credits do I need? | Endpoint | Description | Credits | | --- | --- | --- | | Search | Find the best prices for a given product. | 10 | | Extract | Extract structured product data from a URL. | 1 | | Resolve | Retrieve additional data from small merchants. | 1 | | Feedback | Provide feedback on search results. Refunds 1 credit per search. Strictly optional. | -1 | ## FAQ **Which plan do I need?** The free tier is generous and should cover all personal use and experimentation. If you're unsure which plan to get, it's recommended to start with the free tier and upgrade as you scale. **Can my bill be more than my plan?** No. If you use more credits than your plan allows, calls will answer 402 until your credits reset or you choose to upgrade. You won't be charged for overages. **Do failed calls cost credits?** No, only successful responses consume credits. However, there's one exception: invalid search requests are billed as page reads (1 credit), because the agent has to read the page before it can determine whether the search is valid. ## Documentation - API: call `/v1/search`, `/v1/extract` and `/v1/resolve` from any language or stack. https://findcheap.ai/developers/docs.md - MCP server: connect Findcheap to ChatGPT, Claude, Cursor and more. https://findcheap.ai/developers/mcp.md - SDKs: `pip install findcheap` and `npm install findcheap`, official Python and JavaScript clients. https://github.com/llmbender/findcheap-sdks - For agents: https://findcheap.ai/llms.txt, the OpenAPI spec at https://api.findcheap.ai/v1/openapi.json, the agent skill at https://findcheap.ai/skills/findcheap/SKILL.md. ## Custom endpoints Need a custom endpoint? Drop us a note at https://findcheap.ai/contact?about=custom-endpoints. This can be useful for special cases like: - Searching a specific site, like Temu or Patagonia - Retrieving specific data that a marketplace provides (eg. eBay seller ratings) - Searching within regions that aren't yet supported