Findcheap API

Authentication

Every request carries an API key in the Authorization header. Keys begin with fc_live_ and are issued on request from the access page.

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.

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 TLD to determine its market (.in → India, .co.uk → UK, .com.au → Australia, .ca → Canada); 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.

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

Response

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://www.wearcomet.com/products/astra-burnt-toast", "market": "IN"}'

Example response

{
  "is_product_page": true,
  "url": "https://www.wearcomet.com/products/astra-burnt-toast",
  "market": "IN",
  "title": "Astra BURNT TOAST",
  "image": "https://www.wearcomet.com/cdn/shop/files/...",
  "price": 4899.0,
  "currency": "INR",
  "brand": "wearcomet",
  "in_stock": true,
  "reason": null
}

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 90 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 — the same brand and model as the original product. Sorted by cheapest first.
• similar_products — products that don’t match the same brand and model of the original product, but would be considered acceptable equivalents. Sorted by cheapest first.

Request body

Response

Card structure

Every listing in same_product and similar_products has the following shape:

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.

Example call

# -H adds a header (your key, then the body's format);
# -d is the JSON body. A search takes 20–45 s.
curl https://api.findcheap.ai/v1/search \
  -H "Authorization: Bearer $FINDCHEAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.jlab.com/products/star-spangled-jbuds-lux-anc-headphones"}'

Example response

{
  "product": {
    "title": "Star Spangled JBuds Lux ANC Headphones",
    "price": 99.99, "currency": "USD", "brand": "JLab",
    "image": "https://www.jlab.com/cdn/shop/files/...",
    "url": "https://www.jlab.com/products/star-spangled-jbuds-lux-anc-headphones",
    "market": "US", "in_stock": true
  },
  "same_product": [
    {
      "title": "JLab JBuds Lux ANC Over Ear Headphones Bundle with Go Air Pop+ True Wireless Earbuds, Active Noise Cancelling, Bluetooth",
      "price": 67.5, "currency": "USD",
      "url": "https://www.amazon.com/dp/B0FWTKRMFV",
      "image": "https://m.media-amazon.com/images/I/51KhhANNLVL._AC_SL500_.jpg",
      "retailer": "Amazon", "rating": 4.3, "ratings_count": 79,
      "over_page_price": false
    }
  ],
  "similar_products": [
    {
      "title": "JLab Kids Headphones Active Noise Cancelling Wireless Wired Blue Red",
      "price": 5.99, "currency": "USD",
      "url": "https://www.ebay.com/itm/377483228740",
      "image": "https://i.ebayimg.com/images/g/-QQAAeSw~ttqoREo/s-l500.jpg",
      "retailer": "eBay", "rating": 99.5, "ratings_count": 29294
    }
  ],
  "page_is_cheapest": false,
  "product_name": "JLab JBuds Lux ANC"
}

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

Response

An id that is unknown, expired, or could not be resolved answers { "resolved": false, "url": null, "retailer": null } with a 200; it is never an error.

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

{ "resolved": true, "url": "https://www.bhphotovideo.com/c/product/...", "retailer": "B&H Photo" }

Errors

Every error is an HTTP status with one JSON shape:

{
  "error": {
    "type": "not_searchable",
    "message": "The address is not a readable product page (not_a_product_page)."
  }
}

Rate limits

The rate limits for each plan are listed on the developers page.