ScrapeX API

Run searches, collect leads and read your usage from your own code. JSON over HTTPS, one key per integration.

Introduction

The ScrapeX API lets your own tools run searches, collect leads, export data and read your usage. It is a JSON API over HTTPS. Everything you can do in the dashboard's search, leads and export screens you can do here.

Note: The Developer API is on Growth and Enterprise plans. Outreach and billing are dashboard-only and are not in the API.

Authentication

Create a key in the developer portal and send it in the X-API-Key header on every request. A key looks like sx_live_ followed by random characters and is shown once, when you create it. Keep it secret: anyone with the key can do what the key is allowed to do.

bash

curl https://YOUR-SCRAPEX-HOST/api/me \
  -H "X-API-Key: sx_live_xxxxxxxxxxxxxxxx"

Never put a key in a web page, mobile app or public repository. Call the API from your server.
Revoke a key in the portal the moment you think it has leaked. Revoking is instant.
Keys only work for the workspace that created them.

Key controls

Every key can be limited. Set these when you create a key, and change them later from the portal.

Setting	What it does
Scope	read: GET requests only. write: run searches and exports. admin: also manage team and keys. Set when the key is created.
Allowed features	Pick which parts of the API the key may use: search, leads, exports, social, verify, account, team, keys. Leave all on for full access.
Expiry	The key stops working after 1 to 730 days, or never.
Credit cap	The most credits the key may spend in total. When it is reached, requests that cost credits return 402. The cap is checked one spend at a time, so parallel calls cannot overshoot it.

A request outside a key's allowed features returns 403. An expired or revoked key returns 401.

Tip: Use a separate key per integration, with only the features it needs and a credit cap. If one leaks, you revoke one key.

Quick start: search, then collect leads

Start a search: POST /api/jobs/auto. The reply has an id.
Poll GET /api/jobs/{id} until status is done (queued, running and cancelling are still in progress).
Collect the leads: GET /api/leads?search_id={id}&limit=50. Each call delivers the next leads and charges 1 credit per 20.
Optional: export everything as CSV from GET /api/export/leads.csv.

bash

# 1. start a search
curl -X POST https://YOUR-SCRAPEX-HOST/api/jobs/auto \
  -H "X-API-Key: $SX_KEY" -H "Content-Type: application/json" \
  -d '{"query":"dentist","locations":["Leeds, United Kingdom"],"limit":50}'
# -> {"id": 123, "status": "queued", ...}

# 2. wait until it is done
curl https://YOUR-SCRAPEX-HOST/api/jobs/123 -H "X-API-Key: $SX_KEY"

# 3. collect the leads
curl "https://YOUR-SCRAPEX-HOST/api/leads?search_id=123&limit=50" -H "X-API-Key: $SX_KEY"

python

import time, requests
H = {"X-API-Key": "sx_live_..."}
B = "https://YOUR-SCRAPEX-HOST"
job = requests.post(f"{B}/api/jobs/auto", headers=H,
    json={"query": "dentist", "locations": ["Leeds, United Kingdom"], "limit": 50}).json()
while requests.get(f"{B}/api/jobs/{job['id']}", headers=H).json()["status"] in ("queued", "running", "cancelling"):
    time.sleep(10)
leads = requests.get(f"{B}/api/leads", headers=H, params={"search_id": job["id"], "limit": 50}).json()
for l in leads["items"]:
    print(l["name"], l.get("email"))

javascript

const H = { "X-API-Key": process.env.SX_KEY, "Content-Type": "application/json" };
const B = "https://YOUR-SCRAPEX-HOST";
const job = await (await fetch(`${B}/api/jobs/auto`, { method: "POST", headers: H,
  body: JSON.stringify({ query: "dentist", locations: ["Leeds, United Kingdom"], limit: 50 }) })).json();
let st;
do { await new Promise(r => setTimeout(r, 10000));
  st = (await (await fetch(`${B}/api/jobs/${job.id}`, { headers: H })).json()).status;
} while (["queued", "running", "cancelling"].includes(st));
const leads = await (await fetch(`${B}/api/leads?search_id=${job.id}&limit=50`, { headers: H })).json();

Credits

Action	Cost
Leads delivered (GET /api/leads, POST /api/leads/claim)	1 credit per 20 leads
ICP matches	2 credits per 10 matches
Social scrapers	1 credit per 5 to 20 records, by source (see the guide)
Everything else, including reading data, exports and email verification	Free

Read your balance with GET /api/me (workspace.credits) and per-key spend with GET /api/dev/usage. When credits run out, requests that cost credits return 402 with the amount needed and your balance.

Rate limits

Each key is limited per minute by plan. Over the limit, the API returns 429: wait and retry.

Plan	Requests per minute per key
Growth	120
Enterprise	600

Lead delivery also has hourly, daily and monthly limits per plan (see Plan & Credits). When a window is full the API returns 429 and names the window.

Tip: Poll jobs every 5 to 15 seconds, not in a tight loop. Searches take minutes because every company website is read.

Errors

Errors are JSON: {"detail": "what went wrong and what to do"}.

Status	Meaning
400	The request is wrong (for example an unknown feature or a missing field). Read detail.
401	No key, an unknown or revoked key, or an expired key.
402	Not enough credits, or the key's credit cap is reached.
403	The key's scope or allowed features do not cover this endpoint, or your plan does not include it.
404	Not found, or it belongs to another workspace.
422	A field has the wrong type or is out of range.
429	Rate limit reached. Wait, then retry.
500	Our side. The detail contains a reference (ref) to quote to support.

Webhooks

A webhook is an address on your server that ScrapeX calls when something happens, so you do not have to poll. Add one in the developer portal (or POST /api/dev/webhooks). The address must be a public https:// address. You get a secret when you create it, shown once.

Event	When
search.completed	A search has finished: every source and website crawl is done. Then collect leads with GET /api/leads?search_id=...
search.failed	A search stopped with an error.
webhook.test	You pressed Send test in the portal.

json

{
  "id": "dlv_9f1c2a7be0d34c11",
  "event": "search.completed",
  "created_at": "2026-10-28T13:22:04+00:00",
  "data": {
    "search_id": 123,
    "status": "done",
    "query": "dentist",
    "locations": ["Leeds, United Kingdom"],
    "next": "GET /api/leads?search_id=123"
  }
}

Check the signature

Every call carries X-ScrapeX-Timestamp (unix seconds) and X-ScrapeX-Signature, which is sha256= followed by the hex HMAC-SHA256 of the timestamp, a dot, and the raw request body, using your secret. Compute it yourself and compare in constant time. Reject calls with an old timestamp (more than 5 minutes) to stop replays.

python

import hmac, hashlib, time

def valid(secret: str, headers, raw_body: bytes) -> bool:
    ts = headers["X-ScrapeX-Timestamp"]
    if abs(time.time() - int(ts)) > 300:
        return False
    want = "sha256=" + hmac.new(secret.encode(), ts.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, headers["X-ScrapeX-Signature"])

javascript

import crypto from "node:crypto";
export function valid(secret, headers, rawBody) {
  const ts = headers["x-scrapex-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const want = "sha256=" + crypto.createHmac("sha256", secret).update(ts + "." + rawBody).digest("hex");
  const got = headers["x-scrapex-signature"];
  return want.length === got.length && crypto.timingSafeEqual(Buffer.from(want), Buffer.from(got));
}

Delivery rules

Answer with any 2xx status within 8 seconds. Do the real work afterwards.
If your server fails or times out we retry up to 3 more times, after 5 seconds, 30 seconds and 2 minutes. Use the id to ignore a repeat.
After 10 failed calls in a row the webhook is switched off. Fix your server, then turn it back on in the portal.
Redirects are not followed. Addresses on private networks are refused.
Up to 5 webhooks per workspace. The portal shows the last 15 calls for each.

Conventions

All bodies are JSON (Content-Type: application/json). Exports return CSV.
Times are ISO 8601 in UTC.
Lists use limit and offset where an endpoint offers them. GET /api/leads is different: each call delivers the next leads, so never the same lead twice.
Locations work best as City, Country.
Prefer not to poll? Use webhooks (below).

Keeping keys safe

Store keys in environment variables or a secret manager.
Give each integration its own key with the fewest features and a credit cap.
Set an expiry on keys you hand to contractors.
Watch the portal's per-key calls and errors: a sudden jump means something is wrong.
A limited key can only create keys that are equally limited.

API reference

Every endpoint a key can call, grouped by the feature you switch on or off for a key. Open an endpoint for its fields and an example. A star marks a required field.

Search and find customers

Start searches, ICP / lookalike runs, read jobs and their results Feature name for key settings: search.

GET/api/auto/planAuto Plan

Which sources an 'All sources' search would use for this query + location, and why.

Needs a key with scope read or higher and the search feature.

Query and path parameters

Name	Type	Default	Notes
query	string	-
location	string	-

bash

curl "https://YOUR-SCRAPEX-HOST/api/auto/plan" \
  -H "X-API-Key: $SX_KEY"

GET/api/gapsGap Catalog

Needs a key with scope read or higher and the search feature.

bash

curl "https://YOUR-SCRAPEX-HOST/api/gaps" \
  -H "X-API-Key: $SX_KEY"

GET/api/jobsJobs

Needs a key with scope read or higher and the search feature.

Query and path parameters

Name	Type	Default	Notes
limit	integer	30
all	boolean	false	include the per-source jobs of 'All sources' searches
type	string	-	only jobs of this type, e.g. auto or scrape

bash

curl "https://YOUR-SCRAPEX-HOST/api/jobs?limit=50" \
  -H "X-API-Key: $SX_KEY"

POST/api/jobs/autoAuto Search

Search every source that fits, in parallel; results are merged and listed under this search's id.

Needs a key with scope write or higher and the search feature.

JSON body

Name	Type	Default	Notes
query	string	-	Business type / keyword, e.g. 'dentist'
locations	array of string	-	'City, Country' works best, e.g. 'Manchester, United Kingdom'
limit	integer	100	Max results per source per location
sources	array of string	-	Optional: only these sources (default = all that fit)
crawl	boolean	true
verify	boolean	true	check found companies against official registers afterwards
find_socials	boolean	false	also find the companies' social pages + public page details (slower)
contact	string	"auto"	what counts as a lead: 'email', 'any' (email or phone) or 'auto' (by market: phone counts where small businesses rarely publish an email)
options	object	-

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/jobs/auto" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"dentist","locations":["Leeds, United Kingdom"],"limit":50}'

POST/api/jobs/cancel-allCancel All

Needs a key with scope write or higher and the search feature.

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/jobs/cancel-all" \
  -H "X-API-Key: $SX_KEY"

POST/api/jobs/crawlCrawl

Needs a key with scope write or higher and the search feature.

JSON body

Name	Type	Default	Notes
company_ids	array of integer	-
pending	boolean	true
limit	integer	100
force	boolean	false
retry_failed	boolean	false	put failed sites back in the queue and crawl them again

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/jobs/crawl" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_ids":[],"pending":true,"limit":50}'

POST/api/jobs/discoverDiscover

Needs a key with scope write or higher and the search feature.

JSON body

Name	Type	Default	Notes
source*	string	-	Provider key - see GET /api/providers (e.g. overture, osm, norway, yc)
query	string	-	Business type / keyword, e.g. 'dentist', 'software'
locations	array of string	-	Cities, countries, URLs... depending on the provider
limit	integer	100	Max results per location
crawl	boolean	true
options	object	-	Provider options, e.g. {'require_website': true}, {'find_websites': false}, {'months': 3}

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/jobs/discover" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source":""}'

POST/api/jobs/find-hiringFind Hiring

Who is hiring right now: open roles from the company's own public job board (Greenhouse, Lever, Ashby, Workable, SmartRecruiters, Recruitee). Adds a 'hiring' signal with the role count, departments and a link.

Needs a key with scope write or higher and the search feature.

JSON body

Name	Type	Default	Notes
company_ids	array of integer	-
search_id	integer	-
limit	integer	300
recheck	boolean	false	also re-check companies checked in the last 14 days
guess	boolean	true	if the website links no job board, try the domain name on boards that confirm the company name

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/jobs/find-hiring" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_ids":[],"search_id":123,"limit":50}'

POST/api/jobs/find-socialsFind Socials

Company LinkedIn/Facebook/Instagram/X/YouTube/TikTok pages + public page details (followers, size, industry), from public search results. Company pages only - never personal profiles.

Needs a key with scope write or higher and the search feature.

JSON body

Name	Type	Default	Notes
company_ids	array of integer	-
search_id	integer	-
limit	integer	100
only_missing	boolean	true	skip companies already checked

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/jobs/find-socials" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_ids":[],"search_id":123,"limit":50}'

POST/api/jobs/find-websitesFind Websites

Look up websites for companies that came without one (registries), then crawl them.

Needs a key with scope write or higher and the search feature.

JSON body

Name	Type	Default
company_ids	array of integer	-
limit	integer	100
crawl	boolean	true

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/jobs/find-websites" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_ids":[],"limit":50,"crawl":true}'

POST/api/jobs/importImport

Needs a key with scope write or higher and the search feature.

JSON body

Name	Type	Default
domains	array of string	-
csv	string	-
category	string	-
crawl	boolean	true

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/jobs/import" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains":[],"csv":"","category":""}'

POST/api/jobs/scrapeScrape

Run a scraper now. Results: GET /api/scrapes?job_id=<id>. 1 credit per record found (jobs/posts: per 10).

Needs a key with scope write or higher and the search feature.

JSON body

Name	Type	Default	Notes
kind*	string	-	linkedin.company \| linkedin.jobs \| linkedin.people \| x.profile \| x.posts \| x.followers \| reddit.posts \| company_socials
inputs	array of string	-	URLs, handles, slugs or job keywords, one per item
location	string	-	linkedin.jobs: where, e.g. 'Texas, United States'
limit	integer	25	jobs or posts per input
company_ids	array of integer	-	company_socials: scrape the pages these companies link to
kinds	array of string	-	company_socials: only these kinds
fresh	boolean	false	ignore the shared cache and scrape live (super admin / debugging)
options	object	-	platform filters, e.g. {date_posted, sort, min_favorites, language, since, until, verified_only}

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/jobs/scrape" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":""}'

POST/api/jobs/verifyVerify

Check companies against official registers: confirms they exist and are active, adds legal name, id and directors.

Needs a key with scope write or higher and the search feature.

JSON body

Name	Type	Default
company_ids	array of integer	-
search_id	integer	-
limit	integer	500
recheck	boolean	false

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/jobs/verify" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_ids":[],"search_id":123,"limit":50}'

POST/api/jobs/verify-emailsVerify Emails Job

Background: verify a list, a search's emails, or every email that hasn't been checked yet.

Needs a key with scope write or higher and the search feature.

JSON body

Name	Type	Default	Notes
emails	array of string	-	up to 25 are checked right away; more run as a job
search_id	integer	-	verify the emails found by this search (background job)
force	boolean	false
limit	integer	5000

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/jobs/verify-emails" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":[],"search_id":123,"force":false}'

GET/api/jobs/{job_id}Job

Needs a key with scope read or higher and the search feature.

Query and path parameters

Name	Type	Default	Notes
job_id*	integer	-

bash

curl "https://YOUR-SCRAPEX-HOST/api/jobs/123" \
  -H "X-API-Key: $SX_KEY"

POST/api/jobs/{job_id}/cancelCancel Job

Stop a search and everything it started. Queued jobs stop at once; running ones stop at their next step (and are shown as stopped within seconds even if a slow website is still being read).

Needs a key with scope write or higher and the search feature.

Query and path parameters

Name	Type	Default	Notes
job_id*	integer	-

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/jobs/123/cancel" \
  -H "X-API-Key: $SX_KEY"

POST/api/lookalikeLookalike

Paste your best customer's website: ScrapeX finds more businesses like it (runs an Ideal Customer Profile).

Needs a key with scope write or higher and the search feature.

JSON body

Name	Type	Default	Notes
url*	string	-	your best customer's website
locations	array of string	-	where to look: 'Manchester, United Kingdom'
per_location	integer	100

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/lookalike" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

GET/api/offersOffers List

Needs a key with scope read or higher and the search feature.

bash

curl "https://YOUR-SCRAPEX-HOST/api/offers" \
  -H "X-API-Key: $SX_KEY"

POST/api/offersOffer Create

Needs a key with scope write or higher and the search feature.

JSON body

Name	Type	Default	Notes
name	string	-
description*	string	-	What you sell, in your words: 'AI receptionist that answers missed calls for dental clinics'
website	string	-	your own website (the AI reads it to understand the offer)
locations	array of string	-	where your customers are: 'Manchester, United Kingdom'
business_types	array of string	-	optional: who you sell to (otherwise suggested)
titles	array of string	-
gaps	array of string	-
signal_types	array of string	-
pains	array of string	-
exclude	array of string	-
min_employees	integer	-
max_employees	integer	-
per_location	integer	100
run	boolean	false	start finding customers right away

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/offers" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":""}'

POST/api/offers/suggestOffer Suggest

Preview the ICP ScrapeX would use for this offer (nothing is saved).

Needs a key with scope write or higher and the search feature.

JSON body

Name	Type	Default	Notes
name	string	-
description*	string	-	What you sell, in your words: 'AI receptionist that answers missed calls for dental clinics'
website	string	-	your own website (the AI reads it to understand the offer)
locations	array of string	-	where your customers are: 'Manchester, United Kingdom'
business_types	array of string	-	optional: who you sell to (otherwise suggested)
titles	array of string	-
gaps	array of string	-
signal_types	array of string	-
pains	array of string	-
exclude	array of string	-
min_employees	integer	-
max_employees	integer	-
per_location	integer	100
run	boolean	false	start finding customers right away

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/offers/suggest" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":""}'

DELETE/api/offers/{oid}Offer Delete

Needs a key with scope write or higher and the search feature.

Query and path parameters

Name	Type	Default	Notes
oid*	integer	-

bash

curl -X DELETE "https://YOUR-SCRAPEX-HOST/api/offers/123" \
  -H "X-API-Key: $SX_KEY"

GET/api/offers/{oid}Offer Get

Needs a key with scope read or higher and the search feature.

Query and path parameters

Name	Type	Default	Notes
oid*	integer	-

bash

curl "https://YOUR-SCRAPEX-HOST/api/offers/123" \
  -H "X-API-Key: $SX_KEY"

PATCH/api/offers/{oid}Offer Update

Needs a key with scope write or higher and the search feature.

Query and path parameters

Name	Type	Default	Notes
oid*	integer	-

JSON body

Name	Type	Default
name	string	-
description	string	-
summary	string	-
locations	array of string	-
business_types	array of string	-
titles	array of string	-
gaps	array of string	-
signal_types	array of string	-
pains	array of string	-
exclude	array of string	-
min_employees	integer	-
max_employees	integer	-
per_location	integer	-
status	string	-

bash

curl -X PATCH "https://YOUR-SCRAPEX-HOST/api/offers/123" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My offer","description":"","summary":""}'

POST/api/offers/{oid}/matchOffer Rescore

Needs a key with scope write or higher and the search feature.

Query and path parameters

Name	Type	Default	Notes
oid*	integer	-

JSON body

Name	Type	Default	Notes
ai	boolean	true	use AI research (needs OPENAI_API_KEY) for hot/strong/maybe matches
ai_limit	integer	300
include_existing	boolean	true	also score matching companies already in your database

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/offers/123/match" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ai":true,"ai_limit":300,"include_existing":true}'

GET/api/offers/{oid}/opportunitiesOpportunities

Needs a key with scope read or higher and the search feature.

Query and path parameters

Name	Type	Default	Notes
oid*	integer	-
tier	string	-	hot,strong,maybe (default) \| skip \| all
status	string	-
q	string	-
limit	integer	50
offset	integer	0

bash

curl "https://YOUR-SCRAPEX-HOST/api/offers/123/opportunities?limit=50" \
  -H "X-API-Key: $SX_KEY"

POST/api/offers/{oid}/runOffer Run

Find customers: searches every fitting source for each business type in each location, crawls + audits the websites, verifies, then scores every business against the offer (automatically, as results come in).

Needs a key with scope write or higher and the search feature.

Query and path parameters

Name	Type	Default	Notes
oid*	integer	-

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/offers/123/run" \
  -H "X-API-Key: $SX_KEY"

POST/api/offers/{oid}/stopOffer Stop

Stop an ICP search and everything it started (leads found so far are kept and scored).

Needs a key with scope write or higher and the search feature.

Query and path parameters

Name	Type	Default	Notes
oid*	integer	-

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/offers/123/stop" \
  -H "X-API-Key: $SX_KEY"

GET/api/opportunities/{opid}Opportunity

Needs a key with scope read or higher and the search feature.

Query and path parameters

Name	Type	Default	Notes
opid*	integer	-

bash

curl "https://YOUR-SCRAPEX-HOST/api/opportunities/123" \
  -H "X-API-Key: $SX_KEY"

PATCH/api/opportunities/{opid}Opportunity Update

Needs a key with scope write or higher and the search feature.

Query and path parameters

Name	Type	Default	Notes
opid*	integer	-

JSON body

Name	Type	Default	Notes
status*	string	-	new \| contacted \| meeting \| won \| lost \| not_a_fit

bash

curl -X PATCH "https://YOUR-SCRAPEX-HOST/api/opportunities/123" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":""}'

GET/api/providersProviders

Every data source with plain-English help for the dashboard / n8n.

Needs a key with scope read or higher and the search feature.

bash

curl "https://YOUR-SCRAPEX-HOST/api/providers" \
  -H "X-API-Key: $SX_KEY"

GET/api/search-historySearches History

Past Prospect Discovery searches of THIS workspace (title + location), newest first. Stored server-side so it survives logging out and in. Opening one reloads that search's delivered leads (?search=<id>).

Needs a key with scope read or higher and the search feature.

Query and path parameters

Name	Type	Default	Notes
limit	integer	40

bash

curl "https://YOUR-SCRAPEX-HOST/api/search-history?limit=50" \
  -H "X-API-Key: $SX_KEY"

GET/api/searches/{search_id}Search Summary

Result overview of one search: per-source counts, merged companies, how many have website/email/people.

Needs a key with scope read or higher and the search feature.

Query and path parameters

Name	Type	Default	Notes
search_id*	integer	-

bash

curl "https://YOUR-SCRAPEX-HOST/api/searches/123" \
  -H "X-API-Key: $SX_KEY"

Leads and companies

Deliver leads, read companies, draft emails, reveal, signals Feature name for key settings: leads.

GET/api/companiesCompanies

Needs a key with scope read or higher and the leads feature.

Query and path parameters

Name	Type	Default	Notes
limit	integer	50
offset	integer	0
sort	string	"newest"	newest \| quality \| signals
q	string	-
country	string	-
city	string	-
category	string	-
has_email	boolean	-
has_personal_email	boolean	-
has_phone	boolean	-
has_people	boolean	-
crawl_status	string	-
source	string	-
technology	string	-
min_quality	integer	-
include_branches	boolean	true
search_id	integer	-
verified	string	-
signal	string	-	any \| hiring \| funding \| contract_won \| new_company \| new_website
min_signal	integer	-	minimum signal_score 0-100
min_employees	integer	-
max_employees	integer	-
founded_after	integer	-	founded in or after this year
gap	string	-	website gap, e.g. no_online_booking, no_live_chat, no_https

bash

curl "https://YOUR-SCRAPEX-HOST/api/companies?limit=50&search_id=123" \
  -H "X-API-Key: $SX_KEY"

GET/api/companies/{company_id}Company

Needs a key with scope read or higher and the leads feature.

Query and path parameters

Name	Type	Default	Notes
company_id*	integer	-

bash

curl "https://YOUR-SCRAPEX-HOST/api/companies/123" \
  -H "X-API-Key: $SX_KEY"

POST/api/companies/{company_id}/draft-emailDraft Email

A ready-to-edit cold email for this one business, using what we actually know about it. Uses your OpenAI key for a sharper draft on Growth+ plans; otherwise a template that still uses the real facts.

Needs a key with scope write or higher and the leads feature.

Query and path parameters

Name	Type	Default	Notes
company_id*	integer	-
offer_id	integer	-

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/companies/123/draft-email" \
  -H "X-API-Key: $SX_KEY"

GET/api/leadsLeads

Deliver the next `limit` leads that have an email: de-duplicated (never the same lead twice), with phone and the best contact, emails already unmasked. Costs 1 credit per 20 leads (402 if you have none left).

Needs a key with scope read or higher and the leads feature.

Query and path parameters

Name	Type	Default	Notes
limit	integer	25
topup	boolean	true	if short, start more searching under the same search (max twice)
extra	boolean	false	deliver beyond the number this search was started with
q	string	-
country	string	-
city	string	-
category	string	-
has_email	boolean	-
has_personal_email	boolean	-
has_phone	boolean	-
has_people	boolean	-
crawl_status	string	-
source	string	-
technology	string	-
min_quality	integer	-
include_branches	boolean	true
search_id	integer	-
verified	string	-
signal	string	-	any \| hiring \| funding \| contract_won \| new_company \| new_website
min_signal	integer	-	minimum signal_score 0-100
min_employees	integer	-
max_employees	integer	-
founded_after	integer	-	founded in or after this year
gap	string	-	website gap, e.g. no_online_booking, no_live_chat, no_https

bash

curl "https://YOUR-SCRAPEX-HOST/api/leads?limit=50&search_id=123" \
  -H "X-API-Key: $SX_KEY"

GET/api/leads/availableLeads Available

How many NEW leads with an email match (not yet delivered to you), and how many are still being crawled.

Needs a key with scope read or higher and the leads feature.

Query and path parameters

Name	Type	Default	Notes
want	integer	0
q	string	-
country	string	-
city	string	-
category	string	-
has_email	boolean	-
has_personal_email	boolean	-
has_phone	boolean	-
has_people	boolean	-
crawl_status	string	-
source	string	-
technology	string	-
min_quality	integer	-
include_branches	boolean	true
search_id	integer	-
verified	string	-
signal	string	-	any \| hiring \| funding \| contract_won \| new_company \| new_website
min_signal	integer	-	minimum signal_score 0-100
min_employees	integer	-
max_employees	integer	-
founded_after	integer	-	founded in or after this year
gap	string	-	website gap, e.g. no_online_booking, no_live_chat, no_https

bash

curl "https://YOUR-SCRAPEX-HOST/api/leads/available?search_id=123" \
  -H "X-API-Key: $SX_KEY"

POST/api/leads/claimLeads Claim

Hand out the next N companies that have an email and haven't been handed to this channel before. Best quality first. Also says how many are still being crawled (more will come).

Needs a key with scope write or higher and the leads feature.

JSON body

Name	Type	Default	Notes
channel	string	"n8n"	who takes the leads; each company is handed to a channel only once
search_id	integer	-	only companies from this search (the job id of /api/jobs/auto)
limit	integer	10
min_quality	integer	0
country	string	-
category	string	-
personal_email_only	boolean	false
skip_invalid	boolean	true
signals_first	boolean	true	companies with fresh 'why now' signals (hiring, funding...) first
only_with_signals	boolean	false
offer_id	integer	-	only businesses matched to this offer (Find customers), best first
tiers	string	"hot,strong"	with offer_id: which match tiers to hand out

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/leads/claim" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"n8n","search_id":123,"limit":50}'

GET/api/leads/deliveredLeads Delivered

Every lead already delivered to this workspace (already paid for; emails stay masked until revealed).

Needs a key with scope read or higher and the leads feature.

Query and path parameters

Name	Type	Default
limit	integer	50
offset	integer	0
q	string	-
search_id	integer	-

bash

curl "https://YOUR-SCRAPEX-HOST/api/leads/delivered?limit=50&search_id=123" \
  -H "X-API-Key: $SX_KEY"

GET/api/leads/latestLeads Latest

Newest delivered leads for the dashboard, each with the app page it was found on and its public source link.

Needs a key with scope read or higher and the leads feature.

Query and path parameters

Name	Type	Default	Notes
limit	integer	8

bash

curl "https://YOUR-SCRAPEX-HOST/api/leads/latest?limit=50" \
  -H "X-API-Key: $SX_KEY"

POST/api/revealReveal

Unmask emails. Free: a credit is only used when an email is sent from your Gmail.

Needs a key with scope write or higher and the leads feature.

JSON body

Name	Type	Default	Notes
company_ids	array of integer	-
person_ids	array of integer	-	reveals the person's company (free)

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/reveal" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_ids":[],"person_ids":[]}'

GET/api/scrapeScrape Website

A company website as readable text for the AI (homepage + about/services pages). Replaces Firecrawl.

Needs a key with scope read or higher and the leads feature.

Query and path parameters

Name	Type	Default	Notes
url*	string	-
pages	integer	3

bash

curl "https://YOUR-SCRAPEX-HOST/api/scrape?url=https%3A%2F%2Fexample.com" \
  -H "X-API-Key: $SX_KEY"

GET/api/signals/summarySignals Summary

How many companies have each kind of 'why now' signal, plus the hottest ones.

Needs a key with scope read or higher and the leads feature.

Query and path parameters

Name	Type	Default	Notes
search_id	integer	-

bash

curl "https://YOUR-SCRAPEX-HOST/api/signals/summary?search_id=123" \
  -H "X-API-Key: $SX_KEY"

POST/api/suppressSuppress

Add emails or domains that must never be collected or exported (e.g. someone asked to be removed).

Needs a key with scope write or higher and the leads feature.

JSON body

Name	Type	Default	Notes
values*	array of string	-
reason	string	"requested removal"

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/suppress" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"values":[]}'

GET/api/suppressionsSuppressions

Needs a key with scope read or higher and the leads feature.

Query and path parameters

Name	Type	Default	Notes
limit	integer	500

bash

curl "https://YOUR-SCRAPEX-HOST/api/suppressions?limit=50" \
  -H "X-API-Key: $SX_KEY"

CSV exports

Download leads, companies and scrapes as CSV Feature name for key settings: exports.

GET/api/export/companies.csvExport Companies

CSV export of your leads, with emails visible. Revealing is free.

Needs a key with scope read or higher and the exports feature.

Query and path parameters

Name	Type	Default	Notes
q	string	-
country	string	-
city	string	-
category	string	-
has_email	boolean	-
has_personal_email	boolean	-
has_phone	boolean	-
has_people	boolean	-
crawl_status	string	-
source	string	-
technology	string	-
min_quality	integer	-
include_branches	boolean	true
search_id	integer	-
verified	string	-
signal	string	-	any \| hiring \| funding \| contract_won \| new_company \| new_website
min_signal	integer	-	minimum signal_score 0-100
min_employees	integer	-
max_employees	integer	-
founded_after	integer	-	founded in or after this year
gap	string	-	website gap, e.g. no_online_booking, no_live_chat, no_https

bash

curl "https://YOUR-SCRAPEX-HOST/api/export/companies.csv?search_id=123" \
  -H "X-API-Key: $SX_KEY"

GET/api/export/leads.csvExport Leads

Everything you've been delivered as a lead (email-bearing, de-duplicated). Already paid for - free to re-download.

Needs a key with scope read or higher and the exports feature.

bash

curl "https://YOUR-SCRAPEX-HOST/api/export/leads.csv" \
  -H "X-API-Key: $SX_KEY"

GET/api/export/opportunities.csvExport Opportunities

Needs a key with scope read or higher and the exports feature.

Query and path parameters

Name	Type	Default	Notes
offer_id*	integer	-
tier	string	-

bash

curl "https://YOUR-SCRAPEX-HOST/api/export/opportunities.csv?offer_id=1" \
  -H "X-API-Key: $SX_KEY"

GET/api/export/scrapes.csvExport Scrapes

CSV of one search (job_id) or of everything saved in the workspace. Included from the Growth plan.

Needs a key with scope read or higher and the exports feature.

Query and path parameters

Name	Type	Default
job_id	integer	-
kind	string	-
q	string	-

bash

curl "https://YOUR-SCRAPEX-HOST/api/export/scrapes.csv" \
  -H "X-API-Key: $SX_KEY"

Social scrapers

Social pages and public page details Feature name for key settings: social.

GET/api/scrapersScrapers List

Every scraper, whether a service key is set up for it, and which service it uses.

Needs a key with scope read or higher and the social feature.

bash

curl "https://YOUR-SCRAPEX-HOST/api/scrapers" \
  -H "X-API-Key: $SX_KEY"

GET/api/scrapesScrape Results

job_id = one search; leave it out for everything saved in this workspace (newest first).

Needs a key with scope read or higher and the social feature.

Query and path parameters

Name	Type	Default
job_id	integer	-
kind	string	-
q	string	-
limit	integer	100
offset	integer	0

bash

curl "https://YOUR-SCRAPEX-HOST/api/scrapes?limit=50" \
  -H "X-API-Key: $SX_KEY"

GET/api/scrapes/searchesScrape Searches

Your past social searches (what you looked up and when), newest first, so you can reopen any of them.

Needs a key with scope read or higher and the social feature.

Query and path parameters

Name	Type	Default	Notes
limit	integer	30

bash

curl "https://YOUR-SCRAPEX-HOST/api/scrapes/searches?limit=50" \
  -H "X-API-Key: $SX_KEY"

GET/api/social/companySocial Company

One company's social pages + public page details, from search results.

Needs a key with scope read or higher and the social feature.

Query and path parameters

Name	Type	Default	Notes
name*	string	-
city	string	-

bash

curl "https://YOUR-SCRAPEX-HOST/api/social/company?name=My%20offer" \
  -H "X-API-Key: $SX_KEY"

Email verification

Check whether an address is deliverable Feature name for key settings: verify.

GET/api/mail/verifyVerify One

Check one address: valid | invalid | catch_all | unknown, with the reason. Nothing is sent.

Needs a key with scope read or higher and the verify feature.

Query and path parameters

Name	Type	Default	Notes
email*	string	-
force	boolean	false

bash

curl "https://YOUR-SCRAPEX-HOST/api/mail/verify?email=name%40example.com" \
  -H "X-API-Key: $SX_KEY"

POST/api/mail/verifyVerify Emails

Needs a key with scope write or higher and the verify feature.

JSON body

Name	Type	Default	Notes
emails	array of string	-	up to 25 are checked right away; more run as a job
search_id	integer	-	verify the emails found by this search (background job)
force	boolean	false
limit	integer	5000

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/mail/verify" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":[],"search_id":123,"force":false}'

Account and usage

Credits, plan, workspace usage and members (read) Feature name for key settings: account.

GET/api/statsStats

Needs a key with scope read or higher and the account feature.

bash

curl "https://YOUR-SCRAPEX-HOST/api/stats" \
  -H "X-API-Key: $SX_KEY"

GET/api/workspace/auditWorkspace Audit

Needs a key with scope read or higher and the account feature.

bash

curl "https://YOUR-SCRAPEX-HOST/api/workspace/audit" \
  -H "X-API-Key: $SX_KEY"

GET/api/workspace/usageUsage

Needs a key with scope read or higher and the account feature.

Query and path parameters

Name	Type	Default	Notes
days	integer	30

bash

curl "https://YOUR-SCRAPEX-HOST/api/workspace/usage" \
  -H "X-API-Key: $SX_KEY"

Team management

Invite and remove people (admin keys only) Feature name for key settings: team.

POST/api/workspace/invitesInvite

Needs a key with scope admin or higher and the team feature.

JSON body

Name	Type	Default	Notes
email*	string	-
role	string	"member"	admin \| member \| developer \| viewer

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/workspace/invites" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"name@example.com"}'

DELETE/api/workspace/invites/{iid}Cancel Invite

Needs a key with scope admin or higher and the team feature.

Query and path parameters

Name	Type	Default	Notes
iid*	integer	-

bash

curl -X DELETE "https://YOUR-SCRAPEX-HOST/api/workspace/invites/123" \
  -H "X-API-Key: $SX_KEY"

GET/api/workspace/membersMembers

Needs a key with scope read or higher and the team feature.

bash

curl "https://YOUR-SCRAPEX-HOST/api/workspace/members" \
  -H "X-API-Key: $SX_KEY"

DELETE/api/workspace/members/{uid}Remove Member

Needs a key with scope admin or higher and the team feature.

Query and path parameters

Name	Type	Default	Notes
uid*	integer	-

bash

curl -X DELETE "https://YOUR-SCRAPEX-HOST/api/workspace/members/123" \
  -H "X-API-Key: $SX_KEY"

PATCH/api/workspace/members/{uid}Set Role

Needs a key with scope admin or higher and the team feature.

Query and path parameters

Name	Type	Default	Notes
uid*	integer	-

JSON body

Name	Type	Default	Notes
role*	string	-

bash

curl -X PATCH "https://YOUR-SCRAPEX-HOST/api/workspace/members/123" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role":""}'

POST/api/workspacesNew Workspace

Agencies: one client workspace per client (shares the agency's plan + credits pool is NOT automatic - each client workspace starts on Free; the super admin can move it to a plan).

Needs a key with scope admin or higher and the team feature.

JSON body

Name	Type	Default	Notes
name*	string	-

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/workspaces" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My offer"}'

Manage API keys

Create and revoke keys (admin keys only) Feature name for key settings: keys.

GET/api/dev/featuresKey Features Catalog

Needs a key with scope read or higher and the keys feature.

bash

curl "https://YOUR-SCRAPEX-HOST/api/dev/features" \
  -H "X-API-Key: $SX_KEY"

GET/api/dev/keysList Keys

Needs a key with scope read or higher and the keys feature.

bash

curl "https://YOUR-SCRAPEX-HOST/api/dev/keys" \
  -H "X-API-Key: $SX_KEY"

POST/api/dev/keysCreate Key

Needs a key with scope admin or higher and the keys feature.

JSON body

Name	Type	Default	Notes
name	string	"My key"
scope	string	"write"	read (GET only) \| write (run searches, export) \| admin (+ team)
features	array of string	-	parts of the API this key may use; omit for all. See GET /api/dev/features
expires_in_days	integer	-	the key stops working after this many days; omit for never
credit_limit	integer	-	most credits this key may spend in total; omit for no cap

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/dev/keys" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My offer","scope":"write","features":[]}'

DELETE/api/dev/keys/{kid}Revoke Key

Needs a key with scope admin or higher and the keys feature.

Query and path parameters

Name	Type	Default	Notes
kid*	integer	-

bash

curl -X DELETE "https://YOUR-SCRAPEX-HOST/api/dev/keys/123" \
  -H "X-API-Key: $SX_KEY"

PATCH/api/dev/keys/{kid}Edit Key

Change a key's name, allowed features, expiry or credit cap. The secret and scope never change (make a new key for that).

Needs a key with scope admin or higher and the keys feature.

Query and path parameters

Name	Type	Default	Notes
kid*	integer	-

JSON body

Name	Type	Default
name	string	-
features	array of string	-
all_features	boolean	false
expires_in_days	integer	-
no_expiry	boolean	false
credit_limit	integer	-
no_credit_limit	boolean	false

bash

curl -X PATCH "https://YOUR-SCRAPEX-HOST/api/dev/keys/123" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My offer","features":[],"all_features":false}'

GET/api/dev/usageDev Usage

Everything the developer portal shows: plan, credits, rate limit, and per-key stats.

Needs a key with scope read or higher and the keys feature.

bash

curl "https://YOUR-SCRAPEX-HOST/api/dev/usage" \
  -H "X-API-Key: $SX_KEY"

GET/api/dev/webhooksList Webhooks

Needs a key with scope read or higher and the keys feature.

bash

curl "https://YOUR-SCRAPEX-HOST/api/dev/webhooks" \
  -H "X-API-Key: $SX_KEY"

POST/api/dev/webhooksAdd Webhook

Needs a key with scope admin or higher and the keys feature.

JSON body

Name	Type	Default	Notes
url*	string	-	a public https:// address that accepts POST
events	array of string	["search.completed","search.failed"]	which events to send

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/dev/webhooks" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

DELETE/api/dev/webhooks/{wid}Delete Webhook

Needs a key with scope admin or higher and the keys feature.

Query and path parameters

Name	Type	Default	Notes
wid*	integer	-

bash

curl -X DELETE "https://YOUR-SCRAPEX-HOST/api/dev/webhooks/123" \
  -H "X-API-Key: $SX_KEY"

PATCH/api/dev/webhooks/{wid}Edit Webhook

Needs a key with scope admin or higher and the keys feature.

Query and path parameters

Name	Type	Default	Notes
wid*	integer	-

JSON body

Name	Type	Default	Notes
active	boolean	-
events	array of string	-

bash

curl -X PATCH "https://YOUR-SCRAPEX-HOST/api/dev/webhooks/123" \
  -H "X-API-Key: $SX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active":true,"events":[]}'

POST/api/dev/webhooks/{wid}/testTest Webhook

Send one webhook.test call now and report what your server answered.

Needs a key with scope admin or higher and the keys feature.

Query and path parameters

Name	Type	Default	Notes
wid*	integer	-

bash

curl -X POST "https://YOUR-SCRAPEX-HOST/api/dev/webhooks/123/test" \
  -H "X-API-Key: $SX_KEY"

Basics

Open to every valid key.

GET/api/configConfig

Needs a key with scope read or higher.

bash

curl "https://YOUR-SCRAPEX-HOST/api/config" \
  -H "X-API-Key: $SX_KEY"

GET/api/meMe

Needs a key with scope read or higher.

bash

curl "https://YOUR-SCRAPEX-HOST/api/me" \
  -H "X-API-Key: $SX_KEY"

GET/api/plansPlans

Public: plans, prices and what each includes (landing page + billing screen).

Needs a key with scope read or higher.

bash

curl "https://YOUR-SCRAPEX-HOST/api/plans" \
  -H "X-API-Key: $SX_KEY"