Build on Crawlbench.

Overview

The same API serves the phone app, team plans that connect their searches to their own systems, and data customers. Each one uses its own kind of key.

The phone app signs in with a session key (cb_sess_) bound to one device, on every plan. You never make one.

Base URL

https://api.crawlbench.com/v1

Keys

Send Authorization: Bearer <key> on every call. Make, name and revoke keys in Developers. A key is shown once. A test key (cb_test_) reads your team's real data and never writes: every call but a GET answers 403.

Format

JSON in and out. Times in UTC, ISO 8601 with Z. Money in major units, in the listing’s own currency, with its code.

Quickstart

Make a team key in Developers and keep it in CB_KEY. Then ask for the new listings on your searches.

1List new listings

1import os, requests2KEY = os.environ["CB_KEY"]3 4r = requests.get(5    "https://api.crawlbench.com/v1/listings",6    headers={"Authorization": f"Bearer {KEY}"},7    params={"tab": "new", "sort": "best_deal", "limit": 20},8)9for x in r.json()["data"]:10    print(x["title"], x["price_check"]["rating_label"])

1curl -G https://api.crawlbench.com/v1/listings \2  -H "Authorization: Bearer $CB_KEY" \3  -d tab=new \4  -d sort=best_deal \5  -d limit=20

1const KEY = process.env.CB_KEY;2const res = await fetch(3  "https://api.crawlbench.com/v1/listings?tab=new&sort=best_deal&limit=20",4  { headers: { Authorization: `Bearer ${KEY}` } },5);6const { data, pagination } = await res.json();7for (const x of data) {8  console.log(x.title, x.price_check.rating_label);9}

{  "data": [    {      "id": "1129384756102938",      "title": "2019 Toyota Camry SE",      "price": 15400,      "currency": "USD",      "location": "Dallas, TX",      "first_seen_at": "2026-10-05T09:12:00Z",      "price_check": {        "rating": "super_price",        "rating_label": "Great price",        "expected": 17900,        "low": 15800,        "high": 19900      },      "searches": [{ "id": "Tc7vQ2mX", "name": "Toyota Camry" }],      "saved": false,      "handled": false,      "hidden": false    }  ],  "pagination": { "has_more": true, "after": "1129384756102938" }}

Each listing carries its price check in price_check: the verdict, the usual price and the range most similar listings ask. Pass pagination.after back to get the next page.

2Turn a search off

A search is on or off. Send { "on": false } to stop it, and { "on": true } to start it again.

1r = requests.patch(2    "https://api.crawlbench.com/v1/searches/Tc7vQ2mX",3    headers={"Authorization": f"Bearer {KEY}"},4    json={"on": False},5)6print(r.json()["on"])  # False

curl -X PATCH https://api.crawlbench.com/v1/searches/Tc7vQ2mX \  -H "Authorization: Bearer $CB_KEY" \  -H "Content-Type: application/json" \  -d '{ "on": false }'

1const off = await fetch("https://api.crawlbench.com/v1/searches/Tc7vQ2mX", {2  method: "PATCH",3  headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },4  body: JSON.stringify({ on: false }),5});6console.log((await off.json()).on); // false

{  "id": "Tc7vQ2mX",  "name": "Toyota Camry",  "sentence": "2019 Toyota Camry under $16,000, anywhere in Texas",  "on": false,  "problem": null}

Reference

The main routes, by what they work on. The full reference, with every field, is built from https://api.crawlbench.com/v1/openapi.json.

Webhooks

Add an endpoint in Developers, or with a team key at POST /v1/webhooks, and pick the events it gets. Each endpoint has its own signing secret and a Send a test button.

Check the signature

Every message carries x-crawlbench-signature: t=<unix>,v1=<hex>, an HMAC-SHA256 of "<t>.<raw body>" with your signing secret. Reject messages older than 5 minutes.

1import hashlib, hmac, time2 3def verify(raw_body: bytes, header: str, secret: str) -> bool:4    parts = dict(p.split("=", 1) for p in header.split(","))5    t, sig = parts["t"], parts["v1"]6    if time.time() - int(t) > 300:7        return False  # older than 5 minutes8    signed = f"{t}.".encode() + raw_body9    want = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()10    return hmac.compare_digest(want, sig)11 12ok = verify(request.get_data(), request.headers["x-crawlbench-signature"], SECRET)

The message

When a delivery fails, we retry with backoff for 24 hours. Then the endpoint shows as failing in Developers, and its owner gets one email.

Events

Data API and AI agents

Rate limits and errors

These rules hold for every call, on every key.

1curl https://api.crawlbench.com/v1/searches \2  -H "Authorization: Bearer $CB_KEY" \3  -H "Content-Type: application/json" \4  -H "Idempotency-Key: 6b1f0d6e-3c2a-4e8b-9a51-2f7d9c0e4b11" \5  -d '{ "sentence": "2019 Toyota Camry under $16,000 in Texas" }'

{  "error": {    "code": "search_limit_reached",    "message": "All 20 searches are on. Turn one off or change plan."  }}

Changelog