Get Batch Results

GET https://api.wickson.ai/v1/batches/{batch_id}/results

Description

Retrieves the detailed processing results for a batch operation. This endpoint provides comprehensive information about batch processing outcomes, including success rates, file information, and references to created media items. Unlike the batch status endpoint which focuses on progress tracking, this endpoint focuses on the final results and created assets.

Path Parameters

• batch_id: Required. String. Unique batch identifier.

Query Parameters

• page: Optional. Integer. Page number for pagination. Default: 1.
• page_size: Optional. Integer. Number of items per page. Default: 100.

Example Request

curl -H "X-Api-Key: YOUR_API_KEY" "https://api.wickson.ai/v1/batches/batch-abc123/results?page=1&page_size=50"

Python Example

import requests

# Configuration
api_key = "YOUR_API_KEY"
batch_id = "batch-abc123"

# Get batch results
response = requests.get(
    f"https://api.wickson.ai/v1/batches/{batch_id}/results",
    headers={"X-Api-Key": api_key},
    params={
        "page": 1,
        "page_size": 50
    }
)

# Process the response
if response.status_code == 200:
    data = response.json()

    # Access batch summary information
    summary = data["data"]["batch_summary"]
    print(f"Batch: {summary['batch_name']}")
    print(f"Status: {summary['status']}")
    print(f"Collection: {summary['collection']}")

    # Check completion statistics
    completion = summary["completion"]
    print(f"Completion: {completion['successful']}/{completion['total_items']} items ({completion['completion_rate']}%)")

    # Display processed items
    print("\nProcessed items:")
    for item in data["data"]["job_results"]:
        status = "OK" if item["status"] == "succeeded" else "X" if item["status"] == "failed" else "!"
        print(f"{status} {item.get('filename', 'Unknown')} - {item.get('media_id', 'No media ID')}")

    # Display statistics
    if "statistics" in data["data"]:
        stats = data["data"]["statistics"]
        print("\nMedia Distribution:")
        if "media_distribution" in stats:
            media_dist = stats["media_distribution"]
            print(f"Total created media items: {media_dist.get('total_created_media_items', 0)}")

            # Print media IDs by type
            if "media_ids_by_type" in media_dist:
                print("\nMedia IDs by type:")
                for media_type, ids in media_dist["media_ids_by_type"].items():
                    print(f"  {media_type}: {len(ids)} items")
else:
    print(f"Error {response.status_code}: {response.text}")

Response

Success Response (200 OK)

{
  "success": true,
  "message": "Batch results retrieved successfully",
  "data": {
    "batch_summary": {
      "batch_id": "batch-abc123",
      "batch_name": "Monthly Reports Processing",
      "collection": "reports-collection",
      "status": "completed",
      "timeline": {
        "created_at": "2024-12-18T10:00:00Z",
        "started_at": "2024-12-18T10:01:15Z",
        "completed_at": "2024-12-18T13:45:30Z",
        "total_duration_seconds": 13455.25
      },
      "completion": {
        "successful": 180,
        "failed": 20,
        "total_items": 200,
        "completion_rate": 90.0
      }
    },
    "job_results": [
      {
        "job_id": "job-123abc",
        "media_id": "vec-abc123",
        "filename": "q4_summary.pdf",
        "media_type": "document",
        "status": "succeeded",
        "file_info": {
          "size_bytes": 256789,
          "size_mb": 0.24
        },
        "processing_info": {
          "created_at": "2024-12-18T10:01:30Z",
          "completed_at": "2024-12-18T10:03:12Z"
        }
      },
      {
        "job_id": "job-abc456",
        "media_id": null,
        "filename": "financial_data.xlsx",
        "media_type": "document",
        "status": "failed",
        "file_info": {
          "size_bytes": 175420,
          "size_mb": 0.17
        },
        "processing_info": {
          "created_at": "2024-12-18T10:05:00Z",
          "completed_at": "2024-12-18T10:05:45Z"
        },
        "error": {
          "message": "Unsupported file format",
          "code": "format_error",
          "details": {
            "format": ".xlsx",
            "supported_formats": [".pdf", ".txt", ".docx"]
          }
        }
      }
    ],
    "statistics": {
      "media_distribution": {
        "by_type": {
          "document": 150,
          "image": 30,
          "video": 20
        },
        "total_created_media_items": 180,
        "media_ids_by_type": {
          "document": ["vec-abc123", "vec-def456"],
          "image": ["vec-ghi789", "vec-jkl012"]
        }
      },
      "completion": {
        "successful": 180,
        "failed": 20,
        "total": 200,
        "success_rate": 90.0
      },
      "resources": {
        "total_files_size_bytes": 256789000,
        "total_files_size_mb": 245.12
      },
      "error_summary": [
        {
          "error_type": "format_error",
          "count": 12,
          "affected_files": ["financial_data.xlsx", "budget.numbers"],
          "resolution": "Convert files to a supported format (.pdf, .txt, .docx)"
        },
        {
          "error_type": "corrupted_file",
          "count": 8,
          "affected_files": ["corrupted_report.pdf", "damaged_image.jpg"],
          "resolution": "Check file integrity and re-upload"
        }
      ]
    },
    "pagination": {
      "page": 1,
      "page_size": 50,
      "total_items": 200,
      "total_pages": 4
    }
  },
  "metadata": {
    "request_id": "req_batch_results_abc123",
    "related_endpoints": {
      "media_details": "/v1/media/{media_id}",
      "list_media": "/v1/media?collection=reports-collection"
    }
  }
}

Error Responses

Batch Not Found (404 Not Found)

{
  "success": false,
  "message": "Batch batch-xyz789 not found",
  "code": "not_found",
  "status_code": 404
}

Processing Error (500 Internal Server Error)

{
  "success": false,
  "message": "Failed to retrieve batch results: Database error",
  "code": "processing_error",
  "status_code": 500,
  "details": {
    "operation": "get_batch_results",
    "batch_id": "batch-abc123"
  }
}

Response Details

Batch Summary

The batch_summary object provides an overview of the entire batch, including:

• batch_id: Unique identifier for the batch
• batch_name: Name of the batch job (if provided during creation)
• collection: The collection the batch items were added to
• status: Current batch status (completed, failed, etc.)
• timeline: Timestamps for batch creation, start, and completion with total duration in seconds
• completion: Statistics on successful and failed items

Job Results

The job_results array contains detailed information about each processed item:

• job_id: Unique identifier for the specific job within the batch
• media_id: Identifier for the processed media item (null for failed items) - uses vec- format IDs
• filename: Original filename of the processed item
• media_type: Type of media (document, image, video, audio, model)
• status: Processing status (succeeded, failed, processed)
• file_info: File details including size in bytes and megabytes
• processing_info: Job creation and completion timestamps
• error: For failed items, detailed error information

Statistics

The statistics object provides aggregate metrics about the batch processing:

• media_distribution: Breakdown of processed items by media type with media IDs
• completion: Overall completion statistics
• resources: Resource usage information including total file size
• error_summary: Overview of errors encountered during processing (only present if there were errors)

Pagination

For batches with many items, results are paginated. The pagination object provides details about the current page and total pages.

Important Notes

• This endpoint focuses on batch results and created assets, not real-time progress tracking
• The endpoint returns media IDs in the vec-xxx format that can be used with other API endpoints
• Use the /v1/media/{media_id} endpoint to get full metadata for a specific item
• For large batches, use pagination parameters to retrieve results in manageable chunks

---

Related Endpoints

• Create Batch - Create and initiate a batch job
• Get Batch Status - Check status of a batch job in real-time
• Control Batch State - Cancel/pause/resume a batch job
• Get Media Item - Get complete details for a processed media item

Batch Processing Workflow

1. Create a batch: Submit a batch of files for processing.
2. Monitor progress: Check the batch's processing status using the batch status endpoint.
3. Control if needed: Cancel the batch if required.
4. Retrieve results: Once processing is complete, retrieve the batch processing results.

Error Handling

Common error types include:

• validation_error: Invalid input parameters
• format_error: Unsupported file format
• corrupted_file: File is damaged or unreadable
• processing_error: Error during processing
• storage_error: Error storing results
• timeout_error: Processing exceeded the allotted time
• resource_error: Insufficient system resources
• quota_exceeded: Account limits exceeded

Rate Limiting

Batch operation endpoints are subject to rate limiting to ensure fair usage. If you exceed the rate limit, you'll receive a 429 Too Many Requests response with a Retry-After header indicating when you can retry.