5 min read

Get Job Status

Retrieve the status and progress of an asynchronous processing job

Retrieve the current status, progress, and result of an asynchronous document processing job.

GET/v1/jobs/:id

Request

Headers

Parameter	Type	Description
`Authorization`required	`string`	Bearer token or API key for authentication
`X-API-Key`	`string`	Alternative: API key for authentication (use instead of Authorization)

Path Parameters

Parameter	Type	Description
`id`required	`string`	The unique job identifier (e.g., job_abc123def456)

Example Requests

curl

curl -X GET https://api.docurift.com/v1/jobs/job_abc123def456 \
-H "X-API-Key: frc_your_api_key_here"

python

import requests
import os

API_KEY = os.getenv('DOCURIFT_API_KEY')
API_URL = 'https://api.docurift.com/v1'

job_id = 'job_abc123def456'

response = requests.get(
  f'{API_URL}/jobs/{job_id}',
  headers={'X-API-Key': API_KEY}
)

job = response.json()
print(f"Status: {job['data']['status']}")
print(f"Progress: {job['data']['progress']}%")

javascript

const API_KEY = process.env.DOCURIFT_API_KEY;
const API_URL = 'https://api.docurift.com/v1';

const jobId = 'job_abc123def456';

const response = await fetch(`${API_URL}/jobs/${jobId}`, {
headers: {
  'X-API-Key': API_KEY
}
});

const job = await response.json();
console.log(`Status: ${job.data.status}`);
console.log(`Progress: ${job.data.progress}%`);

| Status | Description | |--------|-------------| | pending | Job is queued and waiting to be processed | | processing | Job is currently being processed | | completed | Job finished successfully, result is available | | failed | Job encountered an error during processing |

Success Response - Pending

response.json

{
"success": true,
"data": {
  "id": "job_abc123def456",
  "status": "pending",
  "progress": 0,
  "documentType": "invoice",
  "createdAt": "2024-01-27T10:30:00Z",
  "updatedAt": "2024-01-27T10:30:00Z"
}
}

Success Response - Processing

response.json

{
"success": true,
"data": {
  "id": "job_abc123def456",
  "status": "processing",
  "progress": 45,
  "documentType": "invoice",
  "createdAt": "2024-01-27T10:30:00Z",
  "updatedAt": "2024-01-27T10:30:15Z"
}
}

Success Response - Completed

response.json

{
"success": true,
"data": {
  "id": "job_abc123def456",
  "status": "completed",
  "progress": 100,
  "documentType": "invoice",
  "documentId": "doc_xyz789ghi012",
  "result": {
    "extractedFields": {
      "invoiceNumber": "INV-2024-001",
      "amount": 1250.00,
      "currency": "USD",
      "vendor": "Acme Corp",
      "date": "2024-01-15"
    },
    "confidence": 0.97
  },
  "createdAt": "2024-01-27T10:30:00Z",
  "updatedAt": "2024-01-27T10:30:45Z",
  "completedAt": "2024-01-27T10:30:45Z"
}
}

Success Response - Failed

response.json

{
"success": true,
"data": {
  "id": "job_abc123def456",
  "status": "failed",
  "progress": 23,
  "documentType": "invoice",
  "error": {
    "code": "OCR_FAILED",
    "message": "Unable to extract text from document. The image may be corrupted or too low quality.",
    "details": {
      "step": "text_extraction",
      "retryable": true
    }
  },
  "createdAt": "2024-01-27T10:30:00Z",
  "updatedAt": "2024-01-27T10:30:20Z",
  "failedAt": "2024-01-27T10:30:20Z"
}
}

Response Fields

Parameter	Type	Description
`id`	`string`	Unique identifier for the job
`status`	`string`	Current job status: pending, processing, completed, or failed
`progress`	`number`	Processing progress percentage (0-100)
`documentType`	`string`	Type of document being processed
`documentId`	`string`	ID of the created document (only when status is completed)
`result`	`object`	Extracted data and confidence score (only when status is completed)
`error`	`object`	Error details including code, message, and retry info (only when status is failed)
`createdAt`	`string`	ISO 8601 timestamp when the job was created
`updatedAt`	`string`	ISO 8601 timestamp when the job was last updated
`completedAt`	`string`	ISO 8601 timestamp when the job completed (only when status is completed)
`failedAt`	`string`	ISO 8601 timestamp when the job failed (only when status is failed)

💡

Polling Best Practices

When polling for job status, use exponential backoff starting at 1 second. Most jobs complete within 30 seconds. Consider using webhooks for production applications.

Error Responses

error.json

{
"success": false,
"error": {
  "code": "JOB_NOT_FOUND",
  "message": "Job with ID 'job_abc123def456' not found"
}
}

Common Error Codes

| Code | Status | Description | |------|--------|-------------| | JOB_NOT_FOUND | 404 | The specified job ID does not exist | | UNAUTHORIZED | 401 | Missing or invalid authentication credentials | | INVALID_API_KEY | 401 | The provided API key is invalid or expired | | FORBIDDEN | 403 | You do not have permission to access this job | | RATE_LIMIT_EXCEEDED | 429 | Too many requests, please slow down |

⚠️

Job Retention

Job records are retained for 30 days after completion or failure. After this period, the job status endpoint will return a 404 error.

Polling Example

polling.js

async function waitForJobCompletion(jobId, maxAttempts = 30) {
const API_KEY = process.env.DOCURIFT_API_KEY;
const API_URL = 'https://api.docurift.com/v1';

let attempts = 0;
let delay = 1000; // Start with 1 second

while (attempts < maxAttempts) {
  const response = await fetch(`${API_URL}/jobs/${jobId}`, {
    headers: { 'X-API-Key': API_KEY }
  });

  const { data } = await response.json();

  if (data.status === 'completed') {
    return data;
  }

  if (data.status === 'failed') {
    throw new Error(`Job failed: ${data.error.message}`);
  }

  // Exponential backoff with max 10 seconds
  await new Promise(resolve => setTimeout(resolve, delay));
  delay = Math.min(delay * 1.5, 10000);
  attempts++;
}

throw new Error('Job timed out');
}