Findcheap API

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.

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 (a free account comes with 1,000 credits a month, no card). The key is shown once, at creation.

HTTP header
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.

# 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"])

The code and the issue tracker: github.com/llmbender/findcheap-sdks. The packages: pypi.org/project/findcheap and 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.

marketCurrencyMarketplaces Search compares against
USUSDAmazon, Walmart, eBay, AliExpress, Shein, and other sites
CACADAmazon, AliExpress, other sites
AUAUDAmazon, eBay, AliExpress, other sites
ININRAmazon, Flipkart, other sites
GLOBALUSDAmazon, 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:

Or let your agent do the setup: click the button below to copy the setup prompt and paste it into the agent of your choice.

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

FieldTypeMeaning
request_idstringThe call's id (a UUID), the one on the account's usage ledger. Quote it when writing to support about the call.
is_product_pagebooleantrue 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.
urlstringThe page the read ended on, after any redirects.
marketstringThe market the page was read in.
titlestring | nullThe product's name as the page states it.
imagestring | nullThe image address of the main product photo.
pricenumber | nullThe standing price a shopper in the market pays: not a first-order, coupon or membership price. null when the page does not show one.
currencystring | nullISO 4217 code of price.
brandstring | nullThe brand, when the page names it.
in_stockboolean | nulltrue 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.
retailerstring | nullThe marketplace the page belongs to ("Amazon", "Flipkart", "eBay"). null for any other store's page.
couponstring | nullA 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_codestring | nullThe code to enter at checkout, when the coupon is a promo code (eBay today). null otherwise.
shipping_costnumber | nullWhat 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_acceptedboolean | nullWhether the seller accepts returns (eBay listings today). null when unknown.
return_daysnumber | nullHow 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" | nullWho pays for return shipping. null when unknown.
reasonstring | nullWhy 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_stepsstep[]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_usednumberWhat 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

# -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"}'

Example response

200 OK
{
  "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
}

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

FieldTypeMeaning
request_idstringThe call's id (a UUID), the one on the account's usage ledger. Quote it when writing to support about the call.
resolvedbooleantrue when url holds the retailer's link.
urlstring | nullThe 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.
retailerstring | nullThe merchant's name, e.g. "B&H Photo". null when not resolved.
credits_usednumberWhat 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

# 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"}'

Example response

200 OK
{
  "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

FieldTypeMeaning
request_idstringThis feedback call's own id (a UUID), the one on the account's usage ledger. Quote it when writing to support about the call.
recordedbooleantrue when this report was recorded.
already_reportedbooleantrue when the search already had a report: the first one stands and this one changed nothing.
credits_refundednumberThe 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_todaynumberThe credits feedback has given back to the account so far today (UTC), this report's included.
daily_refund_capnumberThe most credits feedback gives back to one account in a day (UTC).
daily_cap_reachedbooleantrue when the day's cap is reached: a report is still recorded and gives no credit back until the next day (UTC).
credits_usednumberWhat the call cost the account: 0. Sending feedback costs nothing.

Example call

# 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."
  }'

Example response

200 OK
{
  "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
}

Errors

Every error is an HTTP status with one JSON shape:

Error shape
{
  "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.

StatusTypeMeaning
400invalid_requestA malformed body or a missing field; the message names it.
400invalid_urlThe url is not a web address we can fetch; the message says why.
400unknown_marketmarket is not one of US, CA, AU, IN, GLOBAL.
401unauthorizedNo key, or a key that is not valid (revoked keys stop within a minute).
402credits_exhaustedThe 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.
403account_suspendedThe account is suspended; the message says whom to write to.
403feedback_offFeedback: feedback is switched off for this account, a setting in its dashboard.
404search_not_foundFeedback: no search with this id was made by this account in the last 20 minutes.
422not_searchableSearch: 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.
422refusedSearch: a used-condition search on grocery or consumable products, or one with no determinable brand. Billed as a page read, 1 credit.
429rate_limitedThe account is over one of its per-minute limits (see Rate limits). Retry after the number of seconds in the Retry-After header.
502unreachableThe page could not be fetched right now; the store refused or did not answer. A retry later may succeed.
504timeoutThe 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.
500search_failedSomething failed on our side. Safe to retry with backoff.
503account_service_unavailableThe 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.

PlanCredits a monthSearches/minOther requests/minAPI keys
Free1,000 (100 searches)5301
Developer5,000 (500 searches)201005
Startup40,000 (4,000 searches)15030010
Growth250,000 (25,000 searches)1,0001,00025
EnterpriseCustomCustomCustomCustom

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.