> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unsiloed.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Classification Result

> Check the status and progress of classification jobs and retrieve results

## 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.

<Note>
  Status checks are lightweight and can be polled frequently to monitor progress.
</Note>

## Path Parameters

<ParamField path="job_id" type="string" required>
  The unique identifier of the classification job
</ParamField>

## Response

<ResponseField name="job_id" type="string">
  Unique identifier for the classification job
</ResponseField>

<ResponseField name="status" type="string">
  Current job status: "queued" while the job waits to be picked up, "processing" while it runs, then "completed" or "failed"
</ResponseField>

<ResponseField name="progress" type="string">
  Human-readable progress message describing current processing stage
</ResponseField>

<ResponseField name="error" type="string">
  Error message (if job failed, otherwise null)
</ResponseField>

<ResponseField name="result" type="object">
  Classification results (only present when status is "completed")

  <Expandable title="result_structure">
    <ResponseField name="success" type="boolean">
      Whether the classification operation succeeded
    </ResponseField>

    <ResponseField name="classification" type="string">
      Primary assigned category from the provided conditions list
    </ResponseField>

    <ResponseField name="confidence" type="number">
      Confidence score for primary classification (0.0-1.0)
    </ResponseField>

    <ResponseField name="total_pages" type="number">
      Number of pages classified. At most 4: documents longer than 4 pages are classified from their first 4 pages.
    </ResponseField>

    <ResponseField name="processed_pages" type="number">
      Number of pages attempted (equals total\_pages, at most 4); per-page success is reported in page\_results
    </ResponseField>

    <ResponseField name="page_results" type="array">
      Per-page classification details

      <Expandable title="page_result_structure">
        <ResponseField name="page" type="number">
          Page number (1-indexed)
        </ResponseField>

        <ResponseField name="classification" type="string">
          Classification result for this page
        </ResponseField>

        <ResponseField name="confidence" type="number">
          Confidence score for this page (0.0-1.0)
        </ResponseField>

        <ResponseField name="success" type="boolean">
          Whether this page was classified successfully
        </ResponseField>

        <ResponseField name="raw_result" type="string">
          The model's raw classification output for this page
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  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.
</Note>

## Request Examples

<RequestExample>
  ```bash cURL theme={null}
  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"
  ```

  ```python Python theme={null}
  import requests

  job_id = "47c536aa-9fab-48ca-b27c-2fd74d30490a"
  url = f"https://prod.visionapi.unsiloed.ai/classify/{job_id}"
  headers = {
      "api-key": "your-api-key",
      "Content-Type": "application/json"
  }

  response = requests.get(url, headers=headers)

  if response.status_code == 200:
      result = response.json()
      print(f"Job ID: {result['job_id']}")
      print(f"Status: {result['status']}")
      print(f"Progress: {result.get('progress', 'N/A')}")
      
      if result['status'] == 'completed':
          classification_result = result['result']
          print(f"Classification: {classification_result['classification']}")
          print(f"Confidence: {classification_result['confidence']:.2f}")
          print(f"Total pages: {classification_result['total_pages']}")
          
          # Page-by-page results
          for page_result in classification_result['page_results']:
              print(f"Page {page_result['page']}: {page_result['classification']} (confidence: {page_result['confidence']:.2f})")
      elif result['status'] == 'failed':
          print(f"Error: {result.get('error', 'Unknown error')}")
      else:
          print("Job is still processing...")
  else:
      print("Error:", response.status_code, response.text)
  ```

  ```javascript JavaScript theme={null}
  const jobId = '47c536aa-9fab-48ca-b27c-2fd74d30490a';

  const response = await fetch(`https://prod.visionapi.unsiloed.ai/classify/${jobId}`, {
    method: 'GET',
    headers: {
      'api-key': 'your-api-key',
      'Content-Type': 'application/json'
    }
  });

  if (response.ok) {
    const result = await response.json();
    console.log('Job ID:', result.job_id);
    console.log('Status:', result.status);
    console.log('Progress:', result.progress || 'N/A');
    
    if (result.status === 'completed') {
      const classificationResult = result.result;
      console.log('Classification:', classificationResult.classification);
      console.log('Confidence:', classificationResult.confidence);
      console.log('Total pages:', classificationResult.total_pages);
      
      // Display page-by-page results
      classificationResult.page_results.forEach(pageResult => {
        console.log(`Page ${pageResult.page}: ${pageResult.classification} (${pageResult.confidence.toFixed(2)})`);
      });
    } else if (result.status === 'failed') {
      console.error('Error:', result.error || 'Unknown error');
    } else {
      console.log('Job is still processing...');
    }
  } else {
    console.error('Request failed:', response.status, await response.text());
  }
  ```
</RequestExample>

## Response Examples

<ResponseExample>
  ```json Processing Status theme={null}
  {
    "job_id": "47c536aa-9fab-48ca-b27c-2fd74d30490a",
    "status": "processing",
    "progress": "Starting classification...",
    "error": null,
    "result": null
  }
  ```

  ```json Completed Status theme={null}
  {
    "job_id": "47c536aa-9fab-48ca-b27c-2fd74d30490a",
    "status": "completed",
    "progress": "Classification completed",
    "error": null,
    "result": {
      "success": true,
      "classification": "invoice",
      "confidence": 0.9999996871837232,
      "page_results": [
        {
          "page": 1,
          "success": true,
          "confidence": 0.9999996871837232,
          "raw_result": "invoice",
          "classification": "invoice"
        }
      ],
      "total_pages": 1,
      "processed_pages": 1
    }
  }
  ```

  ```json Multi-Page Completed Status theme={null}
  {
    "job_id": "47c536aa-9fab-48ca-b27c-2fd74d30490a",
    "status": "completed",
    "progress": "Classification completed",
    "error": null,
    "result": {
      "success": true,
      "classification": "contract",
      "confidence": 0.89,
      "page_results": [
        {
          "page": 1,
          "success": true,
          "confidence": 0.92,
          "raw_result": "contract",
          "classification": "contract"
        },
        {
          "page": 2,
          "success": true,
          "confidence": 0.86,
          "raw_result": "contract",
          "classification": "contract"
        }
      ],
      "total_pages": 2,
      "processed_pages": 2
    }
  }
  ```

  ```json Failed Status theme={null}
  {
    "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
  }
  ```

  ```json Job Not Found theme={null}
  {
    "detail": "Job not found"
  }
  ```
</ResponseExample>

## Job Status Values

<AccordionGroup>
  <Accordion title="queued">
    Job has been created and is waiting to be picked up for processing. Jobs move to processing as soon as a worker is available.
  </Accordion>

  <Accordion title="processing">
    Job is currently being processed. This includes file upload to storage, document analysis, and classification processing. Progress messages will indicate the current stage.
  </Accordion>

  <Accordion title="completed">
    Job has completed successfully. The result field contains the classification results with confidence scores and page-by-page details.
  </Accordion>

  <Accordion title="failed">
    Job failed during processing. The error field contains details about what went wrong. Common causes include file corruption, invalid conditions, or processing errors.
  </Accordion>
</AccordionGroup>

## Polling Strategy

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

```python theme={null}
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

```json File Processing Error theme={null}
{
  "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
}
```


## OpenAPI

````yaml api-reference/openapi.json GET /classify/{job_id}
openapi: 3.1.0
info:
  title: Unsiloed AI Document Processing API
  description: >-
    A comprehensive API for document processing, extraction, and analysis using
    AI-powered tools
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://prod.visionapi.unsiloed.ai
    description: Production server
security:
  - apiKeyAuth: []
paths:
  /classify/{job_id}:
    get:
      summary: Get Classification Job Status
      description: >-
        Check the status and progress of classification jobs and retrieve
        results
      parameters:
        - in: path
          name: job_id
          schema:
            type: string
          required: true
          description: The unique identifier of the classification job
      responses:
        '200':
          description: Classification job status retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_id:
                    type: string
                    description: Unique identifier for the classification job
                  status:
                    type: string
                    description: Current job status (queued, processing, completed, failed)
                  progress:
                    type: string
                    description: Progress message
                  error:
                    type: string
                    description: Error message if job failed
                  result:
                    type: object
                    description: >-
                      Classification results (only present when status is
                      completed)
                    properties:
                      success:
                        type: boolean
                        description: Whether classification succeeded
                      classification:
                        type: string
                        description: The classified category
                      confidence:
                        type: number
                        description: Confidence score (0-1)
                      total_pages:
                        type: number
                        description: Total number of pages
                      processed_pages:
                        type: number
                        description: Number of pages processed
                      page_results:
                        type: array
                        description: Per-page classification results
                        items:
                          type: object
                          properties:
                            page:
                              type: number
                              description: Page number
                            classification:
                              type: string
                              description: Classification for this page
                            confidence:
                              type: number
                              description: Confidence score for this page
                            success:
                              type: boolean
                              description: Whether this page was classified successfully
                            raw_result:
                              type: string
                              description: >-
                                The model's raw classification output for this
                                page
      security:
        - apiKeyAuth: []
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: api-key

````