Job Management

Monitor and manage your processing jobs with status checks and real-time streaming.

Get Job Status

GET /api/v1/jobs/{id}

Get the current status and details of a processing job.

Parameters

Parameter	Type	Required	Description
id	string	✅	Job ID (path parameter)

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "image_resize",
  "status": "completed",
  "source_bucket": "my-bucket",
  "source_key": "photo.jpg",
  "dest_bucket": "my-bucket",
  "dest_key": "photo-resized.jpg",
  "parameters": {
    "width": 800,
    "height": 600
  },
  "result": {
    "output_url": "s3://my-bucket/photo-resized.jpg",
    "file_size": 245760,
    "duration": 1.23,
    "metadata": {
      "width": 800,
      "height": 600,
      "format": "jpeg"
    }
  },
  "created_at": "2025-10-18T22:00:00Z",
  "updated_at": "2025-10-18T22:00:02Z",
  "completed_at": "2025-10-18T22:00:02Z",
  "duration_seconds": 1.23
}

Job Status Values

pending

Job is queued, waiting for a worker

Queue position may be included

processing

Worker is actively processing the job

Progress updates via SSE

completed

Job finished successfully

Result data available

failed

Job encountered an error

Error message in response

Example

cURL

curl -H "X-API-Key: your_api_key_here" \
  http://localhost:8080/api/v1/jobs/550e8400-e29b-41d4-a716-446655440000

JavaScript

const response = await fetch(
  `http://localhost:8080/api/v1/jobs/${jobId}`,
  {
    headers: {
      'X-API-Key': 'your_api_key_here'
    }
  }
);
const job = await response.json();
console.log('Status:', job.status);

Python

import requests

response = requests.get(
    f'http://localhost:8080/api/v1/jobs/{job_id}',
    headers={'X-API-Key': 'your_api_key_here'}
)
job = response.json()
print(f"Status: {job['status']}")

---

Stream Job Updates

GET /api/v1/jobs/{id}/stream

Subscribe to real-time job status updates via Server-Sent Events (SSE).

Parameters

Parameter	Type	Required	Description
id	string	✅	Job ID (path parameter)

Response

Server-Sent Events stream with updates:

event: status
data: {"status":"pending","message":"Job queued"}

event: status
data: {"status":"processing","message":"Processing started"}

event: progress
data: {"percent":50,"message":"Processing frame 50/100"}

event: complete
data: {"status":"completed","result":{...}}

Event Types

Event	Description
status	Job status changed
progress	Processing progress update
complete	Job completed (success or failure)
error	Error occurred

Example

JavaScript

const eventSource = new EventSource(
  `http://localhost:8080/api/v1/jobs/${jobId}/stream`
);

eventSource.addEventListener('status', (e) => {
  const data = JSON.parse(e.data);
  console.log('Status:', data.status);
});

eventSource.addEventListener('progress', (e) => {
  const data = JSON.parse(e.data);
  console.log('Progress:', data.percent + '%');
});

eventSource.addEventListener('complete', (e) => {
  const data = JSON.parse(e.data);
  console.log('Completed:', data);
  eventSource.close();
});

eventSource.addEventListener('error', (e) => {
  console.error('Error:', e);
  eventSource.close();
});

cURL

curl -N -H "Accept: text/event-stream" \
  http://localhost:8080/api/v1/jobs/550e8400-e29b-41d4-a716-446655440000/stream

Python

import sseclient
import requests

response = requests.get(
    f'http://localhost:8080/api/v1/jobs/{job_id}/stream',
    stream=True,
    headers={'Accept': 'text/event-stream'}
)

client = sseclient.SSEClient(response)
for event in client.events():
    print(f"Event: {event.event}")
    print(f"Data: {event.data}")

When to Use SSE

Use Server-Sent Events for:

• Real-time progress updates in UI
• Long-running jobs where you need immediate feedback
• Building interactive dashboards

For simple status checks, use the regular GET endpoint.

Learn more in the SSE Guide.

---

List All Jobs

GET /api/v1/jobs

Get a list of all jobs with optional filtering.

Query Parameters

Parameter	Type	Description
status	string	Filter by status: pending, processing, completed, failed
limit	integer	Maximum results (default: 100, max: 1000)

Response

{
  "jobs": [
    {
      "id": "job-1",
      "type": "image_resize",
      "status": "completed",
      "created_at": "2025-10-18T22:00:00Z"
    },
    {
      "id": "job-2",
      "type": "video_thumbnail",
      "status": "processing",
      "created_at": "2025-10-18T22:01:00Z"
    }
  ],
  "total": 2
}

Example

All Jobs

curl -H "X-API-Key: your_api_key_here" \
  "http://localhost:8080/api/v1/jobs?limit=50"

Filter by Status

curl -H "X-API-Key: your_api_key_here" \
  "http://localhost:8080/api/v1/jobs?status=failed&limit=20"

JavaScript

const response = await fetch(
  'http://localhost:8080/api/v1/jobs?status=completed&limit=50',
  {
    headers: {
      'X-API-Key': 'your_api_key_here'
    }
  }
);
const data = await response.json();
console.log(`Found ${data.total} jobs`);

---

Job Result Data

When a job completes successfully, the result object contains:

Image Jobs

{
  "output_url": "s3://bucket/output.jpg",
  "file_size": 245760,
  "duration": 1.23,
  "metadata": {
    "width": 800,
    "height": 600,
    "format": "jpeg"
  }
}

Color Extraction

{
  "colors": ["#3B82F6", "#10B981", "#F59E0B"],
  "percentages": [45.2, 32.1, 22.7]
}

AI Keywords

{
  "keywords": ["sunset", "beach", "ocean", "tropical"],
  "confidence_scores": [0.95, 0.92, 0.89, 0.87]
}

Video Thumbnail

{
  "output_url": "s3://bucket/thumbnail.jpg",
  "file_size": 125440,
  "timestamp": "00:00:05",
  "metadata": {
    "width": 1280,
    "height": 720
  }
}

---

Polling vs Streaming

Polling (GET /jobs/{id})

Best for:

• Simple status checks
• Batch processing
• Background jobs

Pros:

• Simple to implement
• Works everywhere

Cons:

• Higher latency
• More API calls

Streaming (SSE)

Best for:

• Real-time UI updates
• Long-running jobs
• Progress tracking

Pros:

• Instant updates
• Efficient

Cons:

• Requires SSE support
• Keeps connection open

---

Error Responses

Job Not Found

404 Not Found

{
  "error": "Job not found"
}

Job Failed

When a job fails, the response includes an error message:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "Source file not found in S3: my-bucket/photo.jpg",
  "created_at": "2025-10-18T22:00:00Z",
  "updated_at": "2025-10-18T22:00:01Z"
}

---

Use Cases

Progress Bars

Show real-time progress in your UI with SSE

Status Dashboards

Monitor all jobs with the list endpoint

Retry Logic

Check failed jobs and retry with corrected parameters

Analytics

Track job completion rates and processing times

---

Best Practices

Recommendations

1. Use webhooks instead of polling when possible
2. Implement exponential backoff for polling
3. Close SSE connections when job completes
4. Store job IDs for later reference
5. Handle network errors gracefully

Polling Example with Backoff

async function waitForJob(jobId, maxAttempts = 30) {
  let attempt = 0;

  while (attempt < maxAttempts) {
    const response = await fetch(`/api/v1/jobs/${jobId}`, {
      headers: { 'X-API-Key': apiKey }
    });
    const job = await response.json();

    if (job.status === 'completed' || job.status === 'failed') {
      return job;
    }

    // Exponential backoff: 1s, 2s, 4s, 8s, ...
    const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
    await new Promise(resolve => setTimeout(resolve, delay));
    attempt++;
  }

  throw new Error('Job timeout');
}

---

Next Steps

• Set up Webhooks for automatic notifications
• Learn about Server-Sent Events
• Explore Batch Operations