Skip to main content

Dead Jobs API

List Dead Jobs

GET /api/v1/dead-jobs
Query Parameters:
  • class_name - Filter by job class
  • error_class - Filter by error type
  • queue - Filter by queue
  • since - Dead since timestamp
  • limit - Max results (default: 50)
Response:
{
  "dead_jobs": [
    {
      "id": "dead_abc123",
      "class_name": "SendEmailJob",
      "queue": "mailers",
      "arguments": { "user_id": 123, "template": "welcome" },
      "error_class": "Net::SMTPAuthenticationError",
      "error_message": "Authentication failed",
      "attempts": 5,
      "first_failed_at": "2024-01-15T10:00:00Z",
      "died_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 15,
  "pagination": {
    "page": 1,
    "per_page": 50
  }
}

Get Dead Job Details

GET /api/v1/dead-jobs/:id
Response:
{
  "id": "dead_abc123",
  "class_name": "SendEmailJob",
  "queue": "mailers",
  "arguments": { "user_id": 123, "template": "welcome" },
  "error_class": "Net::SMTPAuthenticationError",
  "error_message": "Authentication failed",
  "backtrace": [
    "app/services/email_service.rb:45:in `send'",
    "app/jobs/send_email_job.rb:12:in `perform'"
  ],
  "attempts": 5,
  "retry_history": [
    {
      "attempt": 1,
      "failed_at": "2024-01-15T10:00:00Z",
      "error": "Connection timeout"
    },
    {
      "attempt": 2,
      "failed_at": "2024-01-15T10:05:00Z",
      "error": "Authentication failed"
    }
  ],
  "first_failed_at": "2024-01-15T10:00:00Z",
  "died_at": "2024-01-15T10:30:00Z",
  "original_enqueued_at": "2024-01-15T09:55:00Z"
}

Retry Dead Job

POST /api/v1/dead-jobs/:id/retry
Response:
{
  "dead_job_id": "dead_abc123",
  "new_job_id": "job_xyz789",
  "queue": "mailers",
  "message": "Job requeued successfully"
}

Retry Multiple Dead Jobs

POST /api/v1/dead-jobs/retry
Request:
{
  "job_ids": ["dead_abc123", "dead_def456"],
  // OR filter-based retry:
  "filter": {
    "class_name": "SendEmailJob",
    "error_class": "Net::SMTPAuthenticationError"
  }
}
Response:
{
  "retried": 5,
  "failed": 0,
  "message": "5 jobs requeued successfully"
}

Delete Dead Job

DELETE /api/v1/dead-jobs/:id
Response:
{
  "id": "dead_abc123",
  "deleted": true
}

Delete Multiple Dead Jobs

DELETE /api/v1/dead-jobs
Request:
{
  "job_ids": ["dead_abc123", "dead_def456"],
  // OR filter-based delete:
  "filter": {
    "older_than": "2024-01-01T00:00:00Z"
  },
  "confirm": true
}
Response:
{
  "deleted": 42,
  "message": "42 dead jobs deleted"
}

Dead Job Analytics

GET /api/v1/dead-jobs/analytics
Query Parameters:
  • period - Time period: day, week, month
Response:
{
  "period": "week",
  "total_dead": 127,
  "by_class": [
    { "class_name": "ImportDataJob", "count": 45 },
    { "class_name": "SendEmailJob", "count": 32 }
  ],
  "by_error": [
    { "error_class": "ActiveRecord::RecordNotFound", "count": 38 },
    { "error_class": "Timeout::Error", "count": 25 }
  ],
  "timeline": [
    { "date": "2024-01-15", "count": 12 },
    { "date": "2024-01-14", "count": 18 }
  ]
}