Jobs API

Monitor and manage background processing jobs.

List Jobs


GET /api/jobs

Get a list of processing jobs.

Query Parameters

Parameter	Default	Description
`status`	-	Filter by status
`type`	-	Filter by job type
`limit`	50	Results per page
`offset`	0	Pagination offset

Response


{
  "jobs": [
    {
      "id": "job-uuid",
      "type": "parse",
      "status": "completed",
      "progress": 100,
      "document_id": "doc-uuid",
      "created_at": "2024-01-15T10:00:00Z",
      "completed_at": "2024-01-15T10:00:30Z"
    },
    {
      "id": "job-uuid",
      "type": "extract",
      "status": "processing",
      "progress": 50,
      "document_id": "doc-uuid",
      "created_at": "2024-01-15T10:01:00Z"
    }
  ],
  "total": 150,
  "has_more": true
}

Get Job Status


GET /api/jobs/{id}

Get detailed status for a specific job.

Response


{
  "id": "job-uuid",
  "type": "parse",
  "status": "completed",
  "progress": 100,
  "document_id": "doc-uuid",
  "input_url": "https://example.com/doc.pdf",
  "result": {
    "chunks": [...],
    "metadata": {...}
  },
  "metadata": {
    "filename": "document.pdf",
    "file_type": "pdf",
    "pages": 10
  },
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:25Z",
  "completed_at": "2024-01-15T10:00:30Z"
}

Cancel Job


DELETE /api/jobs/{id}

Cancel a pending or processing job.

Response


{
  "success": true,
  "job_id": "job-uuid",
  "status": "cancelled"
}

Note: Only jobs in queued or processing status can be cancelled.

Job Types

Type	Description
`parse`	Document parsing
`extract`	Data extraction
`split`	Document splitting
`generate`	Document generation
`edit`	Document editing
`workflow`	Workflow execution

Job Statuses

Status	Description
`queued`	Job is waiting to be processed
`processing`	Job is currently running
`completed`	Job finished successfully
`failed`	Job encountered an error
`cancelled`	Job was cancelled
`retrying`	Job is being retried after failure

Job Progress

Jobs report progress as a percentage (0-100):


{
  "status": "processing",
  "progress": 45,
  "stage": "chunking"
}

Progress Stages

Stage	Description
`uploading`	File being uploaded
`parsing`	Content extraction
`ocr`	OCR processing
`chunking`	Text chunking
`vectorizing`	Vectorizing (Pinecone llama-text-embed-v2)
`extracting`	Running extraction
`generating`	Generating output

Error Handling

Failed jobs include error details:


{
  "status": "failed",
  "error": "OCR failed: Unable to process image",
  "error_code": "OCR_ERROR",
  "retry_count": 3
}

Common Error Codes

Code	Description
`TIMEOUT`	Job exceeded time limit
`OCR_ERROR`	OCR processing failed
`PARSE_ERROR`	Document parsing failed
`VALIDATION_ERROR`	Invalid input
`QUOTA_EXCEEDED`	Credit quota exceeded
`INTERNAL_ERROR`	Internal server error

Polling for Status

For async operations, poll the job status:


async function waitForJob(jobId) {
  const maxAttempts = 30;
  const delay = 2000; // 2 seconds
  
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(`/api/jobs/${jobId}`, {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    });
    const job = await response.json();
    
    if (job.status === 'completed') {
      return job.result;
    }
    
    if (job.status === 'failed') {
      throw new Error(job.error);
    }
    
    await new Promise(resolve => setTimeout(resolve, delay));
  }
  
  throw new Error('Job timed out');
}

Webhook Alternative

Instead of polling, use webhooks to receive job completion notifications:


{
  "input": "https://example.com/document.pdf",
  "webhook_url": "https://your-server.com/job-complete"
}

See Webhooks for more details.

Jobs API

Monitor and manage background processing jobs.

List Jobs


GET /api/jobs

Get a list of processing jobs.

Query Parameters

Parameter	Default	Description
`status`	-	Filter by status
`type`	-	Filter by job type
`limit`	50	Results per page
`offset`	0	Pagination offset

Response


{
  "jobs": [
    {
      "id": "job-uuid",
      "type": "parse",
      "status": "completed",
      "progress": 100,
      "document_id": "doc-uuid",
      "created_at": "2024-01-15T10:00:00Z",
      "completed_at": "2024-01-15T10:00:30Z"
    },
    {
      "id": "job-uuid",
      "type": "extract",
      "status": "processing",
      "progress": 50,
      "document_id": "doc-uuid",
      "created_at": "2024-01-15T10:01:00Z"
    }
  ],
  "total": 150,
  "has_more": true
}

Get Job Status


GET /api/jobs/{id}

Get detailed status for a specific job.

Response


{
  "id": "job-uuid",
  "type": "parse",
  "status": "completed",
  "progress": 100,
  "document_id": "doc-uuid",
  "input_url": "https://example.com/doc.pdf",
  "result": {
    "chunks": [...],
    "metadata": {...}
  },
  "metadata": {
    "filename": "document.pdf",
    "file_type": "pdf",
    "pages": 10
  },
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:25Z",
  "completed_at": "2024-01-15T10:00:30Z"
}

Cancel Job


DELETE /api/jobs/{id}

Cancel a pending or processing job.

Response


{
  "success": true,
  "job_id": "job-uuid",
  "status": "cancelled"
}

Note: Only jobs in queued or processing status can be cancelled.

Job Types

Type	Description
`parse`	Document parsing
`extract`	Data extraction
`split`	Document splitting
`generate`	Document generation
`edit`	Document editing
`workflow`	Workflow execution

Job Statuses

Status	Description
`queued`	Job is waiting to be processed
`processing`	Job is currently running
`completed`	Job finished successfully
`failed`	Job encountered an error
`cancelled`	Job was cancelled
`retrying`	Job is being retried after failure

Job Progress

Jobs report progress as a percentage (0-100):


{
  "status": "processing",
  "progress": 45,
  "stage": "chunking"
}

Progress Stages

Stage	Description
`uploading`	File being uploaded
`parsing`	Content extraction
`ocr`	OCR processing
`chunking`	Text chunking
`vectorizing`	Vectorizing (Pinecone llama-text-embed-v2)
`extracting`	Running extraction
`generating`	Generating output

Error Handling

Failed jobs include error details:


{
  "status": "failed",
  "error": "OCR failed: Unable to process image",
  "error_code": "OCR_ERROR",
  "retry_count": 3
}

Common Error Codes

Code	Description
`TIMEOUT`	Job exceeded time limit
`OCR_ERROR`	OCR processing failed
`PARSE_ERROR`	Document parsing failed
`VALIDATION_ERROR`	Invalid input
`QUOTA_EXCEEDED`	Credit quota exceeded
`INTERNAL_ERROR`	Internal server error

Polling for Status

For async operations, poll the job status:


async function waitForJob(jobId) {
  const maxAttempts = 30;
  const delay = 2000; // 2 seconds
  
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(`/api/jobs/${jobId}`, {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    });
    const job = await response.json();
    
    if (job.status === 'completed') {
      return job.result;
    }
    
    if (job.status === 'failed') {
      throw new Error(job.error);
    }
    
    await new Promise(resolve => setTimeout(resolve, delay));
  }
  
  throw new Error('Job timed out');
}

Webhook Alternative

Instead of polling, use webhooks to receive job completion notifications:


{
  "input": "https://example.com/document.pdf",
  "webhook_url": "https://your-server.com/job-complete"
}

See Webhooks for more details.