{
  "object": "doc",
  "title": "Search products: GET /api/v1/search",
  "description": "Cross-retailer product search with natural-language budgets, filters, sorting and pagination.",
  "section": "API reference",
  "url": "https://cart-route.com/docs/api/search",
  "updated": "2026-09-23",
  "prev": "https://cart-route.com/docs/data",
  "next": "https://cart-route.com/docs/api/products",
  "text": "`GET /api/v1/search` finds products across all 3 retailers and returns, for each, every offer with landed price, best coupon, effective price, stock and a 90-day price verdict. Plain-language budgets in `q` (\"under $400\", \"between 200 and 500\", \"over 1k\") become price filters. Costs 1 credit.\n\r\n\r\nGET https://cart-route.com/api/v1/search\n\r\nPOST https://cart-route.com/api/v1/search (same parameters as a JSON body)\n\r\n\r\n\n## Which parameters does search accept?\n\r\n\r\n  \r\n\n| Name | Type | Default | Description | \r\n    \r\n\n| `q` | string, ≤ 200 |  | What to find, in plain words. Required unless `category` or `brand` is set. | \r\n\n| `category` | string |  | Exact category name: Appliances, Audio, Computing, Fitness, Gaming, Home, Kitchen, Laptops, Office, Other, Outdoor, Phones, TVs, Tools, Wearables. | \r\n\n| `brand` | string |  | Exact brand name, e.g. `Sony`. | \r\n\n| `retailers` | csv (GET) or array (POST) | all | Retailer ids: amazon, bestbuy, ebay. Slugs are also accepted. | \r\n\n| `min_price` | number ≥ 0 |  | Minimum effective price in USD. Overrides a budget parsed from `q`. | \r\n\n| `max_price` | number ≥ 0 |  | Maximum effective price in USD. Overrides a budget parsed from `q`. | \r\n\n| `condition` | string | any | `any`, `new`, or `used` (renewed, refurbished, open box and used). Out-of-stock offers are never returned. | \r\n\n| `include_membership` | boolean | true | Include offers from retailers that require a paid membership to buy. | \r\n\n| `sort` | enum | relevance | `relevance`, `price_asc`, `price_desc`, `savings` (widest retailer spread), `rating`. | \r\n\n| `limit` | integer 1–25 | 10 | Products per page. | \r\n\n| `cursor` | string |  | `next_cursor` from the previous page, unchanged. See [pagination](https://cart-route.com/docs/pagination). | \r\n    \r\n\n\r\n\n\r\nHeaders: `Authorization` (required) and `Idempotency-Key` (optional, see [retries](https://cart-route.com/docs/idempotency)).\n\r\n\r\n\n## How is the query matched?\n\r\nKeywords are matched against identifiers (GTIN, MPN, model), brand, title, category and product keywords, with plurals and common synonyms handled (\"tv\" matches TVs, \"ps5\" matches PlayStation). A one- or two-word query must match every word; longer queries must match at least 60% of their words. Filler words such as \"best\", \"cheap\" and \"deal\" are ignored. The `interpreted` object in the response shows exactly how the query was understood.\n\r\n\r\n\n## What does a GET request look like?\n\r\n\n```\ncurl \"https://cart-route.com/api/v1/search?q=65+inch+oled+tv&condition=new&include_membership=false&sort=price_asc&limit=5\" \\\r\n  -H \"Authorization: Bearer $CARTROUTE_API_KEY\"\n```\n\r\n\r\n\n## What does a POST request look like?\n\r\n\n```\ncurl -X POST \"https://cart-route.com/api/v1/search\" \\\r\n  -H \"Authorization: Bearer $CARTROUTE_API_KEY\" \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -H \"Idempotency-Key: 6c1f0e2a-quote-42\" \\\r\n  -d '{\"q\": \"cordless drill kit\", \"retailers\": [\"amazon\", \"bestbuy\"], \"max_price\": 350}'\n```\n\r\n\r\n\n## What does the response contain?\n\r\n\r\n  \r\n\n| Field | Description | \r\n    \r\n\n| `object` | Always `search_result`. | \r\n\n| `query`, `interpreted` | The input and how it was understood: keywords, parsed price bounds, filters. | \r\n\n| `total_results`, `returned` | Matching products overall, and in this page. | \r\n\n| `next_cursor` | Pass as `cursor` for the next page; `null` on the last page. | \r\n\n| `results[]` | Products; see [the product object](https://cart-route.com/docs/objects#product). Specs are omitted in search; fetch them with [get product](https://cart-route.com/docs/api/products). | \r\n\n| `notes` | Present when nothing matched, with suggestions. | \r\n\n| `credits` | `charged` and `remaining`. | \r\n    \r\n\n\r\n\n\r\n\r\n\n```\n{\n  \"object\": \"search_result\",\n  \"api_version\": \"2026-09-01\",\n  \"data_source\": \"live\",\n  \"request_id\": \"req_2m9x1q0a4b8c7f3k\",\n  \"query\": \"sony wh-1000xm6\",\n  \"interpreted\": {\n    \"keywords\": [\n      \"sony\",\n      \"wh-1000xm6\"\n    ],\n    \"min_price_usd\": null,\n    \"max_price_usd\": null,\n    \"retailers\": \"all\",\n    \"in_stock_only\": false,\n    \"include_membership_retailers\": true,\n    \"sort\": \"relevance\"\n  },\n  \"total_results\": 1,\n  \"returned\": 1,\n  \"next_cursor\": null,\n  \"results\": [\n    {\n      \"object\": \"product\",\n      \"id\": \"prd_0dophw3\",\n      \"slug\": \"sony-wh-1000xm6\",\n      \"title\": \"Sony WH-1000XM6 Wireless Noise Cancelling Headphones\",\n      \"brand\": \"Sony\",\n      \"category\": \"Audio\",\n      \"subcategory\": \"Headphones\",\n      \"identifiers\": {\n        \"gtin\": null,\n        \"mpn\": null,\n        \"model\": \"WH-1000XM6\"\n      },\n      \"rating\": 4.2,\n      \"review_count\": 3975,\n      \"rating_source\": \"Amazon\",\n      \"image_url\": \"https://pisces.bbystatic.com/image2/BestBuy_US/images/products/5c0ff147-1f18-4f75-adbc-680f9fee5308.jpg\",\n      \"released_on\": null,\n      \"summary\": \"Sony WH-1000XM6 Wireless Noise Cancelling Headphones. Cartroute checks Amazon, Best Buy and eBay for listings of this product every 24 hours and records each day's prices.\",\n      \"url\": \"https://cart-route.com/p/sony-wh-1000xm6\",\n      \"price_summary\": {\n        \"best_offer_id\": \"off_0f10sq01vb\",\n        \"best_retailer\": \"eBay\",\n        \"best_effective_price_usd\": 291.26,\n        \"lowest_price_usd\": 199.99,\n        \"highest_price_usd\": 378,\n        \"spread_usd\": 178.01,\n        \"offers_count\": 31,\n        \"in_stock_count\": 31,\n        \"best_condition\": \"new\",\n        \"offers_by_condition\": {\n          \"new\": 20,\n          \"used\": 8,\n          \"renewed\": 3\n        },\n        \"coupons_count\": 0\n      },\n      \"price_insight\": {\n        \"verdict\": \"typical_price\",\n        \"reason\": \"Current lowest price is within the normal 90-day range ($180.00–$259.99).\",\n        \"low_90d_usd\": 180,\n        \"high_90d_usd\": 259.99,\n        \"avg_30d_usd\": 206.72,\n        \"trend_30d_pct\": -23.1,\n        \"is_at_90d_low\": false,\n        \"observations\": 45\n      },\n      \"offers\": [\n        {\n          \"offer_id\": \"off_0f10sq01vb\",\n          \"retailer\": {\n            \"id\": \"ebay\",\n            \"name\": \"eBay\",\n            \"domain\": \"ebay.com\",\n            \"membership_required\": false,\n            \"returns_window_days\": null\n          },\n          \"sku\": \"377622630831\",\n          \"listing_title\": \"Sony WH-1000XM6 Noise Cancelling Wireless Headphones Black\",\n          \"condition\": \"new\",\n          \"seller\": \"bc2to7 (eBay seller)\",\n          \"price_usd\": 280,\n          \"list_price_usd\": null,\n          \"discount_from_list_pct\": 0,\n          \"shipping_usd\": 11.26,\n          \"shipping_stated\": true,\n          \"landed_price_usd\": 291.26,\n          \"best_coupon\": null,\n          \"effective_price_usd\": 291.26,\n          \"coupons\": [],\n          \"availability\": {\n            \"in_stock\": true,\n            \"stock_level\": \"in_stock\",\n            \"delivery_days_min\": null,\n            \"delivery_days_max\": null,\n            \"store_pickup\": false\n          },\n          \"retailer_url\": \"https://www.ebay.com/itm/377622630831\",\n          \"buy_url\": \"https://cart-route.com/go/off_0f10sq01vb\",\n          \"last_checked_at\": \"2026-11-06T18:42:04.433Z\",\n          \"freshness_seconds\": 122108\n        }\n      ]\n    }\n  ],\n  \"credits\": {\n    \"charged\": 1,\n    \"remaining\": 199\n  }\n}\n```\n\r\n\r\n\r\n\n## Which errors can search return?\n\r\n`401 unauthorized`, `402 insufficient_credits`, `422 validation_error` (the body names the `param`, e.g. an unknown retailer id or `limit` above 25) and `429 rate_limited`. See [errors](https://cart-route.com/docs/errors)."
}