Your First Batch
Batch jobs allow you to submit multiple URLs in a single API request.
Instead of sending one extraction request per page, you create a single batch job. Geonode queues the job, processes each URL asynchronously, and lets you retrieve the results later.
In this guide, you'll:
- Create your first batch job
- Understand the response
- Learn how invalid URLs are handled
- Retrieve the batch status
Create Your First Batch
Send a POST request to the batch endpoint.
POST /v1/batchRequest
curl -X POST "https://scraper.geonode.io/v1/batch" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://geonode.com",
"https://docs.geonode.com",
"https://example.com"
]
}'Response
{
"job_id": "d16e56a0-dbe9-4586-a40d-028cf3c439a9",
"status": "queued",
"status_url": "/v1/batch/d16e56a0-dbe9-4586-a40d-028cf3c439a9",
"accepted_urls": 3,
"invalid_urls": []
}The request creates a new batch job immediately.
Geonode validates the request, queues the job, and returns a unique job ID that you can use to monitor progress.
Understanding the Response
The initial response confirms that the batch job has been accepted.
| Field | Description |
|---|---|
job_id | Unique identifier for the batch job. |
status | Current processing status. A new job starts as queued. |
status_url | Endpoint used to retrieve the latest status and results. |
accepted_urls | Number of valid URLs accepted for processing. |
invalid_urls | URLs that were rejected during validation. |
The actual extraction results are not returned immediately because batch jobs run asynchronously.
What Happens Next?
Once the request is accepted, Geonode processes each URL in the background.
You can use the returned job_id or status_url to check the progress of the job at any time.
Handling Invalid URLs
By default, every URL in the batch request must be valid.
If one or more URLs are invalid and ignore_invalid_urls is set to false, the entire request is rejected.
Request
{
"urls": [
"https://geonode.com",
"https://docs.geonode.com",
"not-a-valid-url"
],
"ignore_invalid_urls": false
}Response
{
"code": "VALIDATION_ERROR",
"message": "Batch contains invalid URLs and ignore_invalid_urls is false",
"correlation_id": "1fd0958b-6583-4c32-9e9b-5ad7960ac5ad",
"retryable": false
}No batch job is created until the request contains only valid URLs.
Skip Invalid URLs
If you want Geonode to continue processing valid URLs, enable ignore_invalid_urls.
Request
{
"urls": [
"https://geonode.com",
"https://docs.geonode.com",
"https://example.com",
"not-a-valid-url"
],
"ignore_invalid_urls": true
}Response
{
"job_id": "d16e56a0-dbe9-4586-a40d-028cf3c439a9",
"status": "queued",
"status_url": "/v1/batch/d16e56a0-dbe9-4586-a40d-028cf3c439a9",
"accepted_urls": 3,
"invalid_urls": [
"not-a-valid-url"
]
}Only the valid URLs are queued for processing. Invalid URLs are skipped and returned in the invalid_urls array.
Use ignore_invalid_urls when importing URLs from user input, CSV files, or external systems where a few invalid entries shouldn't stop the entire batch.
Check the Batch Status
Batch jobs are processed asynchronously.
After creating a job, use the returned job_id to check its status.
GET /v1/batch/{job_id}You'll learn how to monitor a running job and retrieve its results in the next guide.
Next Steps
Now that you've created your first batch job, continue to Working with Batch Inputs to learn how to customize batch requests with output formats, JavaScript rendering, proxies, custom headers, and other request options.