Check status

Endpoint

GET /ocr/v1/:id

curl https://api.case.dev/ocr/v1/JOB_ID \
  -H "Authorization: Bearer sk_case_YOUR_API_KEY"

casedev ocr:v1 retrieve --id $JOB_ID

import Casedev from 'casedev';

const client = new Casedev({ apiKey: 'sk_case_YOUR_API_KEY' });

const job = await client.ocr.v1.retrieve(jobId);

console.log(job.status);           // 'pending' | 'processing' | 'completed' | 'failed'
console.log(job.chunks_completed); // Progress
console.log(job.page_count);       // Total pages

import casedev

client = casedev.Casedev(api_key='sk_case_YOUR_API_KEY')

job = client.ocr.v1.retrieve(job_id)

print(job.status)            # 'pending' | 'processing' | 'completed' | 'failed'
print(job.chunks_completed)  # Progress
print(job.page_count)        # Total pages

result, _ := client.Ocr.V1.Get(ctx, jobID)
fmt.Println(result.Status)

Query parameters

Parameter	Type	Default	Description
`include_text`	boolean	`false`	Include the full extracted text in a completed status response.

Response (processing)

{
  "id": "1f4a195e-026b-41ff-b367-c61089f5f367",
  "status": "processing",
  "page_count": 245,
  "chunk_count": 50,
  "chunks_completed": 23,
  "chunks_processing": 15,
  "created_at": "2025-11-04T09:30:12Z"
}

Response (completed)

{
  "id": "1f4a195e-026b-41ff-b367-c61089f5f367",
  "status": "completed",
  "page_count": 245,
  "confidence": 0.96,
  "processing_time_ms": 1091000,
  "links": {
    "text": "https://api.case.dev/ocr/v1/.../download/text",
    "json": "https://api.case.dev/ocr/v1/.../download/json",
    "pdf": "https://api.case.dev/ocr/v1/.../download/pdf"
  }
}

Status responses omit full OCR text by default. Download the text result when processing completes, or pass include_text=true when inline text is required.

Status values

Status	Meaning
`pending`	Queued, not started
`processing`	OCR in progress
`completed`	Done, results ready
`failed`	Processing failed

Failure details

Failed jobs retain the readable error string and add error_code, error_stage, and retryable. Codes distinguish source download, document validation, engine, and output failures. retryable: false means the input or request needs attention before another attempt; it does not schedule a retry. Older jobs may have unclassified diagnostics.

Response (failed)

{
  "id": "1f4a195e-026b-41ff-b367-c61089f5f367",
  "status": "failed",
  "error": "1 of 3 OCR chunks failed.",
  "error_code": "chunks_failed",
  "error_stage": "chunk_processing",
  "retryable": false,
  "chunks_failed": 1,
  "chunk_count": 3,
  "failed_chunks": [
    {
      "chunk_id": "chunk-2",
      "page_start": 11,
      "page_end": 20,
      "error": "The OCR engine ran out of memory. The document needs smaller processing chunks.",
      "error_code": "gpu_out_of_memory",
      "error_stage": "inference",
      "retryable": false
    }
  ]
}

failed_chunks contains at most 20 samples with one-based inclusive page ranges. Use chunks_failed and chunk_count for exact totals. New Vision terminal callbacks include the same failure fields as status polling. Submission HTTP errors can carry safe diagnostics in the response’s data object, alongside the original HTTP status. Match failures using error_code, rather than the human-readable error message, which may change. Failed-job responses retain validated identity, timing, and progress fields; they exclude upstream debug fields, traces, source URLs, and result links.

Polling example

casedev ocr:v1 retrieve --id $JOB_ID

async function waitForOCR(jobId: string) {
  while (true) {
    const job = await client.ocr.v1.retrieve(jobId);

    if (job.status === 'completed') {
      return job;
    }
    if (job.status === 'failed') {
      throw new Error('OCR failed');
    }

    // Wait 5 seconds before checking again
    await new Promise(r => setTimeout(r, 5000));
  }
}

const result = await waitForOCR(jobId);
const text = await client.ocr.v1.download(jobId, 'text');
console.log(text);

import time

def wait_for_ocr(job_id: str):
    while True:
        job = client.ocr.v1.retrieve(job_id)

        if job.status == 'completed':
            return job
        if job.status == 'failed':
            raise Exception('OCR failed')

        # Wait 5 seconds before checking again
        time.sleep(5)

result = wait_for_ocr(job_id)
text = client.ocr.v1.download(job_id, 'text')
print(text)

result, _ := client.Ocr.V1.Get(ctx, jobID)
fmt.Println(result.Status)

Use webhooks for large documents. Set callback_url when submitting to avoid polling.

Get Started

Platform

Resources

Query parameters

Status values

Failure details

Polling example

​Query parameters

​Status values

​Failure details

​Polling example

Query parameters

Status values

Failure details

Polling example