Get Batch Status¶
Description¶
Retrieves the current status and detailed information about a specific batch processing job. This endpoint provides comprehensive insights into the batch's progress, estimated completion time, and error statistics.
Path Parameters¶
batch_id: Required. The unique identifier for the batch you want to check.
Query Parameters¶
include_job_details: Optional. Boolean. Include detailed information about individual jobs within the batch. Default:false.metrics_only: Optional. Boolean. Return only the batch's metrics and statistics without other details. Default:false.include_errors: Optional. Boolean. Include detailed error information for failed items. Default:true.fields: Optional. List of specific fields to include in the response (comma-separated). Use this to receive only the information you need.
Example Request¶
curl -H "X-Api-Key: YOUR_API_KEY" "https://api.wickson.ai/v1/batches/batch-abc123?include_job_details=true"
Python Example¶
import requests
import datetime
# Configuration
api_key = "YOUR_API_KEY"
batch_id = "batch-abc123"
# Get batch status with job details
response = requests.get(
f"https://api.wickson.ai/v1/batches/{batch_id}",
headers={"X-Api-Key": api_key},
params={"include_job_details": True}
)
# Process the response
if response.status_code == 200:
data = response.json()["data"]
# Display batch overview
print(f"Batch: {data['batch_name']} ({data['batch_id']})")
print(f"Status: {data['status'].upper()}")
# Display progress information
progress = data["progress"]
print(f"Progress: {progress['percentage']:.1f}% ({progress['completed']} of {progress['total']} complete)")
# Show timing information
if data["status"] != "completed" and "estimated_completion" in data["timing"]:
est_time = datetime.datetime.fromisoformat(data["timing"]["estimated_completion"].replace("Z", "+00:00"))
now = datetime.datetime.now(datetime.timezone.utc)
minutes_remaining = round((est_time - now).total_seconds() / 60)
print(f"Estimated completion: {minutes_remaining} minutes remaining")
# Show error count if any
if progress["failed"] > 0 and "error_summary" in data:
print(f"\nErrors: {progress['failed']} files failed")
for error in data["error_summary"]:
print(f" - {error['error_type']} ({error['count']} files): {error['resolution']}")
else:
print(f"Error {response.status_code}: {response.text}")
Response¶
Success Response (200 OK)¶
{
"success": true,
"message": "Batch status retrieved successfully",
"data": {
"batch_id": "batch-abc123",
"batch_name": "Monthly Reports Processing",
"status": "running",
"progress": {
"percentage": 42.5,
"completed": 85,
"failed": 3,
"pending": 112,
"processing": 5,
"total": 200
},
"timing": {
"created_at": "2024-12-18T10:00:00Z",
"started_at": "2024-12-18T10:01:15Z",
"updated_at": "2024-12-18T11:30:00Z",
"completed_at": null,
"estimated_completion": "2024-12-18T13:45:00Z",
"elapsed_time": 5345.5,
"average_item_time": 62.8
},
"job_details": [
{
"job_id": "job-xyz789",
"file_path": "reports/q4_summary.pdf",
"media_type": "document",
"status": "completed",
"progress": 100.0,
"started_at": "2024-12-18T10:02:00Z",
"completed_at": "2024-12-18T10:03:12Z"
},
{
"job_id": "job-abc456",
"file_path": "reports/financial_data.xlsx",
"media_type": "document",
"status": "failed",
"progress": 23.5,
"started_at": "2024-12-18T10:05:30Z",
"completed_at": "2024-12-18T10:06:45Z",
"error": {
"message": "Unsupported file format",
"code": "format_error",
"details": {
"format": ".xlsx",
"supported_formats": [".pdf", ".txt", ".docx"]
}
}
}
],
"error_summary": [
{
"error_type": "format_error",
"count": 2,
"affected_files": ["reports/financial_data.xlsx", "reports/spreadsheet.xlsx"],
"resolution": "Ensure file is in a supported format"
},
{
"error_type": "corrupted_file",
"count": 1,
"affected_files": ["reports/damaged_report.pdf"],
"resolution": "Verify file integrity and try uploading again"
}
],
"batch_configuration": {
"max_concurrent": 5,
"priority": "normal",
"timeout": 3600,
"notification_enabled": false
}
},
"metadata": {
"request_id": "req_batch_status_abc123",
"api_version": "1.0.0",
"cache_ttl": 30,
"cache_remaining": 25
}
}
Error Responses¶
Invalid Batch ID (400 Bad Request)¶
{
"success": false,
"message": "Invalid batch ID: batch@123",
"code": "validation_error",
"status_code": 400,
"details": {
"error": "Batch ID must be alphanumeric with hyphens only"
}
}
Batch Not Found (404 Not Found)¶
{
"success": false,
"message": "Batch batch-xyz789 not found",
"code": "not_found",
"status_code": 404,
"details": {
"resource_type": "batch",
"resource_id": "batch-xyz789"
}
}
Processing Error (500 Internal Server Error)¶
{
"success": false,
"message": "Failed to retrieve batch status: Database connection error",
"code": "processing_error",
"status_code": 500,
"details": {
"operation": "get_batch_status",
"batch_id": "batch-abc123"
}
}
Response Details¶
Status Values¶
created: Batch has been created but processing hasn't startedrunning: Batch is currently being processedpaused: Batch processing has been pausedcompleted: All items in the batch have been processedfailed: Batch processing has failedcancelled: Batch processing was cancelled by the user
Progress Information¶
The progress object provides a snapshot of how many items are in each processing state and the overall completion percentage.
Timing Information¶
The timing object includes timestamps for key events and calculated durations. The estimated_completion is calculated based on the average processing time of completed items.
Error Summary¶
When errors occur during batch processing, the error_summary provides a concise overview of the error types, affected files, and suggested resolutions.
Caching¶
Status responses are cached briefly to improve performance. The cache_remaining field in the metadata indicates how many seconds until the cache expires.