Job Queue API Reference

Monitor and manage background jobs that process your training data (website content, products, documents).

Overview

The Job Queue API allows you to:

Monitor background job status and progress
View job statistics and metrics
Cancel pending or processing jobs
Manage failed jobs in the dead letter queue
Track queue depth and processing times

Authentication

All endpoints require JWT token authentication:

Authorization: Bearer <jwt_token>

Base URL

https://api.yourdomain.com/api

Job Status Endpoints

List Jobs

http

GET /api/jobs

Retrieve a list of jobs with optional filtering.

Query Parameters:

status (optional) - Filter by status: pending, processing, completed, failed, retrying, cancelled
job_type (optional) - Filter by job type: website_chunk_embed, product_chunk_embed, document_process
limit (optional) - Number of jobs to return (default: 50, max: 100)
offset (optional) - Pagination offset (default: 0)

Response: 200 OK

json

{
  "jobs": [
    {
      "id": "job-123",
      "tenant_id": "tenant-456",
      "job_type": "website_chunk_embed",
      "status": "processing",
      "priority": 0,
      "attempts": 1,
      "max_attempts": 3,
      "progress": {
        "current": 2,
        "total": 3,
        "step": "generating_embeddings",
        "chunks": 15
      },
      "started_at": "2024-01-15T10:00:00Z",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:05:00Z"
    }
  ],
  "pagination": {
    "total": 25,
    "limit": 50,
    "offset": 0
  }
}

Example:

bash

curl -X GET "https://api.yourdomain.com/api/jobs?status=processing&limit=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get Job Details

http

GET /api/jobs/:id

Retrieve detailed information about a specific job.

Parameters:

id - Job ID

Response: 200 OK

json

{
  "id": "job-123",
  "tenant_id": "tenant-456",
  "job_type": "website_chunk_embed",
  "job_data": {
    "page_id": "page-789",
    "content_text": "...",
    "page_title": "About Us"
  },
  "status": "completed",
  "priority": 0,
  "attempts": 1,
  "max_attempts": 3,
  "progress": {
    "current": 3,
    "total": 3,
    "step": "completed",
    "chunks_stored": 15
  },
  "result": {
    "success": true
  },
  "started_at": "2024-01-15T10:00:00Z",
  "completed_at": "2024-01-15T10:05:00Z",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:05:00Z"
}

Error Responses:

404 Not Found - Job not found
401 Unauthorized - Invalid or missing authentication

Cancel Job

http

POST /api/jobs/:id/cancel

Cancel a pending or processing job.

Parameters:

id - Job ID

Request Body:

json

{
  "reason": "User requested cancellation" // optional
}

Response: 200 OK

json

{
  "message": "Job cancelled successfully"
}

Error Responses:

400 Bad Request - Job cannot be cancelled (already completed/failed)
404 Not Found - Job not found
401 Unauthorized - Invalid or missing authentication

Note: Processing jobs will be cancelled at the next cancellation check point. This may take a few seconds.

Statistics Endpoints

Get Job Statistics

http

GET /api/jobs/stats

Get aggregate statistics about jobs.

Response: 200 OK

json

{
  "by_status": {
    "pending": 5,
    "processing": 2,
    "completed": 150,
    "failed": 3,
    "retrying": 1
  },
  "by_type": {
    "website_chunk_embed": {
      "pending": 3,
      "processing": 1,
      "completed": 100,
      "failed": 2
    },
    "product_chunk_embed": {
      "pending": 2,
      "processing": 1,
      "completed": 50,
      "failed": 1
    }
  },
  "avg_processing_time_ms": 125000,
  "success_rate": 98.0
}

Get Queue Depth

http

GET /api/jobs/queue-depth

Get current queue depth metrics by job type.

Response: 200 OK

json

{
  "by_type": {
    "website_chunk_embed": {
      "pending": 5,
      "processing": 2,
      "retrying": 1
    },
    "product_chunk_embed": {
      "pending": 3,
      "processing": 1,
      "retrying": 0
    }
  }
}

Metrics Endpoint

Get Job Metrics

http

GET /api/jobs/metrics

Get time-series metrics for job performance.

Query Parameters:

start_date (optional) - Start date (ISO 8601 format)
end_date (optional) - End date (ISO 8601 format)
job_type (optional) - Filter by job type
metric_name (optional) - Filter by metric name

Available Metrics:

job_processing_time_ms - Time to complete jobs
job_queue_depth - Number of pending jobs
job_success_count - Successful job completions
job_failure_count - Failed jobs
job_retry_count - Job retries

Response: 200 OK

json

{
  "metrics": [
    {
      "metric_name": "job_processing_time_ms",
      "time_bucket": "2024-01-15T10:00:00Z",
      "avg_value": 125000,
      "min_value": 45000,
      "max_value": 300000,
      "sample_count": 25
    }
  ]
}

Dead Letter Queue

List Dead Letter Jobs

http

GET /api/jobs/dead-letters

Retrieve jobs that have permanently failed.

Query Parameters:

job_type (optional) - Filter by job type
error_category (optional) - Filter by error category: permanent, timeout, rate_limit, transient, unknown
limit (optional) - Number of jobs to return (default: 50)
offset (optional) - Pagination offset (default: 0)

Response: 200 OK

json

{
  "jobs": [
    {
      "id": "dead-letter-123",
      "original_job_id": "job-456",
      "job_type": "website_chunk_embed",
      "status": "failed",
      "error_category": "permanent",
      "error_code": "VALIDATION_ERROR",
      "last_error": "Missing required job data: page_id",
      "failure_reason_category": "permanent_error",
      "archived_at": "2024-01-15T10:00:00Z"
    }
  ]
}

Retry Dead Letter Job

http

POST /api/jobs/dead-letters/:id/retry

Create a new job from a dead letter job to retry processing.

Parameters:

id - Dead letter job ID

Response: 200 OK

json

{
  "message": "Dead letter job retried successfully",
  "new_job_id": "job-789"
}

Error Responses:

404 Not Found - Dead letter job not found
401 Unauthorized - Invalid or missing authentication

Delete Dead Letter Job

http

DELETE /api/jobs/dead-letters/:id

Permanently delete a dead letter job.

Parameters:

id - Dead letter job ID

Response: 200 OK

json

{
  "message": "Dead letter job deleted successfully"
}

Job Types

Website Chunk Embed

Processes website pages for embedding generation:

Job Type: website_chunk_embed
Default Timeout: 30 minutes

Job Data:

json

{
  "page_id": "page-uuid",
  "content_text": "Page content...",
  "page_title": "Page Title"
}

Product Chunk Embed

Processes product data for embedding generation:

Job Type: product_chunk_embed
Default Timeout: 30 minutes

Job Data:

json

{
  "product_id": "product-uuid",
  "product": {
    "name": "Product Name",
    "description": "Product description...",
    "metadata": {}
  }
}

Document Process

Processes large documents (future):

Job Type: document_process
Default Timeout: 60 minutes

Job Statuses

pending - Job is queued and waiting to be processed
processing - Job is currently being processed by a worker
completed - Job finished successfully
failed - Job failed permanently (moved to dead letter queue)
retrying - Job failed but will be retried
cancelled - Job was cancelled by user

Error Categories

permanent - Validation errors, missing data (no retry, archived immediately)
rate_limit - API rate limit exceeded (longer retry delay: 15+ minutes)
timeout - Job exceeded timeout (single retry, then archived)
transient - Network errors, temporary failures (standard exponential backoff)
unknown - Unclassified errors (standard exponential backoff)

Progress Tracking

Jobs report progress during processing:

json

{
  "progress": {
    "current": 2,
    "total": 3,
    "step": "generating_embeddings",
    "chunks": 15
  }
}

Progress Steps:

chunking / preparing_fields - Preparing content
generating_embeddings - Creating embeddings
storing_chunks - Saving to database
completed - Finished

Best Practices

Monitor Queue Depth: Check queue depth regularly to ensure jobs are processing
Handle Dead Letters: Review dead letter jobs periodically to identify issues
Use Metrics: Track processing times to optimize job configuration
Cancel When Needed: Cancel jobs that are no longer needed to free resources
Check Status: Poll job status for long-running operations

Error Handling

Rate Limiting

If you exceed API rate limits:

Response: 429 Too Many Requests
Action: Wait before retrying
Retry-After: Check response headers

Job Not Found

If a job doesn't exist:

Response: 404 Not Found
Action: Verify job ID and tenant access

Unauthorized

If authentication fails:

Response: 401 Unauthorized
Action: Verify JWT token is valid and not expired

Website Training Context - Website crawling and processing
Products Training Context - Product data management
Documents Training Context - Document processing
Overview - Training context overview

Job Queue API Reference ​

Overview ​

Authentication ​

Base URL ​

Job Status Endpoints ​

List Jobs ​

Get Job Details ​

Cancel Job ​

Statistics Endpoints ​

Get Job Statistics ​

Get Queue Depth ​

Metrics Endpoint ​

Get Job Metrics ​

Dead Letter Queue ​

List Dead Letter Jobs ​

Retry Dead Letter Job ​

Delete Dead Letter Job ​

Job Types ​

Website Chunk Embed ​

Product Chunk Embed ​

Document Process ​

Job Statuses ​

Error Categories ​

Progress Tracking ​

Best Practices ​

Error Handling ​

Rate Limiting ​

Job Not Found ​

Unauthorized ​

Related Documentation ​

Job Queue API Reference

Overview

Authentication

Base URL

Job Status Endpoints

List Jobs

Get Job Details

Cancel Job

Statistics Endpoints

Get Job Statistics

Get Queue Depth

Metrics Endpoint

Get Job Metrics

Dead Letter Queue

List Dead Letter Jobs

Retry Dead Letter Job

Delete Dead Letter Job

Job Types

Website Chunk Embed

Product Chunk Embed

Document Process

Job Statuses

Error Categories

Progress Tracking

Best Practices

Error Handling

Rate Limiting

Job Not Found

Unauthorized

Related Documentation