Monitoring Batch Jobs

Batch jobs are processed asynchronously.

After creating a batch job, use the returned job_id to monitor its progress and retrieve the extraction results.

Retrieve a Batch Job

Use the following endpoint to retrieve the latest status and results for a batch job.

GET /v1/batch/{job_id}

Request

request.sh

curl -X GET "https://scraper.geonode.io/v1/batch/YOUR_JOB_ID" \
  -H "X-Api-Key: YOUR_API_KEY"

Replace YOUR_JOB_ID with the job ID returned when the batch was created.

Example Response

response.json

{
  "job_id": "d54da3de-7afc-4127-a5ee-5f7e0378a3e6",
  "status": "completed",
  "created_at": "2026-07-05T16:14:22.721Z",
  "completed_at": "2026-07-05T16:14:25.318Z",
  "total_urls": 3,
  "completed_urls": 2,
  "failed_urls": 1,
  "pending_urls": 0,
  "cancelled_urls": 0,
  "token_summary": {
    "tokens_charged_total": 2,
    "tokens_reserved": 0
  },
  "results": [
    {
      "input_index": 0,
      "url": "https://geonode.com",
      "status": "completed"
    },
    {
      "input_index": 1,
      "url": "https://docs.geonode.com",
      "status": "completed"
    },
    {
      "input_index": 2,
      "url": "https://this-domain-does-not-exist-123456789.com",
      "status": "failed"
    }
  ]
}

Job Information

The top-level response describes the overall batch job.

Field	Description
`job_id`	Unique identifier for the batch job.
`status`	Current status of the batch job.
`created_at`	Time the batch job was created.
`completed_at`	Time processing finished.

Processing Statistics

These fields summarize the progress of the batch.

Field	Description
`total_urls`	Total number of submitted URLs.
`completed_urls`	URLs processed successfully.
`failed_urls`	URLs that failed during processing.
`pending_urls`	URLs that are still waiting to be processed.
`cancelled_urls`	URLs cancelled before processing completed.

Token Usage

The response also includes a summary of token usage.

Field	Description
`tokens_charged_total`	Total tokens consumed by the batch.
`tokens_reserved`	Tokens reserved for processing.

Individual Results

Each submitted URL appears in the results array.

Each result contains information about a single URL.

Field	Description
`input_index`	Position of the URL in the original request.
`url`	The processed URL.
`status`	Processing status for that URL.
`error_code`	Error code when processing fails.
`error_message`	Human-readable error description.
`data`	Extracted content for successful requests.
`metadata`	Processing metadata for the request.

Job Status

Each URL has its own processing status.

Status	Description
`queued`	Waiting to be processed.
`processing`	Currently being processed.
`completed`	Successfully extracted.
`failed`	Processing failed.
`cancelled`	Processing was cancelled.

Partial Failures

A batch job can complete successfully even if some URLs fail.

For example, a batch containing three URLs may produce:

2 completed URLs
1 failed URL
Overall batch status: completed

Failed URLs include additional error information.

{
  "url": "https://this-domain-does-not-exist-123456789.com",
  "status": "failed",
  "error_code": "INTERNAL_ERROR",
  "error_message": "An unexpected error occurred on the server"
}

This allows you to retry only the failed URLs instead of rerunning the entire batch.

Good to know

Failed URLs do not prevent other URLs in the same batch from completing successfully.

Metadata

Each completed result includes processing metadata.

Field	Description
`http_status`	HTTP status code returned by the target website.
`duration_ms`	Time taken to process the URL.
`tokens_charged`	Tokens consumed for that extraction.

This information can help monitor performance and troubleshoot extraction issues.

Best Practices

When working with batch jobs:

Save the returned job_id so you can retrieve the results later.
Wait until the job status is completed before using the extracted data.
Review the processing statistics to quickly identify failed URLs.
Retry only failed URLs instead of rerunning the entire batch.
Monitor token usage when processing large batches.

Next Steps

Now that you know how to monitor batch jobs and retrieve their results, continue to Batch Workflows to learn common patterns for processing large collections of URLs.

Monitoring Batch Jobs

On this page