Skip to main content
GET
/
classify
/
{job_id}
curl -X GET "https://prod.visionapi.unsiloed.ai/classify/47c536aa-9fab-48ca-b27c-2fd74d30490a" \
  -H "api-key: your-api-key" \
  -H "Content-Type: application/json"

{
  "job_id": "47c536aa-9fab-48ca-b27c-2fd74d30490a",
  "status": "processing",
  "progress": "Starting classification...",
  "error": null,
  "result": null
}

​
Overview

The Get Classification Job Status endpoint allows you to check the current status of classification jobs and retrieve the final results once processing is complete. Classification jobs process documents asynchronously, uploading files to cloud storage and analyzing them in the background.
Status checks are lightweight and can be polled frequently to monitor progress.

​
Path Parameters

​
job_id
string
required
The unique identifier of the classification job

​
Response

​
job_id
string
Unique identifier for the classification job
​
status
string
Current job status: “queued” while the job waits to be picked up, “processing” while it runs, then “completed” or “failed”
​
progress
string
Human-readable progress message describing current processing stage
​
error
string
Error message (if job failed, otherwise null)
​
result
object
Classification results (only present when status is “completed”)
For image inputs the result has no page_results array; it carries classification, confidence, and raw_result at the top level with total_pages: 1. When an individual PDF page fails, its page_results entry has success: false, an error message, no raw_result, and the classification defaults to the first category.

​
Request Examples

curl -X GET "https://prod.visionapi.unsiloed.ai/classify/47c536aa-9fab-48ca-b27c-2fd74d30490a" \
  -H "api-key: your-api-key" \
  -H "Content-Type: application/json"

​
Response Examples

{
  "job_id": "47c536aa-9fab-48ca-b27c-2fd74d30490a",
  "status": "processing",
  "progress": "Starting classification...",
  "error": null,
  "result": null
}

​
Job Status Values

Job has been created and is waiting to be picked up for processing. Jobs move to processing as soon as a worker is available.
Job is currently being processed. This includes file upload to storage, document analysis, and classification processing. Progress messages will indicate the current stage.
Job has completed successfully. The result field contains the classification results with confidence scores and page-by-page details.
Job failed during processing. The error field contains details about what went wrong. Common causes include file corruption, invalid conditions, or processing errors.

​
Polling Strategy

For long-running classification jobs, implement polling with exponential backoff: 
import time
import asyncio

async def poll_classification_status(job_id, max_wait_time=300):
    """Poll classification job status with exponential backoff"""
    
    base_delay = 1  # Start with 1 second
    max_delay = 30  # Maximum delay between polls
    current_delay = base_delay
    total_wait_time = 0
    
    while total_wait_time < max_wait_time:
        try:
            response = requests.get(
                f"https://prod.visionapi.unsiloed.ai/classify/{job_id}",
                headers={"api-key": "your-api-key", "Content-Type": "application/json"}
            )
            
            if response.status_code == 200:
                result = response.json()
                
                if result['status'] == 'completed':
                    return result['result']
                elif result['status'] == 'failed':
                    raise Exception(f"Classification failed: {result.get('error', 'Unknown error')}")
                else:
                    print(f"Status: {result['status']}, Progress: {result.get('progress', 'N/A')}")
            
            # Wait before next poll
            await asyncio.sleep(current_delay)
            total_wait_time += current_delay
            
            # Exponential backoff
            current_delay = min(current_delay * 2, max_delay)
            
        except Exception as e:
            print(f"Error polling status: {e}")
            await asyncio.sleep(current_delay)
            total_wait_time += current_delay
    
    raise Exception("Classification job timed out")

​
Progress Messages

The progress field carries one of three messages:
  • “Starting classification…” - Job has been picked up and is being processed
  • “Classification completed” - Job finished successfully
  • “Classification failed” - Job encountered an error (jobs that fail before classification starts may retain “Starting classification…”)

​
Error Handling

​
Common Error Scenarios

  1. File Processing Errors: PDF corruption, password protection, or unreadable content (job fails with the reason in error)
  2. Model Errors: Vision model failures or timeouts during page classification
  3. Job Not Found: Invalid job ID or job has been deleted (HTTP 404)
Input validation errors (missing file, malformed categories, oversize files) are rejected synchronously by POST /classify with a 400/413 response, so they never appear as failed jobs here.

​
Error Response Example

File Processing Error
{
  "job_id": "47c536aa-9fab-48ca-b27c-2fd74d30490a",
  "status": "failed",
  "progress": "Classification failed",
  "error": "This PDF could not be opened — the file may be corrupt or in an unsupported format.",
  "result": null
}

Authorizations

​
api-key
string
header
required

Path Parameters

​
job_id
string
required

The unique identifier of the classification job

Response

200 - application/json

Classification job status retrieved successfully

​
job_id
string

Unique identifier for the classification job

​
status
string

Current job status (queued, processing, completed, failed)

​
progress
string

Progress message

​
error
string

Error message if job failed

​
result
object

Classification results (only present when status is completed)