{
  "object": "doc",
  "title": "How do I make my first Cartroute API call?",
  "description": "Create an account, get a key, and search 12 retailers in under a minute.",
  "section": "Getting started",
  "url": "https://cart-route.com/docs/quickstart",
  "updated": "2026-09-23",
  "prev": "https://cart-route.com/docs",
  "next": "https://cart-route.com/docs/authentication",
  "text": "Create a free account, create an API key in the dashboard, and call `GET https://cart-route.com/api/v1/search` with the key in the `Authorization` header. The whole path takes about a minute and the first 200 searches are free.\n\n## Step 1: How do I get an account and credits?\n\n[Sign up](https://cart-route.com/signup) with your name, email and a password. 100 credits are added immediately. Click the link in the confirmation email and 100 more are added, once. An agent can also register on a person's behalf with [`POST /api/v1/accounts`](https://cart-route.com/docs/api/accounts).\n\n## Step 2: How do I create an API key?\n\nOpen the [dashboard](https://cart-route.com/dashboard), name the key (for example \"production agent\") and press Create key. The key starts with `cr_live_` and is shown exactly once, because Cartroute stores only its hash. Put it in an environment variable:\n\n```\nexport CARTROUTE_API_KEY=\"cr_live_...\"\n```\n\n## Step 3: How do I run the first search?\n\n  curl\n  Python\n  TypeScript\n\n```\ncurl \"https://cart-route.com/api/v1/search?q=noise+cancelling+headphones+under+%24400&in_stock=true\" \\\n  -H \"Authorization: Bearer $CARTROUTE_API_KEY\"\n```\n\n```\nimport os\nimport requests\n\nresp = requests.get(\n    \"https://cart-route.com/api/v1/search\",\n    params={\"q\": \"noise cancelling headphones under $400\", \"in_stock\": \"true\"},\n    headers={\"Authorization\": f\"Bearer {os.environ['CARTROUTE_API_KEY']}\"},\n    timeout=15,\n)\nresp.raise_for_status()\nfor product in resp.json()[\"results\"]:\n    s = product[\"price_summary\"]\n    print(product[\"title\"], \"-\", s[\"best_retailer\"], s[\"best_effective_price_usd\"])\n```\n\n```\nconst url = new URL(\"https://cart-route.com/api/v1/search\");\nurl.searchParams.set(\"q\", \"noise cancelling headphones under $400\");\nurl.searchParams.set(\"in_stock\", \"true\");\n\nconst res = await fetch(url, {\n  headers: { Authorization: `Bearer ${process.env.CARTROUTE_API_KEY}` },\n});\nif (!res.ok) throw new Error((await res.json()).detail);\nconst body = await res.json();\nfor (const p of body.results) {\n  console.log(p.title, p.price_summary.best_retailer, p.price_summary.best_effective_price_usd);\n}\n```\n\n## What comes back?\n\nA `search_result` with the products that matched, each carrying `price_summary`, `price_insight` and an `offers` array. This is a trimmed real response from the catalog:\n\n```\n{\n  \"object\": \"search_result\",\n  \"data_source\": \"sandbox\",\n  \"query\": \"sony wh-1000xm6\",\n  \"total_results\": 1,\n  \"results\": [\n    {\n      \"id\": \"prd_0dophw3\",\n      \"title\": \"Sony WH-1000XM6 Wireless Noise Cancelling Headphones\",\n      \"price_summary\": {\n        \"best_offer_id\": \"off_1piefxe\",\n        \"best_retailer\": \"Newegg\",\n        \"best_effective_price_usd\": 343.99,\n        \"lowest_price_usd\": 343.99,\n        \"highest_price_usd\": 454.99,\n        \"spread_usd\": 111,\n        \"offers_count\": 7,\n        \"in_stock_count\": 6,\n        \"coupons_count\": 4\n      },\n      \"price_insight\": {\n        \"verdict\": \"good_time_to_buy\",\n        \"reason\": \"Current lowest price is at or within 1% of the 90-day low of $342.99.\"\n      },\n      \"offers\": [\n        {\n          \"retailer\": \"Newegg\",\n          \"price_usd\": 343.99,\n          \"shipping_usd\": 0,\n          \"effective_price_usd\": 343.99,\n          \"availability\": {\n            \"in_stock\": true\n          }\n        }\n      ]\n    }\n  ],\n  \"credits\": {\n    \"charged\": 1,\n    \"remaining\": 199\n  }\n}\n```\n\nCompare offers on `effective_price_usd`. Every field is described in [response objects](https://cart-route.com/docs/objects).\n\n## What should I read next?\n\n- [Search reference](https://cart-route.com/docs/api/search): filters, sorting, budgets and pagination.\n\n- [MCP server](https://cart-route.com/docs/mcp): skip the HTTP code and give an agent the tools directly.\n\n- [Errors](https://cart-route.com/docs/errors) and [retries](https://cart-route.com/docs/idempotency): what to do when a call fails."
}