Job Status

Learn how Mend tracks job status throughout the processing lifecycle.

Job Lifecycle

1. Created

Job is submitted via API

• Assigned unique job ID
• Saved to Redis
• Status: pending

2. Queued

Job is waiting for a worker

• In Redis queue
• Position depends on priority
• Status: pending

3. Processing

Worker is actively processing

• Media downloaded from S3
• Transformation applied
• Status: processing

4. Complete

Job finished successfully

• Result uploaded to S3
• Webhook sent (if configured)
• Status: completed

Job Statuses

Status	Description	Next State
pending	Job queued, waiting for worker	processing or failed
processing	Worker is actively processing	completed or failed
completed	Job finished successfully	Terminal state
failed	Job encountered an error	Terminal state (or retry)

Get Job Status

GET /api/v1/jobs/{id}

Response (Completed)

{
  "id": "c815faad-3e99-4d0f-99a3-af61bfc7f26e",
  "type": "image_resize",
  "status": "completed",
  "source_bucket": "my-bucket",
  "source_key": "images/input.jpg",
  "dest_bucket": "my-bucket",
  "dest_key": "images/output.jpg",
  "parameters": {
    "width": 800,
    "height": 600,
    "quality": 85
  },
  "result": {
    "output_url": "s3://my-bucket/images/output.jpg",
    "file_size": 245678,
    "duration": 1.23,
    "metadata": {
      "width": 800,
      "height": 600,
      "format": "jpeg"
    }
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:15Z",
  "completed_at": "2024-01-15T10:30:15Z",
  "duration_seconds": 1.23
}

Response (Failed)

{
  "id": "c815faad-3e99-4d0f-99a3-af61bfc7f26e",
  "type": "image_resize",
  "status": "failed",
  "error": "Source file not found: s3://my-bucket/images/input.jpg",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:05Z"
}

Data Retention

7-Day Retention

Job data is stored in Redis with a TTL of 7 days. After this period, job information is automatically deleted.

Retention Policy:

• Completed jobs: 7 days
• Failed jobs: 7 days
• Pending jobs: Until processed or expired

Best Practices:

• Store important job results in your own database
• Use webhooks for immediate notifications
• Don’t rely on job status API for long-term tracking

Example Workflow

# 1. Submit job
RESPONSE=$(curl -X POST http://localhost:8080/api/v1/jobs/image/resize \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "source_bucket": "my-bucket",
    "source_key": "input.jpg",
    "dest_bucket": "my-bucket",
    "dest_key": "output.jpg",
    "width": 800,
    "height": 600
  }')

# 2. Extract job ID
JOB_ID=$(echo $RESPONSE | jq -r '.job_id')

# 3. Poll for status
while true; do
  STATUS=$(curl -s http://localhost:8080/api/v1/jobs/$JOB_ID \
    -H "X-API-Key: your-api-key" | jq -r '.status')

  echo "Status: $STATUS"

  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
    break
  fi

  sleep 2
done

# 4. Get final result
curl http://localhost:8080/api/v1/jobs/$JOB_ID \
  -H "X-API-Key: your-api-key" | jq

Status Updates

The worker automatically updates job status at key points:

Start Processing

Status: pending → processing

Worker begins downloading source file

On Error

Status: * → failed

Error message saved to job record

On Success

Status: processing → completed

Result data saved with output URL

Redis Keys

Jobs are stored with the key pattern:

mend:job:{job_id}

Example:

mend:job:c815faad-3e99-4d0f-99a3-af61bfc7f26e

Queue Position

For pending jobs, you can check queue position:

{
  "id": "job-123",
  "status": "pending",
  "queue_position": 5,
  "estimated_wait_seconds": 30
}

Tip

Queue position is approximate and depends on:

• Job priority
• Worker availability
• Current queue depth

Monitoring Tips

Use Webhooks

Get notified immediately when jobs complete instead of polling

Use SSE

Stream real-time updates for long-running jobs

Track Metrics

Monitor queue depth and processing times

Set Timeouts

Implement client-side timeouts for stuck jobs

Next Steps

• Learn about Server-Sent Events for real-time updates
• Set up Webhooks for notifications
• Explore Job Management API