Overview

The batch status endpoint allows you to monitor the progress of batch conversion jobs, retrieve completed results, and check for any processing errors. This endpoint provides real-time status updates for all files in a batch.

📊 Real-time Progress

Get accurate progress percentages and completion estimates.

📄 Individual Results

Access results for completed files while others are still processing.

🔍 Detailed Errors

Get specific error messages and suggestions for failed files.

Parameter

Type

Required

Description

batch_id

string

Yes

The batch ID returned from the batch conversion request

Response Formats

In Progress Response

Batch Processing (200 OK)

{
 "batch_id": "batch_1234567890abcdef",
 "status": "in_progress",
 "total_files": 5,
 "completed_files": 3,
 "failed_files": 1,
 "processing_files": 1,
 "progress_percentage": 80,
 "results": [
 {
 "id": "file1",
 "job_id": "conv_1111111111111111",
 "status": "completed",
 "filename": "document1.pdf",
 "markdown_content": "# Document 1\n\nContent from the first PDF...",
 "metadata": {
 "file_size": 2048,
 "pages": 3,
 "processing_time_ms": 1850
 },
 "sas_url": "https://storage.azure.com/converted/conv_1111111111111111.md?sp=r&st=..."
 },
 {
 "id": "file2",
 "job_id": "conv_2222222222222222",
 "status": "completed", 
 "filename": "document2.docx",
 "markdown_content": "# Document 2\n\nContent from the Word document...",
 "metadata": {
 "file_size": 1536,
 "pages": 2,
 "processing_time_ms": 1200
 },
 "sas_url": "https://storage.azure.com/converted/conv_2222222222222222.md?sp=r&st=..."
 },
 {
 "id": "file3",
 "job_id": "conv_3333333333333333",
 "status": "processing",
 "filename": "presentation.pptx",
 "estimated_completion": "2024-01-01T12:00:15Z"
 },
 {
 "id": "file4",
 "status": "failed",
 "filename": "corrupted.pdf",
 "error": {
 "code": "CORRUPTED_FILE",
 "message": "The file appears to be corrupted and cannot be processed",
 "suggestion": "Please verify the file integrity and try again"
 }
 },
 {
 "id": "file5",
 "job_id": "conv_5555555555555555",
 "status": "completed",
 "filename": "spreadsheet.xlsx",
 "markdown_content": "# Spreadsheet Data\n\n| Column 1 | Column 2 |\n|----------|----------|\n| Value 1 | Value 2 |",
 "metadata": {
 "file_size": 1024,
 "pages": 1,
 "processing_time_ms": 900
 },
 "sas_url": "https://storage.azure.com/converted/conv_5555555555555555.md?sp=r&st=..."
 }
 ],
 "created_at": "2024-01-01T12:00:00Z",
 "started_at": "2024-01-01T12:00:01Z",
 "estimated_completion": "2024-01-01T12:00:15Z"
}

Completed Response

Batch Complete (200 OK)

{
 "batch_id": "batch_1234567890abcdef",
 "status": "completed",
 "total_files": 3,
 "completed_files": 3,
 "failed_files": 0,
 "processing_files": 0,
 "progress_percentage": 100,
 "results": [
 {
 "id": "file1",
 "job_id": "conv_1111111111111111",
 "status": "completed",
 "filename": "document1.pdf",
 "markdown_content": "# Document 1\n\nContent from the first PDF document...",
 "metadata": {
 "file_size": 2048,
 "pages": 3,
 "processing_time_ms": 1850
 },
 "sas_url": "https://storage.azure.com/converted/conv_1111111111111111.md?sp=r&st=..."
 },
 {
 "id": "file2",
 "job_id": "conv_2222222222222222",
 "status": "completed",
 "filename": "document2.docx", 
 "markdown_content": "# Document 2\n\nContent from the Word document...",
 "metadata": {
 "file_size": 1536,
 "pages": 2,
 "processing_time_ms": 1200
 },
 "sas_url": "https://storage.azure.com/converted/conv_2222222222222222.md?sp=r&st=..."
 },
 {
 "id": "file3",
 "job_id": "conv_3333333333333333",
 "status": "completed",
 "filename": "presentation.pptx",
 "markdown_content": "# Presentation Title\n\n## Slide 1\n\nContent from slide 1...",
 "metadata": {
 "file_size": 4096,
 "pages": 10,
 "processing_time_ms": 2400
 },
 "sas_url": "https://storage.azure.com/converted/conv_3333333333333333.md?sp=r&st=..."
 }
 ],
 "created_at": "2024-01-01T12:00:00Z",
 "started_at": "2024-01-01T12:00:01Z",
 "completed_at": "2024-01-01T12:00:05Z",
 "total_processing_time_ms": 5450
}

Error Response

Batch Not Found (404)

{
 "error": "Batch not found",
 "code": "BATCH_NOT_FOUND",
 "message": "No batch found with ID: batch_invalid123",
 "suggestion": "Please verify the batch_id and ensure it was created successfully"
}

Response Fields

Batch Level Fields

Field	Type	Description
batch_id	string	Unique identifier for the batch
status	string	Overall batch status (pending, in_progress, completed, partial_failure)
total_files	number	Total number of files in the batch
completed_files	number	Number of successfully processed files
failed_files	number	Number of files that failed processing
processing_files	number	Number of files currently being processed
progress_percentage	number	Completion percentage (0-100)

File Result Fields

Field	Type	Description
id	string	File identifier from the original batch request
job_id	string	Individual conversion job ID (only for successful/processing files)
status	string	File status (pending, processing, completed, failed)
filename	string	Original filename
markdown_content	string	Converted markdown content (only for completed files)
error	object	Error details (only for failed files)

Polling Guidelines

Recommended Intervals

• Small batches (1-5 files): Poll every 2-3 seconds
• Medium batches (6-20 files): Poll every 5-10 seconds
• Large batches (21+ files): Poll every 15-30 seconds
• Maximum polling duration: 30 minutes

Best Practices

• Use exponential backoff for failed requests
• Stop polling when status is "completed" or "partial_failure"
• Process completed files immediately as they become available
• Implement timeout handling for long-running batches

Batch Status

Overview

📊 Real-time Progress

📄 Individual Results

🔍 Detailed Errors

Batch Status States

Request Format

Path Parameters

cURL Example