Skip to main content

Documentation Index

Fetch the complete documentation index at: https://brezelscraper.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Start with the API-first workflow. It is easier to test and easier to debug. Add webhooks later if you want BrezelScraper to notify n8n when jobs finish.

​
Before you start

Make sure you have:
  • A BrezelScraper account with credits
  • An API key from Dashboard > Integrations
  • An n8n workflow you can edit and activate

​
Workflow overview

Trigger --> HTTP Request (create job) --> Wait --> HTTP Request (poll status)
                                                        |
                                          +---------+---+----------+
                                          |         |              |
                                      completed   running       failed
                                          |       / pending    / cancelled
                                          v      v              v
                                  HTTP Request  loop back     stop or
                                  (get results) to Wait       handle error

​
Step 1: create an API key

In BrezelScraper, open Dashboard > Integrations and create a new API key. Copy the full bscraper_... token and store it somewhere safe. You will only see it once.

​
Step 2: create a job with an HTTP Request node

Add an HTTP Request node with these settings:
  • Method: POST
  • URL: https://api.brezelscraper.com/api/v1/jobs
  • Authentication: generic header auth, or add the header manually
  • Header option 1: Authorization: Bearer bscraper_your_key_here
  • Header option 2: X-API-Key: bscraper_your_key_here
  • Body content type: JSON
Example request body: 
{
  "name": "Berlin cafes",
  "keywords": ["cafes in berlin"],
  "lang": "en",
  "depth": 5,
  "max_results": 100,
  "reviews_max": 0,
  "images_max": 0,
  "max_time": 1800
}
FieldTypeNotes
namestringA label for this job (required)
keywordsstring[]1 to 5 search terms (required)
langstringTwo-letter language code (required)
depthintScroll depth, 1—20 (default 5)
max_resultsintCap on results, 1—500
reviews_maxintReviews per place, 0—500
images_maxintTotal images across all places, 0—40000
max_timeintTimeout in seconds, up to 3600 (default 1800)
A successful 201 Created response returns the new job ID: 
{
  "id": "d8d8a24e-cef2-4b02-8396-abc290b6f299"
}

​
Step 3: keep the job ID in your workflow

Store the id from the response in a field such as jobId so later nodes can reference it easily.

​
Step 4: wait before polling

Add a Wait node after job creation so your workflow does not hit the API in a tight loop. 30 to 60 seconds is a good starting interval for most jobs. After the wait, call: 
GET https://api.brezelscraper.com/api/v1/jobs/{{ $json.jobId }}
The response looks like this: 
{
  "id": "d8d8a24e-cef2-4b02-8396-abc290b6f299",
  "name": "Berlin cafes",
  "status": "running",
  "data": { ... },
  "result_count": 0,
  "created_at": "2026-04-10T12:00:00Z"
}
Check the status field and branch accordingly:
  • pending, running, or aborting: wait again, then poll again
  • completed: continue to results
  • failed or cancelled: stop the workflow or route to your error handling path
You can also check result_count before fetching results. If it is 0, there is nothing to download.

​
Step 5: fetch results

Once the status is completed, fetch structured results: 
GET https://api.brezelscraper.com/api/v1/jobs/{{ $json.jobId }}/results
Use this when you want JSON data inside n8n. If you want the CSV file instead: 
GET https://api.brezelscraper.com/api/v1/jobs/{{ $json.jobId }}/download

​
Cancelling a job

To stop a running job from n8n (for example on a timeout), send: 
POST https://api.brezelscraper.com/api/v1/jobs/{{ $json.jobId }}/cancel
The job status will move to aborting and then to cancelled.

​
Optional: trigger n8n from BrezelScraper webhooks

Instead of polling, you can have BrezelScraper notify n8n when a job finishes.

​
Set up the webhook

  1. In n8n, add a Webhook node and copy its Production URL
  2. In BrezelScraper, open Dashboard > Integrations
  3. Create a webhook and paste the n8n production URL
  4. Copy the signing secret and store it securely (you will only see it once)
BrezelScraper sends a POST request to your webhook URL when a job reaches a terminal state.

​
Webhook payload

{
  "event_type": "job.completed",
  "job_id": "d8d8a24e-cef2-4b02-8396-abc290b6f299",
  "job_name": "Berlin cafes",
  "status": "completed",
  "result_count": 87,
  "created_at": "2026-04-10T12:00:00Z",
  "ended_at": "2026-04-10T12:05:30Z"
}
Possible event_type values: job.completed, job.failed, job.cancelled. The payload contains metadata only. Fetch results through the API after receiving the webhook.

​
Verify the signature

Each delivery includes an X-Webhook-Signature header with an HMAC-SHA256 signature of the request body. In your n8n Code node: 
const crypto = require('crypto');
const sigHeader = $input.first().headers['x-webhook-signature'];
const parts = Object.fromEntries(sigHeader.split(',').map(p => p.split('=')));
const timestamp = parts.t;
const signature = parts.sha256;

const expected = crypto
  .createHmac('sha256', 'your_signing_secret')
  .update(timestamp + '.' + $input.first().body)
  .digest('hex');
const valid = crypto.timingSafeEqual(
  Buffer.from(signature),
  Buffer.from(expected)
);

​
Delivery and retries

BrezelScraper retries failed deliveries up to 5 times with exponential backoff. Each delivery has a unique X-Webhook-ID header you can use for deduplication. The timestamp in the signature header is cryptographically signed, so reject deliveries where t is more than 5 minutes old.

​
Error handling

The API returns standard HTTP status codes. Handle these in your n8n workflow with an IF node or error branch:
CodeMeaningWhat to do
201Job createdContinue
200Request succeeded (poll, results, download)Continue
402Insufficient creditsStop and alert the user
404Job not found or not owned by youCheck the job ID
422Invalid request bodyCheck field values and types
429Rate limit hitWait and retry after the number of seconds in the Retry-After header
Polling too fast is the most common cause of 429 errors. Space your Wait nodes at least 10 seconds apart.

​
Good production habits

  • Add an Idempotency-Key header on POST /api/v1/jobs if your workflow may retry on failure
  • Handle failed and cancelled jobs explicitly instead of looping forever
  • Keep the job ID in one field throughout the workflow so every node can reference it

​
Official n8n docs