# Bolt Scraper API & Developer Documentation

> Complete developer reference for Bolt Scraper REST APIs, Real-time Google Maps search, Website enrichment, Telegram Bot, Multi-Webhooks, and automation pipelines.
> Base URL: `https://boltscraper.com/api/v1`
> Web Portal: `https://app.boltscraper.com`
> Telegram Bot: `@boltcloudscraperbot`

---

## Architecture Overview

Bolt Scraper provides two distinct scraping architectures depending on your product latency and throughput requirements:

| Architecture | Best For | Typical Latency | Key Endpoints | Output Delivery |
| :--- | :--- | :--- | :--- | :--- |
| **Real-time Search API** | Live search bars, interactive SaaS widgets, chatbots, on-demand enrichment | Real-time Synchronous | `POST /v1/maps/search`<br>`POST /v1/reviews/search`<br>`POST /v1/website/scrape` | Synchronous JSON response body (zero polling required) |
| **Background Job API** | Bulk lead generation, scraping entire cities, bulk reviews crawls, scheduled batch workflows | Asynchronous Batch (Scales to 100k+ records) | `POST /v1/maps/jobs`<br>`POST /v1/reviews/jobs`<br>`POST /v1/website/jobs` | Automated Webhooks or downloadable CSV export links |

---

## Table of Contents

- [Authentication & API Keys](#authentication--api-keys)
- [Rate Limits & Error Handling](#rate-limits--error-handling)
- [Google Maps Scraper API](#google-maps-scraper-api)
  - [Real-time Search API (`POST /v1/maps/search`)](#real-time-search-api-post-v1mapssearch)
  - [Create Scrape Job (`POST /v1/maps/jobs`)](#create-scrape-job-post-v1mapsjobs)
  - [List Recent Jobs (`GET /v1/maps/jobs`)](#list-recent-jobs-get-v1mapsjobs)
  - [Get Job Status (`GET /v1/maps/jobs/:id`)](#get-job-status-get-v1mapsjobsid)
  - [Download Gmap CSV (`GET /v1/maps/jobs/:id/download`)](#download-gmap-csv-get-v1mapsjobsiddownload)
  - [Pause Scraping Job (`POST /v1/maps/jobs/:id/pause`)](#pause-scraping-job-post-v1mapsjobsidpause)
  - [Resume Scraping Job (`POST /v1/maps/jobs/:id/resume`)](#resume-scraping-job-post-v1mapsjobsidresume)
  - [Stop Scraping Job (`POST /v1/maps/jobs/:id/stop`)](#stop-scraping-job-post-v1mapsjobsidstop)
- [Google Maps Reviews Scraper API](#google-maps-reviews-scraper-api)
  - [Real-time Reviews Search (`POST /v1/reviews/search`)](#real-time-reviews-search-post-v1reviewssearch)
  - [Create Reviews Job (`POST /v1/reviews/jobs`)](#create-reviews-job-post-v1reviewsjobs)
  - [List Recent Reviews Jobs (`GET /v1/reviews/jobs`)](#list-recent-reviews-jobs-get-v1reviewsjobs)
  - [Get Reviews Job Status (`GET /v1/reviews/jobs/:id`)](#get-reviews-job-status-get-v1reviewsjobsid)
  - [Get Paginated Reviews Data (`GET /v1/reviews/jobs/:id/reviews`)](#get-paginated-reviews-data-get-v1reviewsjobsidreviews)
  - [Download Reviews CSV (`GET /v1/reviews/jobs/:id/download.csv`)](#download-reviews-csv-get-v1reviewsjobsiddownloadcsv)
  - [Pause Reviews Job (`POST /v1/reviews/jobs/:id/pause`)](#pause-reviews-job-post-v1reviewsjobspause)
  - [Resume Reviews Job (`POST /v1/reviews/jobs/:id/resume`)](#resume-reviews-job-post-v1reviewsjobsresume)
  - [Stop Reviews Job (`POST /v1/reviews/jobs/:id/stop`)](#stop-reviews-job-post-v1reviewsjobsstop)
- [Website Scraper API](#website-scraper-api)
  - [Real-time Website Scrape (`POST /v1/website/scrape`)](#real-time-website-scrape-post-v1websitescrape)
  - [Create Website Job (`POST /v1/website/jobs`)](#create-website-job-post-v1websitejobs)
  - [List Website Jobs (`GET /v1/website/jobs`)](#list-website-jobs-get-v1websitejobs)
  - [Get Job Status (`GET /v1/website/jobs/:id`)](#get-job-status-get-v1websitejobsid)
  - [Download Website CSV (`GET /v1/website/jobs/:id/download`)](#download-website-csv-get-v1websitejobsiddownload)
  - [Stop Website Job (`POST /v1/website/jobs/:id/stop`)](#stop-website-job-post-v1websitejobsidstop)
- [Multi-Endpoint Webhooks](#multi-endpoint-webhooks)
  - [Webhook Management Endpoints](#webhook-management-endpoints)
  - [HMAC SHA-256 Signature Verification](#hmac-sha-256-signature-verification)
  - [Google Maps Webhook Payloads](#google-maps-webhook-payloads)
  - [Website Scraper Webhook Payloads](#website-scraper-webhook-payloads)
  - [Automation Integrations (Make.com, n8n, Zapier)](#automation-integrations-makecom-n8n-zapier)
- [Telegram Cloud Scraper Bot](#telegram-cloud-scraper-bot)

---

## Authentication & API Keys

All requests require authentication via an API key prefixed with `bs_`. API keys can be managed in the dashboard at **Dashboard → Integrations → API Keys**.

### Request Headers
Pass the key using either standard Bearer token header (recommended) or `X-API-Key`:
```http
Authorization: Bearer bs_YOUR_API_KEY
```
or
```http
X-API-Key: bs_YOUR_API_KEY
Content-Type: application/json
```

### Plan Quotas & Deductions
- API access is enabled across all plans (including Free tiers).
- **Google Maps API**: Draws directly from your monthly lead quota (Free 1k, Basic 50k, Professional 200k, Business 600k, Advanced 1.5M).
- **Google Maps Reviews API**: Draws directly from your monthly review quota (1 credit per extracted review). Plan limits per target: Free 50, Basic 500, Professional+ unlimited extraction.
- **Website Scraper API**: Draws directly from your monthly website crawl quota (Free 1k, Starter 100k, Pro 250k, Elite 1M).
- **Zero Charge on Upstream Failure**: Unreachable domains, DNS failures, or 502 errors deduct 0 credits (any reserved credit is automatically refunded).

---

## Rate Limits & Error Handling

- **Rate Limit**: **60 requests per minute** per API key.
- **Rate Limit Headers Delivered**:
  - `X-RateLimit-Limit`: `60`
  - `X-RateLimit-Remaining`: Requests left in the current minute.
  - `X-RateLimit-Reset`: Seconds remaining until reset.

### Standard HTTP Status Codes

| Status Code | Meaning | Description | Credits Deducted |
| :--- | :--- | :--- | :--- |
| `200 OK` | Success | Request succeeded and data is returned. | Normal Usage |
| `400 Bad Request` | Validation Error | Missing required query parameters or malformed JSON payload. | 0 Credits |
| `401 Unauthorized` | Authentication Failed | Missing, invalid, or expired API key. | 0 Credits |
| `403 Forbidden` | Quota Exceeded | Monthly lead or crawl credits exhausted. Upgrade required. | 0 Credits |
| `404 Not Found` | Resource Not Found | Target Job ID does not exist or has expired. | 0 Credits |
| `429 Too Many Requests` | Rate Limit Exceeded | Exceeded 60 requests/min. Inspect `Retry-After` header. | 0 Credits |
| `502 Bad Gateway` | Target / Upstream Error | Upstream Google Maps or target website unreachable. Automatic refund. | **0 Credits (Refunded)** |

---

## Google Maps Scraper API

### Real-time Search API (`POST /v1/maps/search`)

Synchronously executes a live query against Google Maps using residential proxies and returns structured business listings directly in the HTTP response. Zero polling or webhook setup required.

- **Method**: `POST`
- **Path**: `/api/v1/maps/search`
- **Headers**:
  - `Authorization: Bearer bs_YOUR_API_KEY`
  - `Content-Type: application/json`

#### Request Body Parameters
| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `keyword` | `string` | **Yes** | — | Search query (e.g. `"Coffee shops in Seattle"`, `"Commercial roofing in Dallas, TX"`). |
| `page` | `integer` | No | `1` | Page number to scrape (1 to 15, returning ~20 places per page). |
| `hl` | `string` | No | `"en"` | Two-letter interface language code (e.g. `"en"`, `"es"`, `"de"`, `"fr"`, `"ja"`, `"hi"`). |

#### Example Request (cURL)
```bash
curl -X POST "https://boltscraper.com/api/v1/maps/search" \
  -H "Authorization: Bearer bs_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "Coffee shops in Seattle",
    "page": 1,
    "hl": "en"
  }'
```

#### Example Request (Python)
```python
import requests

url = "https://boltscraper.com/api/v1/maps/search"
headers = {
    "Authorization": "Bearer bs_YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "keyword": "Coffee shops in Seattle",
    "page": 1,
    "hl": "en"
}

res = requests.post(url, headers=headers, json=payload)
data = res.json()
print(f"Retrieved {data['total_results']} places:")
for place in data.get("data", []):
    print(f"- {place.get('Name')}: {place.get('Phone')} | {place.get('Website')}")
```

#### Example Request (JavaScript / Node.js)
```javascript
const res = await fetch('https://boltscraper.com/api/v1/maps/search', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer bs_YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    keyword: 'Coffee shops in Seattle',
    page: 1,
    hl: 'en'
  })
});

const { data, total_results } = await res.json();
console.log(`Found ${total_results} results:`, data);
```

#### Example Response (`200 OK`)
```json
{
  "success": true,
  "status": "success",
  "request": {
    "keyword": "Coffee shops in Seattle",
    "page": 1,
    "hl": "en"
  },
  "pagination": {
    "page": 1,
    "results_returned": 20,
    "total_results": 20,
    "has_next_page": true
  },
  "data": [
    {
      "Keyword": "Coffee shops in Seattle",
      "Name": "Storyville Coffee Pike Place",
      "Full Address": "94 Pike St Top floor Seattle WA 98101",
      "Street Address": "94 Pike St Top floor",
      "Neighborhood": "Pike Place Market",
      "City": "Seattle",
      "Zip": "98101",
      "Municipality": "Seattle",
      "State": "WA",
      "Country": "US",
      "Phone": "(206) 780-5777",
      "Phone Type": "Landline",
      "Is Mobile": "No",
      "Phone Country": "US",
      "International Phone": "+1 206-780-5777",
      "Phone URI": "tel:+12067805777",
      "Website": "https://storyville.com",
      "Clean Website URL": "https://storyville.com",
      "Domain": "storyville.com",
      "Category": "Coffee shop",
      "Second Category": "Bakery",
      "All Categories": "Coffee shop | Bakery | Espresso bar",
      "Google Category IDs": "coffee_shop | bakery | espresso_bar",
      "Claimed": "Yes",
      "Average Rating": 4.6,
      "Review URL": "https://search.google.com/local/reviews?placeid=ChIJbT0mY5JqkFQRzVq7g",
      "Business Status": "OPERATIONAL",
      "Open Now": "Yes",
      "Hours": "Mon-Sun 7:00 AM - 6:00 PM",
      "Latitude": 47.6089,
      "Longitude": -122.3409,
      "Coordinates": "47.6089,-122.3409",
      "Timezone": "America/Los_Angeles",
      "Place ID": "ChIJbT0mY5JqkFQRzVq7g",
      "GMB URL": "https://www.google.com/maps/place/?q=place_id:ChIJbT0mY5JqkFQRzVq7g",
      "CID": "13697921983050183301",
      "Logo URL": "https://lh3.googleusercontent.com/p/example_logo=s1600",
      "Main Photo URL": "https://lh5.googleusercontent.com/p/example_photo=s1600",
      "Favicon URL": "https://t1.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=https://storyville.com&size=48",
      "Review Count": 1420
    }
  ]
}
```

---

### Create Scrape Job (`POST /v1/maps/jobs`)

Creates an asynchronous background scraping job. Used for high-volume extractions across multiple keywords or full cities.

- **Method**: `POST`
- **Path**: `/api/v1/maps/jobs`

#### Request Body Parameters
| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `keywords` | `array \| string` | **Yes** | — | Single keyword or array of keywords. |
| `title` | `string` | No | Auto (e.g. 'Roofers in Austin, TX + 3') | Optional custom job name. If omitted, automatically generated from keywords. |
| `scrape_websites` | `boolean` | No | `false` | Crawl discovered websites for emails, direct phones, and social links. |
| `ultra_mode` | `boolean` | No | `false` | Multi-point grid scanning to extract up to 3x more listings in dense cities. |
| `max_results` | `integer` | No | `None (All)` | Optional maximum listings target per keyword (e.g. 10, 30, 50). If omitted, extracts all available listings. |
| `max_total_leads` | `integer` | No | `None (All)` | Target lead limit across the entire job (e.g. 500, 2000). Finishes the active keyword before stopping without cutting off. |
| `webhook_url` | `string` | No | `null` | Optional completion webhook for this specific job. |

#### Example Request (Python)
```python
import requests

url = "https://boltscraper.com/api/v1/maps/jobs"
headers = {"Authorization": "Bearer bs_YOUR_API_KEY", "Content-Type": "application/json"}
payload = {
    "keywords": [
        "Commercial roofing in Austin, TX",
        "Commercial roofing in Dallas, TX"
    ],
    "scrape_websites": True,
    "ultra_mode": True
}

res = requests.post(url, headers=headers, json=payload)
print("Launched Job ID:", res.json()["job_id"])
```

#### Example Response (`200 OK`)
```json
{
  "success": true,
  "job_id": "map_demo_123",
  "title": "Commercial roofing in Austin, TX",
  "status": "RUNNING",
  "keywords_count": 2,
  "scrape_websites": true,
  "ultra_mode": true,
  "created_at": "2026-09-20T10:00:00Z"
}
```

---

### List Recent Jobs (`GET /v1/maps/jobs`)

Retrieve a paginated list of your recent scraping jobs.

- **Method**: `GET`
- **Path**: `/api/v1/maps/jobs?limit=50`

#### Query Parameters
- `limit` (optional, default `50`, max `50`): Number of jobs to return.

#### Example Response (`200 OK`)
```json
{
  "jobs": [
    {
      "id": "map_demo_123",
      "title": "Commercial roofing in Austin, TX",
      "status": "COMPLETED",
      "leads_count": 284,
      "keywords_count": 2,
      "scrape_websites": true,
      "ultra_mode": true,
      "created_at": "2026-09-20T10:00:00Z",
      "completed_at": "2026-09-20T10:05:22Z"
    }
  ]
}
```

---

### Get Job Status (`GET /v1/maps/jobs/:id`)

Poll real-time status and progress counts for a specific job.

- **Method**: `GET`
- **Path**: `/api/v1/maps/jobs/:id`

#### Path Parameter
- `id` (required): Unique job ID (e.g. `map_demo_123`).

#### Example Response (`200 OK`)
```json
{
  "job": {
    "id": "map_demo_123",
    "title": "Commercial roofing in Austin, TX",
    "status": "RUNNING",
    "leads_count": 142,
    "keywords_count": 2,
    "scrape_websites": true,
    "ultra_mode": true,
    "created_at": "2026-09-20T10:00:00Z",
    "completed_at": null
  }
}
```

---

### Download Gmap CSV (`GET /v1/maps/jobs/:id/download`)

Directly download the complete CSV export containing all 60+ enriched columns.

- **Method**: `GET`
- **Path**: `/api/v1/maps/jobs/:id/download`
- **Query Parameters**:
  - `token` (optional): Signed download token (allows direct download via browser without `Authorization` header).

```bash
curl -X GET "https://boltscraper.com/api/v1/maps/jobs/map_demo_123/download" \
  -H "Authorization: Bearer bs_YOUR_API_KEY" \
  -o "export_map_demo_123.csv"
```

---

### Pause Scraping Job (`POST /v1/maps/jobs/:id/pause`)

Temporarily pause an active scraping job. Current batches finish and partial leads remain saved.

- **Method**: `POST`
- **Path**: `/api/v1/maps/jobs/:id/pause`

```bash
curl -X POST "https://boltscraper.com/api/v1/maps/jobs/map_demo_123/pause" \
  -H "Authorization: Bearer bs_YOUR_API_KEY"
```

---

### Resume Scraping Job (`POST /v1/maps/jobs/:id/resume`)

Resume a paused scraping job from where it left off.

- **Method**: `POST`
- **Path**: `/api/v1/maps/jobs/:id/resume`

```bash
curl -X POST "https://boltscraper.com/api/v1/maps/jobs/map_demo_123/resume" \
  -H "Authorization: Bearer bs_YOUR_API_KEY"
```

---

### Stop Scraping Job (`POST /v1/maps/jobs/:id/stop`)

Halt an active scraping job. All leads collected up to that moment are finalized and compiled into your downloadable CSV dataset.

- **Method**: `POST`
- **Path**: `/api/v1/maps/jobs/:id/stop`

```bash
curl -X POST "https://boltscraper.com/api/v1/maps/jobs/map_demo_123/stop" \
  -H "Authorization: Bearer bs_YOUR_API_KEY"
```

---

## Google Maps Reviews Scraper API

### Real-time Reviews Search (`POST /v1/reviews/search`)

Synchronously extracts customer reviews and place metadata from a Google Maps listing without polling or delay. Each request fetches 1 page (10 reviews). Returns structured reviewer information, review ratings, timestamps, review text, photos, and owner replies directly in the HTTP response. Use `next_page_token` to fetch subsequent pages, or use the Asynchronous Reviews Jobs API for bulk extractions.

- **Method**: `POST`
- **Path**: `/api/v1/reviews/search`
- **Headers**:
  - `Authorization: Bearer bs_YOUR_API_KEY`
  - `Content-Type: application/json`

#### Request Body Parameters
| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `query` | `string` | **Yes** | — | Google Maps Place URL, Place ID, or Business Name (e.g. `https://maps.app.goo.gl/...`, `https://www.google.com/maps/place/...`, or `ChIJ...`). Direct URL or Place ID recommended for exact matches. |
| `sort_by` | `string` | No | `"newest"` | Sort order: `"newest"` (default), `"most_relevant"`, `"highest_rating"`, `"lowest_rating"`. |
| `language` | `string` | No | `"en"` | Two-letter language code for reviews and place details (e.g. `"en"`, `"es"`, `"de"`, `"fr"`). |
| `next_page_token` | `string` | No | `null` | Continuation cursor token returned from previous response to fetch the subsequent page (10 reviews). |

#### Example Request (cURL)
```bash
curl -X POST "https://boltscraper.com/api/v1/reviews/search" \
  -H "Authorization: Bearer bs_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "https://maps.google.com/?cid=102381283912",
    "sort_by": "newest",
    "language": "en"
  }'
```

#### Example Request (Python)
```python
import requests

url = "https://boltscraper.com/api/v1/reviews/search"
headers = {
    "Authorization": "Bearer bs_YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "query": "https://maps.google.com/?cid=102381283912",
    "sort_by": "newest",
    "language": "en"
}

res = requests.post(url, headers=headers, json=payload)
data = res.json()
print(f"Place: {data['place']['name']} - Scraped: {data['total_scraped']} reviews")
for r in data.get("data", []):
    print(f"[{r['stars']}★] {r['reviewer']['name']}: {r['review_text'][:80]}...")
```

#### Example Response (`200 OK`)
```json
{
  "status": "success",
  "place": {
    "name": "Priority Roofing Austin",
    "place_id": "ChIJbT0mY5JqkFQRzVq7g",
    "feature_id": "0x8644b59263263d6d:0x874b4344e156ca3",
    "rating": 4.9,
    "total_reviews_google": 342,
    "address": "1204 W 34th St, Austin, TX 78705",
    "website": "https://priorityroofing.com",
    "phone": "+1 512-555-0199"
  },
  "query": "https://maps.google.com/?cid=102381283912",
  "sort_by": "newest",
  "total_scraped": 10,
  "pages_fetched": 1,
  "has_next_page": true,
  "next_page_token": "CAESBkVxdFhPQWRnWWw0bFhVQlF...",
  "data": [
    {
      "review_id": "ChZDSUhNMG9nS0VJQ0FnSUN6MjhpdE1REAE",
      "stars": 5,
      "review_text": "Outstanding service! They replaced our entire roof in two days.",
      "review_date_relative": "2 days ago",
      "review_date_utc": "2026-09-26T14:22:00Z",
      "review_timestamp": 1790432520000,
      "likes_count": 3,
      "review_url": "https://www.google.com/maps/reviews/data=!4m8!14m7...",
      "reviewer": {
        "name": "Sarah Jenkins",
        "avatar_url": "https://lh3.googleusercontent.com/a-/ALV-Uj...",
        "profile_url": "https://www.google.com/maps/contrib/10982312...",
        "is_local_guide": true,
        "local_guide_level": 6,
        "total_reviews": 48,
        "total_photos": 124
      },
      "owner_response": {
        "has_response": true,
        "date_relative": "1 day ago",
        "text": "Thank you so much Sarah! It was our pleasure to take care of your home."
      }
    }
  ]
}
```

---

### Create Reviews Job (`POST /v1/reviews/jobs`)

Initializes an asynchronous background task to scrape up to 25,000+ reviews across single or multiple Google Maps locations simultaneously. Supports pause, resume, auto Google Drive synchronization, and downloadable CSV exports.

- **Method**: `POST`
- **Path**: `/api/v1/reviews/jobs`
- **Headers**:
  - `Authorization: Bearer bs_YOUR_API_KEY`
  - `Content-Type: application/json`

#### Request Body Parameters
| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `queries` | `array \| string` | **Yes** | — | Array of Google Maps Place URLs or Place IDs (e.g. `["ChIJbT0mY5JqkFQRzVq7g", "https://maps.google.com/?cid=..."]`). Also accepts `urls`, `place_ids`, or single `query`. |
| `max_reviews` | `integer` | No | `null` | Maximum reviews to extract per location (Free: max 50, Basic: max 500, Professional+: unlimited extraction). Pass `null` or omit for unlimited reviews up to plan quota. |
| `sort_by` | `string` | No | `"newest"` | Sort criteria: `"newest"` (default), `"most_relevant"`, `"highest_rating"`, `"lowest_rating"`. |
| `cutoff_date` | `string` | No | `null` | Optional relative date cutoff filter: `'7 days'`, `'30 days'`, `'90 days'`, `'6 months'`, `'1 year'`, `'2 years'`. Only reviews newer than this period are extracted. |
| `language` | `string` | No | `"en"` | Two-letter language code (`"en"`, `"es"`, `"fr"`, `"de"`). |
| `title` | `string` | No | Auto | Custom title for the reviews scraping job. |

#### Example Request (cURL)
```bash
curl -X POST "https://boltscraper.com/api/v1/reviews/jobs" \
  -H "Authorization: Bearer bs_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      "https://maps.google.com/?cid=102381283912",
      "ChIJbT0mY5JqkFQRzVq7g"
    ],
    "max_reviews": 500,
    "sort_by": "newest"
  }'
```

#### Example Response (`201 Created`)
```json
{
  "status": "success",
  "message": "Reviews scraping task started successfully (2 targets)",
  "total_created": 1,
  "total_targets": 2,
  "batch_id": "revjob_4b1e82",
  "job_id": "revjob_4b1e82",
  "job": {
    "id": "revjob_4b1e82",
    "title": "Priority Roofing Austin + 1 target",
    "query": "[\"https://maps.google.com/?cid=102381283912\",\"ChIJbT0mY5JqkFQRzVq7g\"]",
    "status": "SCRAPING",
    "max_reviews": 500,
    "sort_by": "newest",
    "reviews_count": 0,
    "created_at": "2026-09-28T15:20:00.000Z"
  }
}
```

---

### List Recent Reviews Jobs (`GET /v1/reviews/jobs`)

Retrieve a paginated list of your recent reviews scraping jobs.

- **Method**: `GET`
- **Path**: `/api/v1/reviews/jobs`
- **Query Parameters**:
  - `limit`: `integer` (Default: `50`, Max: `100`)

```bash
curl -X GET "https://boltscraper.com/api/v1/reviews/jobs?limit=20" \
  -H "Authorization: Bearer bs_YOUR_API_KEY"
```

---

### Get Reviews Job Status (`GET /v1/reviews/jobs/:id`)

Retrieve current execution status, targets count, and progress counters for a reviews scraping job.

- **Method**: `GET`
- **Path**: `/api/v1/reviews/jobs/:id`

```bash
curl -X GET "https://boltscraper.com/api/v1/reviews/jobs/revjob_4b1e82" \
  -H "Authorization: Bearer bs_YOUR_API_KEY"
```

#### Example Response (`200 OK`)
```json
{
  "status": "success",
  "job": {
    "id": "revjob_4b1e82",
    "title": "Priority Roofing Austin",
    "query": "https://maps.google.com/?cid=102381283912",
    "place_name": "Priority Roofing Austin",
    "place_address": "1204 W 34th St, Austin, TX 78705",
    "place_rating": 4.9,
    "status": "COMPLETED",
    "sort_by": "newest",
    "reviews_count": 342,
    "max_reviews": 500,
    "created_at": "2026-09-28T15:20:00.000Z",
    "completed_at": "2026-09-28T15:22:10.000Z"
  }
}
```

---

### Get Paginated Reviews Data (`GET /v1/reviews/jobs/:id/reviews`)

Fetch extracted reviews from a completed or running job with pagination.

- **Method**: `GET`
- **Path**: `/api/v1/reviews/jobs/:id/reviews`
- **Query Parameters**:
  - `limit`: `integer` (Default: `50`, Max: `1000`)
  - `offset`: `integer` (Default: `0`)

```bash
curl -X GET "https://boltscraper.com/api/v1/reviews/jobs/revjob_4b1e82/reviews?limit=50&offset=0" \
  -H "Authorization: Bearer bs_YOUR_API_KEY"
```

---

### Download Reviews CSV (`GET /v1/reviews/jobs/:id/download.csv`)

Download all harvested customer reviews and location metadata as a formatted UTF-8 CSV spreadsheet.

- **Method**: `GET`
- **Path**: `/api/v1/reviews/jobs/:id/download.csv`

```bash
curl -X GET "https://boltscraper.com/api/v1/reviews/jobs/revjob_4b1e82/download.csv" \
  -H "Authorization: Bearer bs_YOUR_API_KEY" \
  --output google_reviews_export.csv
```

---

### Pause Reviews Job (`POST /v1/reviews/jobs/:id/pause`)

Temporarily pause an actively crawling reviews scraping task without losing progress.

- **Method**: `POST`
- **Path**: `/api/v1/reviews/jobs/:id/pause`

```bash
curl -X POST "https://boltscraper.com/api/v1/reviews/jobs/revjob_4b1e82/pause" \
  -H "Authorization: Bearer bs_YOUR_API_KEY"
```

---

### Resume Reviews Job (`POST /v1/reviews/jobs/:id/resume`)

Resume a paused reviews scraping job from its exact pagination checkpoint.

- **Method**: `POST`
- **Path**: `/api/v1/reviews/jobs/:id/resume`

```bash
curl -X POST "https://boltscraper.com/api/v1/reviews/jobs/revjob_4b1e82/resume" \
  -H "Authorization: Bearer bs_YOUR_API_KEY"
```

---

### Stop Reviews Job (`POST /v1/reviews/jobs/:id/stop`)

Permanently stop a reviews scraping task and finalize all harvested reviews.

- **Method**: `POST`
- **Path**: `/api/v1/reviews/jobs/:id/stop`

```bash
curl -X POST "https://boltscraper.com/api/v1/reviews/jobs/revjob_4b1e82/stop" \
  -H "Authorization: Bearer bs_YOUR_API_KEY"
```

---

## Website Scraper API

### Real-time Website Scrape (`POST /v1/website/scrape`)

Synchronously crawls a target website directly and extracts business emails, phone numbers, social links, and metadata without queuing or polling.

- **Method**: `POST`
- **Path**: `/api/v1/website/scrape`
- **Headers**:
  - `Authorization: Bearer bs_YOUR_API_KEY`
  - `Content-Type: application/json`

#### Request Body Parameters
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `url` | `string` | **Yes** | Website domain or URL to crawl (e.g. `"stripe.com"` or `"https://example.com"`). |

#### Example Request (Python)
```python
import requests

url = "https://boltscraper.com/api/v1/website/scrape"
headers = {"Authorization": "Bearer bs_YOUR_API_KEY", "Content-Type": "application/json"}
payload = {"url": "https://example.com"}

res = requests.post(url, headers=headers, json=payload)
data = res.json()
if res.status_code == 200:
    print("Company:", data["data"]["title"])
    print("Emails:", data["data"]["emails"])
    print("Phones:", data["data"]["phones"])
    print("Socials:", data["data"]["social_links"])
elif res.status_code == 502:
    print("Website unreachable (0 credits deducted)")
```

#### Example Response (`200 OK`)
```json
{
  "success": true,
  "status": "success",
  "request": {
    "url": "https://example.com",
    "domain": "example.com"
  },
  "data": {
    "url": "https://example.com",
    "domain": "example.com",
    "title": "Example Company | Cloud Software",
    "meta_description": "Enterprise cloud solutions.",
    "favicon": "https://example.com/favicon.ico",
    "emails": [
      "contact@example.com",
      "sales@example.com"
    ],
    "phones": [
      "+1 555-0199"
    ],
    "has_email": true,
    "has_phone": true,
    "social_links": {
      "linkedin": "https://linkedin.com/company/example",
      "twitter": "https://x.com/example",
      "facebook": "https://facebook.com/example",
      "instagram": "https://instagram.com/example",
      "youtube": "https://youtube.com/@example",
      "github": "https://github.com/example"
    },
    "pages": {
      "contact": "https://example.com/contact",
      "about": "https://example.com/about",
      "team": "https://example.com/team"
    }
  }
}
```

---

### Create Website Job (`POST /v1/website/jobs`)

Submit batch domain URLs to extract business contacts asynchronously.

- **Method**: `POST`
- **Path**: `/api/v1/website/jobs`

#### Request Body Parameters
| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `urls` | `array \| string` | **Yes** | — | Array of domain URLs to crawl. |
| `webhook_url` | `string` | No | — | Optional webhook URL to receive job completion callback. |

#### Example Request (cURL)
```bash
curl -X POST "https://boltscraper.com/api/v1/website/jobs" \
  -H "Authorization: Bearer bs_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://acme.org", "https://globex.com"],
    "webhook_url": "https://webhook.site/YOUR_WEBHOOK_UUID"
  }'
```

---

### List Website Jobs (`GET /v1/website/jobs`)

List recent website extraction tasks and status.

- **Method**: `GET`
- **Path**: `/api/v1/website/jobs?limit=100&include_deleted=false`

---

### Get Job Status (`GET /v1/website/jobs/:id`)

Check live crawl progress, processed count, failed count, and completion status.

- **Method**: `GET`
- **Path**: `/api/v1/website/jobs/:id`

---

### Download Website CSV (`GET /v1/website/jobs/:id/download`)

Download the complete CSV export of extracted website contacts.

- **Method**: `GET`
- **Path**: `/api/v1/website/jobs/:id/download`

```bash
curl -X GET "https://boltscraper.com/api/v1/website/jobs/web_demo_123/download" \
  -H "Authorization: Bearer bs_YOUR_API_KEY" \
  -o "website_leads.csv"
```

---

### Stop Website Job (`POST /v1/website/jobs/:id/stop`)

Halt an active website crawl. Unprocessed URL credits are immediately refunded back to your account.

- **Method**: `POST`
- **Path**: `/api/v1/website/jobs/:id/stop`

---

## Multi-Endpoint Webhooks

Bolt Scraper supports registering up to **5 concurrent webhook endpoints**. Webhooks deliver immediate JSON notifications when scraping tasks finish or change state.

### Webhook Management Endpoints

| Method | Path | Description |
| :--- | :--- | :--- |
| `GET` | `/v1/webhooks` | List all registered webhook endpoints. |
| `POST` | `/v1/webhooks` | Register a new webhook endpoint (`name`, `webhook_url`, `secret`, `platform`). |
| `PUT` | `/v1/webhooks/:id` | Update endpoint URL, secret, platform filter, or active status. |
| `DELETE` | `/v1/webhooks/:id` | Remove a webhook endpoint. |

---

### HMAC SHA-256 Signature Verification

If a `secret` is configured, Bolt Scraper attaches an HMAC SHA-256 signature to the `X-Bolt-Signature` HTTP header in the format `sha256=<hex_digest>`.

#### Verification (Node.js)
```javascript
import crypto from 'crypto';

export function verifyBoltWebhook(rawBodyBuffer, signatureHeader, secret) {
  if (!signatureHeader || !signatureHeader.startsWith('sha256=')) return false;
  const signature = signatureHeader.slice(7);
  
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(rawBodyBuffer);
  const expected = hmac.digest('hex');

  return crypto.timingSafeEqual(Buffer.from(signature, 'hex'), Buffer.from(expected, 'hex'));
}
```

#### Verification (Python)
```python
import hmac
import hashlib

def verify_bolt_webhook(raw_body: bytes, signature_header: str, secret: str) -> bool:
    if not signature_header or not signature_header.startswith("sha256="):
        return False
    signature = signature_header.split("sha256=")[1]
    computed = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, computed)
```

---

### Google Maps Webhook Payloads

#### Supported Events
- `gmap_job.completed`: Scraping completed successfully for all keywords.
- `gmap_job.paused`: Scraping paused due to credit limit (`pause_reason: "CREDIT_LIMIT"`) or user action (`pause_reason: "USER_ACTION"`).
- `gmap_job.stopped`: Scrape job was stopped/cancelled by user. Partial results finalized.

#### Headers Delivered
- `Content-Type: application/json`
- `User-Agent: BoltScraper-Webhook-Delivery/1.0`
- `X-Bolt-Event: gmap_job.completed`
- `X-Bolt-Signature: sha256=<hex_digest>`

#### Payload Schema Example (`gmap_job.completed`)
```json
{
  "event": "gmap_job.completed",
  "job_id": "job_demo_123",
  "title": "Denver Solar Contractors",
  "status": "COMPLETED",
  "total_leads": 500,
  "leads_in_payload": 100,
  "is_truncated": true,
  "keywords_count": 1,
  "scrape_websites": true,
  "ultra_mode": true,
  "completed_at": "2026-09-18T10:04:12.000Z",
  "download_csv_url": "https://boltscraper.com/api/v1/maps/jobs/job_demo_123/download?token=SIGNED_DOWNLOAD_TOKEN",
  "leads": [
    {
      "Keyword": "Denver Solar Contractors",
      "place_id": "ChIJ_example_place_id_123",
      "title": "Example Solar Company",
      "category": "Solar Energy Contractor",
      "phone": "+1 555-0100",
      "website": "https://example.com",
      "email": "contact@example.com",
      "instagram": "https://instagram.com/example",
      "facebook": "https://facebook.com/example",
      "linkedin": "https://linkedin.com/company/example",
      "address": "123 Example Street, Denver, CO 80202",
      "rating": 4.9,
      "reviews_count": 182,
      "business_status": "OPERATIONAL",
      "claimed": true
    }
  ]
}
```

---

### Website Scraper Webhook Payloads

#### Supported Events
- `website_job.completed`: Crawl and extraction finished for all submitted URLs.
- `website_job.stopped`: Crawl was stopped/cancelled by user. Partial results finalized.

#### Payload Schema Example (`website_job.completed`)
```json
{
  "event": "website_job.completed",
  "job_id": "web_demo_123",
  "status": "COMPLETED",
  "job_name": "SaaS Contact Enrichment",
  "platform": "website",
  "total_urls": 100,
  "processed_count": 100,
  "success_count": 98,
  "failed_count": 2,
  "is_truncated": false,
  "results_in_payload": 100,
  "download_csv_url": "https://boltscraper.com/api/v1/website/jobs/web_demo_123/download?token=SIGNED_DOWNLOAD_TOKEN",
  "completed_at": "2026-09-18T10:17:30.000Z",
  "results": [
    {
      "url": "https://example.com",
      "status": "success",
      "emails": ["support@example.com", "hello@example.com"],
      "phones": ["+1 555-0100"],
      "social_links": {
        "linkedin": "https://linkedin.com/company/example",
        "twitter": "https://x.com/example",
        "facebook": "https://facebook.com/example",
        "instagram": "https://instagram.com/example",
        "youtube": "https://youtube.com/@example",
        "github": "https://github.com/example"
      },
      "title": "Example Company",
      "description": "Example company description."
    }
  ]
}
```

---

### Automation Integrations (Make.com, n8n, Zapier)

1. **Make.com**: Create a scenario with a **Custom Webhook** module. Paste your webhook URL into Bolt Scraper dashboard. Use the **Iterator** module over the `leads[]` array to insert contacts into Google Sheets, Airtable, or HubSpot.
2. **n8n**: Add a **Webhook node** (`POST`). Use a **Split Out node** on `leads` to iterate each record.
3. **Zapier**: Create a Zap with **Webhooks by Zapier → Catch Hook**, copy the hook URL into Bolt Scraper, and route leads into Salesforce, Pipedrive, or Mailchimp.

---

## Telegram Cloud Scraper Bot

Manage scraping jobs 24/7 directly via Telegram:
- **Bot Handle**: `@boltcloudscraperbot`
- **Link Account**: Pair your chat via **Dashboard → Integrations → Connect Telegram Bot**.

### Bot Commands
- `/scrape <keywords>`: Launch scrape jobs (supports multi-line or semicolon-delimited lists).
- `/status`: Interactive dashboard to view running jobs with pause, resume, stop, and CSV export buttons.
- `/balance`: Check active plan, leads used, and remaining quota.
- `/export <job_id>`: Delivers completed `.csv` file directly into your Telegram chat.
- **Bulk Keyword File Upload**: Send a `.txt` or `.csv` file directly into Telegram; the bot automatically parses up to 5,000 keywords and initiates the cloud scrape.