ScrapeKit API Reference

Overview

The ScrapeKit API lets you run the same tools available in the dashboard — lead scraping and email verification — directly from your own backend or automation stack.

All requests are JSON over HTTPS. Scrape and bulk-verify operations are asynchronous: you create a job, poll for status, and fetch the result payload when it completes. Single-email verification is synchronous and returns in under a second.

You'll need an active ScrapeKit account with credits. The API uses the same credit balance as the dashboard — 0.015 credits per lead scraped, 0.005 credits per email verified.

Base URL

All API requests go to a single host. There is no sandbox — use small max_leads values to test without burning credits.

https://scrapekit.ai

Authentication

Every request must include an Authorization header with a Bearer token. Requests without a valid token return 401 Unauthorized.

Authorization: Bearer YOUR_API_KEY

API Keys

Manage your keys from the dashboard. Each key is tied to your account and can be rotated or revoked at any time.

• Generate: go to Dashboard → API and click Create key. You'll see the full key once — copy it immediately.
• Format: keys start with sk_live_ followed by 40 random characters.
• Scope: a single key has access to all endpoints. Use separate keys per environment or integration so you can revoke individually.
• Rotate: deleting a key invalidates it instantly. In-flight jobs continue but no new requests with that key will succeed.

Rate Limits

Rate limits are enforced per API key and vary by endpoint class.

Every response includes three headers so you can track usage without a probe request:

• X-RateLimit-Limit — your cap for this endpoint class.
• X-RateLimit-Remaining — requests left in the current window.
• X-RateLimit-Reset — Unix timestamp when the window resets.

Exceeding the limit returns 429 Too Many Requests with a Retry-After header in seconds. Back off exponentially on repeated 429s.

Errors

Errors use standard HTTP status codes and a single consistent JSON body. Any 4xx means the request was invalid — retrying the same call will fail the same way. 5xx responses are safe to retry with backoff.

Error response body

Every error — from any endpoint, at any status code — returns this exact shape. The top-level object always has one key: error.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits. 0.015 required per lead; balance is 1.20.",
    "request_id": "req_7f2a9c4e1b"
  }
}

HTTP status codes

Common error codes

Examples

{
  "error": {
    "code": "invalid_api_key",
    "message": "API key is invalid or has been revoked.",
    "request_id": "req_8b3d1fa4c9"
  }
}

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits. 0.005 required per email.",
    "request_id": "req_5d22ab7e31"
  }
}

{
  "error": {
    "code": "job_not_found",
    "message": "Job not found.",
    "request_id": "req_1c44ef902b"
  }
}

{
  "error": {
    "code": "job_not_ready",
    "message": "Job is running. Wait until completed before requesting results.",
    "request_id": "req_90fe12ab3c"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Max 60 requests per 60s on this endpoint.",
    "request_id": "req_ac3f7b012d"
  }
}

Credit Accounting

Scraping costs 0.015 credits per lead. Email verification costs 0.005 credits per email. Credits never expire.

When credits are charged

• Scrape jobs: charged per lead as rows are written to the result CSV. If a job produces 312 leads, you are billed 312 × 0.015 = 4.68 credits.
• Bulk verify jobs: charged per email for every address that got an actionable verdict (see Verification result schema). unknown results are auto-refunded — you are only billed for emails we classified (safe / role / catch-all / invalid / disabled / inbox_full / disposable).
• Single email verification: charged 0.005 at response time, with the same unknown-refund rule. The response's credits_used field tells you exactly what was billed.

Creation-time credit check

When you create a job, we check your balance and may clamp the request to what you can afford:

• Scrape: if max_leads × 0.015 exceeds your balance, the effective max_leads is reduced to floor(balance / 0.015). The response's max_leads reflects the clamped value.
• Bulk verify: if the input list is larger than you can afford, the excess is dropped before queueing. The response's total reflects what was actually queued.
• If your balance is zero or you can't afford even one unit of work, the call fails with 402 insufficient_credits.

Terminal-state accounting

Every job-status response includes a live credits_used field reflecting billing so far. The completion-time value is the final amount deducted from your balance.

Pagination

In v1, results endpoints do not paginate — they return the full payload inline in a single response.

Cursor-based pagination may be introduced in a future API version. If it is, it will be an opt-in query parameter — existing clients that do not pass a cursor will continue to receive the full inline response.

Idempotency

Job creation is not idempotent in v1. An Idempotency-Key header is not supported. Retrying a failed POST /api/v1/scrape/jobs or POST /api/v1/verify/jobs will create a second job and charge credits again.

Patterns to avoid duplicate charges

• Only retry on network-level failures (DNS errors, connection resets, read timeouts before any response). These mean the server never received the request.
• Do not retry on 5xx responses from job-creation endpoints without first checking GET /api/v1/{scrape|verify}/jobs-style reconciliation if you keep a client-side request ID. A 5xx may mean the job was already created.
• Use a short in-flight lock on your side, keyed by the job parameters you intend to submit, so a double-click or queue retry can't fire the same POST twice.
• Store the X-Request-Id from every response. If support needs to trace a suspected duplicate charge, that's the only way we can do it.

Read-only endpoints (GET /…) are naturally idempotent and safe to retry freely.

Scraping Endpoints

Run async lead-scrape jobs over Google Maps. Each job takes a niche + location and returns structured business contact records.

{
  "query": "dentists",
  "location": "Austin, Texas",
  "max_leads": 500,
  "verify_emails": true,
  "webhook_url": "https: 0 
}

curl https: 0 
  -H "Authorization: Bearer $SCRAPEKIT_KEY" \
  -H "Content-Type: application/json" \
  -d  1 

const res = await fetch("https: 0 
  method: "POST",
  headers: {
    "Authorization":  1 ,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "dentists",
    location: "Austin, Texas",
    max_leads: 500,
    verify_emails: true,
  }),
});
const job = await res.json();

import os, requests

res = requests.post(
    "https: 0 
    headers={"Authorization": f"Bearer {os.environ[ 1 ]}"},
    json={
        "query": "dentists",
        "location": "Austin, Texas",
        "max_leads": 500,
        "verify_emails": True,
    },
)
job = res.json()

{
  "job_id": "sk_job_4f7a9b1c",
  "status": "queued",
  "query": "dentists",
  "location": "Austin, Texas",
  "max_leads": 500,
  "verify_emails": true,
  "estimated_credits": 7.5,
  "created_at": "2026-04-21T10:32:14Z"
}

curl https: 0 
  -H "Authorization: Bearer $SCRAPEKIT_KEY"

const res = await fetch(
  "https: 0 
  { headers: { "Authorization":  1  } },
);
const job = await res.json();

import os, requests
job = requests.get(
    "https: 0 
    headers={"Authorization": f"Bearer {os.environ[ 1 ]}"},
).json()

{
  "job_id": "sk_job_4f7a9b1c",
  "status": "running",
  "query": "dentists",
  "location": "Austin, Texas",
  "progress": {
    "scraped": 214,
    "verified": 198,
    "target": 500
  },
  "credits_used": 3.21,
  "error": null,
  "created_at": "2026-04-21T10:32:14Z",
  "updated_at": "2026-04-21T10:34:51Z"
}

curl https: 0 
  -H "Authorization: Bearer $SCRAPEKIT_KEY"

const res = await fetch(
  "https: 0 
  { headers: { "Authorization":  1  } },
);
const { results, results_count } = await res.json();

import os, requests
data = requests.get(
    "https: 0 
    headers={"Authorization": f"Bearer {os.environ[ 1 ]}"},
).json()
leads = data["results"]

{
  "job_id": "sk_job_4f7a9b1c",
  "status": "completed",
  "results_count": 487,
  "credits_used": 7.305,
  "results": [
    {
      "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
      "name": "Smile Austin Dental",
      "address": "1200 Congress Ave, Austin, TX 78701",
      "phone": "+1 512 555 0142",
      "website": "https: 0 
      "rating": 4.8,
      "reviews_count": 312,
      "lat": 30.2672,
      "lng": -97.7431,
      "category": "Dentist",
      "emails_found": "hello@smileaustin.com;admin@smileaustin.com"
    },
    {
      "place_id": "ChIJP3yTRiTtEmsReNnn3KhLp8s",
      "name": "Downtown Dental Group",
      "address": "500 W 5th St, Austin, TX 78701",
      "phone": "+1 512 555 0177",
      "website": "https: 1 
      "rating": 4.6,
      "reviews_count": 208,
      "lat": 30.2681,
      "lng": -97.7465,
      "category": "Dentist",
      "emails_found": "info@downtown-dental.com"
    }
  ]
}

Email Verification Endpoints

Verify a single email in real time, or submit a list as an async bulk job. Both use MX lookup plus SMTP mailbox probing for ~99% accuracy. See the Verify Status Taxonomy for the nine possible verdicts.

{
  "email": "hello@smileaustin.com"
}

curl https: 0 
  -H "Authorization: Bearer $SCRAPEKIT_KEY" \
  -H "Content-Type: application/json" \
  -d  1 

const res = await fetch("https: 0 
  method: "POST",
  headers: {
    "Authorization":  1 ,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "hello@smileaustin.com" }),
});
const result = await res.json();

import os, requests
result = requests.post(
    "https: 0 
    headers={"Authorization": f"Bearer {os.environ[ 1 ]}"},
    json={"email": "hello@smileaustin.com"},
).json()

{
  "email": "hello@smileaustin.com",
  "status": "safe",
  "score": 95,
  "reason": null,
  "checks": {
    "syntax": "pass",
    "mx": "pass",
    "smtp": "pass",
    "disposable": false,
    "role_account": false,
    "catch_all": false,
    "free_provider": false
  },
  "credits_used": 0.005
}

{
  "emails": [
    "a@example.com",
    "b@example.com",
    "c@example.com"
  ],
  "webhook_url": "https: 0 
}

curl https: 0 
  -H "Authorization: Bearer $SCRAPEKIT_KEY" \
  -H "Content-Type: application/json" \
  -d  1 

const res = await fetch("https: 0 
  method: "POST",
  headers: {
    "Authorization":  1 ,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    emails: ["a@example.com", "b@example.com", "c@example.com"],
    webhook_url: "https: 2 
  }),
});
const job = await res.json();

import os, requests
job = requests.post(
    "https: 0 
    headers={"Authorization": f"Bearer {os.environ[ 1 ]}"},
    json={
        "emails": ["a@example.com", "b@example.com", "c@example.com"],
        "webhook_url": "https: 2 
    },
).json()

{
  "job_id": "sk_verify_c1d2e3f4",
  "status": "queued",
  "total": 12500,
  "estimated_credits": 62.5,
  "created_at": "2026-04-21T10:38:01Z"
}

curl https: 0 
  -H "Authorization: Bearer $SCRAPEKIT_KEY"

const res = await fetch(
  "https: 0 
  { headers: { "Authorization":  1  } },
);
const job = await res.json();

import os, requests
job = requests.get(
    "https: 0 
    headers={"Authorization": f"Bearer {os.environ[ 1 ]}"},
).json()

{
  "job_id": "sk_verify_c1d2e3f4",
  "status": "running",
  "total": 12500,
  "processed": 7842,
  "valid": 6310,
  "credits_used": 39.21,
  "error": null,
  "created_at": "2026-04-21T10:38:01Z",
  "updated_at": "2026-04-21T10:42:17Z"
}

curl https: 0 
  -H "Authorization: Bearer $SCRAPEKIT_KEY"

const res = await fetch(
  "https: 0 
  { headers: { "Authorization":  1  } },
);
const { summary, results } = await res.json();

import os, requests
data = requests.get(
    "https: 0 
    headers={"Authorization": f"Bearer {os.environ[ 1 ]}"},
).json()
summary, results = data["summary"], data["results"]

{
  "job_id": "sk_verify_c1d2e3f4",
  "status": "completed",
  "summary": {
    "total": 12500,
    "safe": 8120,
    "role": 1544,
    "catch_all": 987,
    "disposable": 112,
    "invalid": 1403,
    "disabled": 58,
    "inbox_full": 34,
    "unknown": 242
  },
  "credits_used": 61.29,
  "results": [
    {
      "email": "a@example.com",
      "status": "safe",
      "reason": null,
      "role": false,
      "catch_all": false,
      "free_provider": true,
      "overall_score": 88
    },
    {
      "email": "b@example.com",
      "status": "invalid",
      "reason": "mailbox not found",
      "role": false,
      "catch_all": false,
      "free_provider": true,
      "overall_score": 0
    },
    {
      "email": "c@example.com",
      "status": "catch_all",
      "reason": null,
      "role": false,
      "catch_all": true,
      "free_provider": false,
      "overall_score": 55
    },
    {
      "email": "d@example.com",
      "status": "role",
      "reason": null,
      "role": true,
      "catch_all": false,
      "free_provider": false,
      "overall_score": 80
    },
    {
      "email": "e@example.com",
      "status": "disposable",
      "reason": "disposable domain",
      "role": false,
      "catch_all": false,
      "free_provider": false,
      "overall_score": 0
    },
    {
      "email": "f@example.com",
      "status": "unknown",
      "reason": "smtp unreachable",
      "role": false,
      "catch_all": false,
      "free_provider": true,
      "overall_score": 15
    }
  ]
}

Jobs — Cancellation

A single endpoint cancels either a scrape or a bulk verify job. See Credit Accounting for how credits already consumed are handled.

curl -X POST https: 0 
  -H "Authorization: Bearer $SCRAPEKIT_KEY"

const res = await fetch(
  "https: 0 
  { method: "POST", headers: { "Authorization":  1  } },
);
const r = await res.json();

import os, requests
r = requests.post(
    "https: 0 
    headers={"Authorization": f"Bearer {os.environ[ 1 ]}"},
).json()

{
  "job_id": "sk_job_4f7a9b1c",
  "status": "cancelled",
  "cancelled_at": "2026-04-21T10:36:02Z",
  "note": "Credits already consumed for partially-completed work are not refunded."
}

Async Job Flow

Scrape jobs and bulk verify jobs follow the same lifecycle. Pick either polling or webhooks — or use webhooks with polling as a fallback.

Recommended polling cadence

• 0 – 60s: poll every 5 seconds.
• 1 – 10 min: poll every 15 seconds.
• 10+ min: poll every 60 seconds, or just wait for the webhook.

A typical scrape job of 500 leads finishes in 2–4 minutes. A bulk verify of 10,000 emails takes 8–15 minutes.

Verification Status Taxonomy

Every verified email is classified into one of nine statuses, each carrying a different deliverability signal. The single-email endpoint and bulk-verify results use the same taxonomy.

Grouping for deliverability decisions

• Deliverable: safe, role, legacy valid — these populate valid on the status endpoint.
• Lower confidence, still deliverable: catch_all, inbox_full — generally safe to send but expect soft bounces or lower reply rates.
• Do not send: disposable, invalid, disabled.
• Retry later: unknown — not billed, safe to re-submit.

Webhooks

Pass a webhook_url (HTTPS required) when creating a scrape or bulk verify job and we'll POST a signed JSON payload as soon as the job reaches a terminal state — no polling required.

Event types

Payload shape

The body is always an object with three top-level keys: event, created_at, and data. The data object mirrors the fields on the corresponding status endpoint and also includes a results_url. Results are never inlined in the webhook — fetch them from results_url with your API key.

scrape.job.completed

{
  "event": "scrape.job.completed",
  "created_at": "2026-04-21T10:41:02Z",
  "data": {
    "job_id": "sk_job_4f7a9b1c",
    "status": "completed",
    "query": "dentists",
    "location": "Austin, Texas",
    "results_count": 487,
    "results_url": "https: 0 
    "credits_used": 7.305
  }
}

scrape.job.failed

{
  "event": "scrape.job.failed",
  "created_at": "2026-04-21T10:43:11Z",
  "data": {
    "job_id": "sk_job_9eb012fa",
    "status": "failed",
    "query": "unicorn breeders",
    "location": "Reykjavik, Iceland",
    "results_count": 0,
    "results_url": "https: 0 
    "credits_used": 0,
    "error": "No businesses found for this query in the target region."
  }
}

verify.job.completed

{
  "event": "verify.job.completed",
  "created_at": "2026-04-21T10:52:44Z",
  "data": {
    "job_id": "sk_verify_c1d2e3f4",
    "status": "completed",
    "total": 12500,
    "processed": 12500,
    "valid": 9664,
    "results_url": "https: 0 
    "credits_used": 61.29
  }
}

verify.job.failed

{
  "event": "verify.job.failed",
  "created_at": "2026-04-21T10:52:44Z",
  "data": {
    "job_id": "sk_verify_d2e3f4c1",
    "status": "failed",
    "total": 12500,
    "processed": 842,
    "valid": 621,
    "results_url": "https: 0 
    "credits_used": 4.21,
    "error": "Worker crashed mid-run"
  }
}

Headers

Signing secret

• Scope: one secret per account (not per key). All webhooks triggered by any of your API keys are signed with the same secret.
• Format: prefix whsec_ followed by 43 URL-safe characters.
• Retrieve / rotate (UI): go to Dashboard → API. A secret is auto-generated the first time you open that panel, and you can rotate it with one click.
• Retrieve / rotate (HTTP): dashboard-session endpoints — authenticate with your logged-in browser session (JWT cookie), not a sk_live_ API key:
  • GET https://scrapekit.ai/api/webhook/secret → { "webhook_secret": "whsec_..." } (auto-creates one if none exists).
  • POST https://scrapekit.ai/api/webhook/secret/rotate → { "webhook_secret": "whsec_...", "rotated_at": "..." } (replaces the current secret immediately).
• Rotation behaviour: rotating is immediate. In-flight webhooks already queued for dispatch are signed with whichever secret is current at send time — if you rotate during a burst, receivers may need to accept either the previous or new secret for a short window.

Signature verification

The signed string is {timestamp}.{raw_body} (the literal timestamp string, a period, then the raw request body bytes before any JSON parsing). Signature is the lowercase hex HMAC-SHA256 of that string keyed with your webhook secret. Compare with a constant-time check and reject any request where the signature doesn't match or the timestamp is more than 5 minutes old (replay protection).

import hmac, hashlib, time

SECRET = b"whsec_..."   0 

def verify(raw_body: bytes, signature: str, timestamp: str) -> bool:
     1 
    try:
        ts = int(timestamp)
    except ValueError:
        return False
    if abs(time.time() - ts) > 300:
        return False
     2 
    signed = timestamp.encode() + b"." + raw_body
    expected = hmac.new(SECRET, signed, hashlib.sha256).hexdigest()
     3 
    return hmac.compare_digest(expected, signature)

 4 
from flask import Flask, request, abort
app = Flask(__name__)

@app.post("/webhooks/scrapekit")
def on_webhook():
    raw = request.get_data()
    sig = request.headers.get("X-ScrapeKit-Signature", "")
    ts  = request.headers.get("X-ScrapeKit-Timestamp", "")
    if not verify(raw, sig, ts):
        abort(401)
    event = request.get_json()
     5 
    return ("", 204)

import crypto from "node:crypto";

const SECRET = "whsec_...";  0 

export function verify(rawBody, signature, timestamp) {
   1 
  const ts = Number(timestamp);
  if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false;
   2 
  const signed = Buffer.concat([Buffer.from(timestamp), Buffer.from("."), rawBody]);
  const expected = crypto.createHmac("sha256", SECRET).update(signed).digest("hex");
   3 
  const a = Buffer.from(expected), b = Buffer.from(signature);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

 4 
import express from "express";
const app = express();
app.post("/webhooks/scrapekit",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const ok = verify(
      req.body,
      req.get("X-ScrapeKit-Signature") || "",
      req.get("X-ScrapeKit-Timestamp") || "",
    );
    if (!ok) return res.sendStatus(401);
    const event = JSON.parse(req.body.toString("utf8"));
     5 
    res.sendStatus(204);
  });

Delivery guarantees

• At-most-once, 10-second timeout. We POST the payload one time with a 10-second socket timeout. If your endpoint returns non-2xx or times out, the delivery is considered failed and is not retried in v1 — you should treat webhooks as a latency optimisation on top of polling, not the sole signal.
• Always have a fallback. For safety-critical flows, pair webhooks with a periodic poll of GET /api/v1/{scrape|verify}/jobs/{id} to reconcile any missed deliveries.
• Respond fast. Return 2xx within 10 seconds. Push heavy work into a queue.

Quickstart

Go from zero to fetched leads in three copy-paste-runnable calls. Uses a small max_leads so you can try without burning credits.

 0 
export SCRAPEKIT_KEY="sk_live_..."

 1 
curl https: 2 
  -H "Authorization: Bearer $SCRAPEKIT_KEY" \
  -H "Content-Type: application/json" \
  -d  3 
 4 

 5 
curl https: 6 
  -H "Authorization: Bearer $SCRAPEKIT_KEY"

 7 
curl https: 8 
  -H "Authorization: Bearer $SCRAPEKIT_KEY"
 9 

const BASE = "https: 0 
const headers = {
  "Authorization":  1 ,
  "Content-Type": "application/json",
};

 2 
const create = await fetch( 3 , {
  method: "POST",
  headers,
  body: JSON.stringify({
    query: "plumbers",
    location: "Dublin, Ireland",
    max_leads: 50,
    verify_emails: true,
  }),
});
const { job_id } = await create.json();

 4 
const deadline = Date.now() + 10 * 60 * 1000;
let job;
while (Date.now() < deadline) {
  await new Promise(r => setTimeout(r, 5000));
  job = await fetch( 5 , { headers }).then(r => r.json());
  if (["completed", "failed", "cancelled"].includes(job.status)) break;
}
if (job.status !== "completed") {
  throw new Error( 6 );
}

 7 
const { results } = await fetch(
   8 ,
  { headers },
).then(r => r.json());
console.log( 9 );

import os, time, requests

BASE = "https: 0 
headers = {"Authorization": f"Bearer {os.environ[ 1 ]}"}

 2 
create = requests.post(
    f"{BASE}/scrape/jobs",
    headers=headers,
    json={
        "query": "plumbers",
        "location": "Dublin, Ireland",
        "max_leads": 50,
        "verify_emails": True,
    },
)
create.raise_for_status()
job_id = create.json()["job_id"]

 3 
deadline = time.time() + 10 * 60
while time.time() < deadline:
    time.sleep(5)
    job = requests.get(f"{BASE}/scrape/jobs/{job_id}", headers=headers).json()
    if job["status"] in ("completed", "failed", "cancelled"):
        break
if job["status"] != "completed":
    raise RuntimeError(f"Job ended with status={job[ 4 ]}: {job.get( 5 ) or  6 }")

 7 
results = requests.get(
    f"{BASE}/scrape/jobs/{job_id}/results",
    headers=headers,
).json()["results"]
print(f"Got {len(results)} leads")

Support

We typically reply to API questions within a few business hours.

Every response — success or error — includes an X-Request-Id header (e.g. req_7f2a9c4e1b). Error responses also include the same value as error.request_id in the body. Always paste this ID into support emails — it's the only way we can trace the exact call on our side.