REST API for developers

In short

The REST API gives your own code what the dashboard shows about your crawls. It works on the sites in your My Sites list. Reading is free of credits. Starting a crawl spends credits, the way a crawl you start in the dashboard does.

Quickstart

You need a PerfBee account, a site in My Sites and a terminal. Each step is one call.

Step 1: Make a key

In the dashboard open Settings > API keys, choose Read and start crawls and copy the key. It is shown once. Keep it in an environment variable.

Terminal: the key and the address

export PERFBEE_API_KEY="pbk_..."
export PERFBEE_API="https://dashboard.perfbee.com/api/v1"

Step 2: Check the key

The answer names your workspace, your plan and the credits left.

Terminal: check the key

curl -sS -H "Authorization: Bearer $PERFBEE_API_KEY" "$PERFBEE_API/me"

Step 3: Find your site

Use the id of the site as SITE_ID.

Terminal: list your sites

curl -sS -H "Authorization: Bearer $PERFBEE_API_KEY" "$PERFBEE_API/sites"

Step 4: Start a crawl

The same Idempotency-Key returns the same crawl, so a retry never starts a second one. The call answers 202 at once with the crawl. Its id is CRAWL_ID.

Terminal: start a crawl

curl -sS -X POST "$PERFBEE_API/crawls" \
  -H "Authorization: Bearer $PERFBEE_API_KEY" \
  -H "Idempotency-Key: $(git rev-parse HEAD)" \
  -H "Content-Type: application/json" \
  -d "{\"site_id\": $SITE_ID, \"mode\": \"fast\", \"max_pages\": 100}"

Step 5: Wait for it

The call holds for up to 25 seconds and returns as soon as the crawl ends. Repeat it until status is one of completed, failed, cancelled or partial.

Terminal: wait for the crawl

curl -sS -H "Authorization: Bearer $PERFBEE_API_KEY" "$PERFBEE_API/crawls/$CRAWL_ID?wait=25"

Step 6: Read what it found

The issues, and what changed since the crawl before.

Terminal: issues and changes

curl -sS -H "Authorization: Bearer $PERFBEE_API_KEY" "$PERFBEE_API/crawls/$CRAWL_ID/issues"
curl -sS -H "Authorization: Bearer $PERFBEE_API_KEY" "$PERFBEE_API/crawls/$CRAWL_ID/diff"

A crawl is completed before its pages and fixes are processed. The crawl's processing member says when they are ready, and the scan_data_ready webhook says it too.

Plans and credits

The REST API, webhooks and the MCP server are on every plan. Crawls spend credits.

A crawl needs enough credits for the most it can cost before it starts: the pages it may check times the page rate. You are charged when it ends, for the pages it checked. If the credits do not cover it, the call answers insufficient_credits and says how many are needed and free. Reading data never costs credits. A key can also carry a daily cap on what its crawls may cost: see authentication.

What the API cannot do

PerfBee crawls from its own cloud. It cannot reach a private network, a VPN or a staging site that PerfBee has no access details for.
A crawl starts only on a site in My Sites. The API does not add or remove sites, change schedules or delete crawls.
A site that refuses the crawler is reported as not checked, and those pages are not charged. Crawls follow the rules on our crawler page: the same user agent, address and signature as every other PerfBee crawl.
There is no console on these pages. A key never belongs in a browser, and the API does not answer cross-origin requests from one.

Exports and live links

Exports through the API and live CSV links for Google Sheets need a plan with exports: Starter and up. A workspace on Free gets plan_required from those calls.

Where to go next

Authentication: Keys, scopes and the daily credit cap.
Pagination: Cursors, page sizes and counts.
Errors: The problem document and every error code.
Rate limits: Calls a minute, crawl caps and idempotency.
Webhooks: Events, deliveries and signature checks.
Recipes: Ready examples for CI, n8n, Zapier and Google Sheets.
API reference: Every endpoint, from the OpenAPI file.
Changelog: What changed, and how changes are made.

Questions about the API: support@perfbee.com. Quote the request_id of the answer.

PerfBee API