Job Lifecycle and Debugging

Start with the failed job's reason, payload, attempts, and logs. Correct the underlying problem before retrying; retries can repeat application side effects, so check your worker's idempotency.

Job List

Queue jobs route context:

• /$orgSlug/c/$connectionId/queues/$queueName

Job listing supports:

• status filter
• job name filter
• job ID lookup and payload search
• pagination (page, pageSize, or index cursor) for unfiltered API listings

Name and payload searches return all matches for client-side pagination. ID search tries an exact match first, then falls back to substring matches. Searches can be expensive on large queues.

API route:

• GET /api/c/:connectionId/queues/:queueName/jobs

Job Detail

Job detail route:

• /$orgSlug/c/$connectionId/queues/$queueName/jobs/$jobId

Shows:

• job data payload
• options and retry metadata
• progress/attempt counters
• return value
• failure reason
• timestamps

API route:

• GET /api/c/:connectionId/queues/:queueName/jobs/:jobId

Logs and Stacktraces

Logs are paginated via BullMQ log API:

• GET /api/c/:connectionId/queues/:queueName/jobs/:jobId/logs
• DELETE /api/c/:connectionId/queues/:queueName/jobs/:jobId/logs clears all logs for the job (permanent Redis deletion)

Stacktraces are served paginated (application-level slicing):

• GET /api/c/:connectionId/queues/:queueName/jobs/:jobId/stacktraces

Important detail:

• BullMQ stores stacktraces in the job hash as an array.
• Pagination reduces transfer cost but still starts from full job retrieval.

Edit data and retry one job

From job detail, use the data editor to correct a payload before retrying. The API exposes:

• POST /api/c/:connectionId/queues/:queueName/jobs/:jobId/data with { "data": ... }.
• POST /api/c/:connectionId/queues/:queueName/jobs/:jobId/retry with {} or { "data": ... }.

Editing an active job returns 409 because a worker is already processing its old payload. Single-job retry is allowed only when the job is failed.

Clear logs or stack traces

The Logs and Stack Traces tabs support permanent cleanup with optional retention of the newest N entries. Use POST .../jobs/:jobId/logs/clear or POST .../jobs/:jobId/stacktraces/clear with { "keepMostRecent": N }. Omitting N clears all entries. Cleanup changes the data stored in Redis.

Bulk and Single-Job Actions

The paths below are relative to /api/c/:connectionId/queues/:queueName:

• Retry failed jobs
  • POST /jobs/retry
• Remove jobs
  • POST /jobs/remove
• Invoke delayed jobs now (optional data override)
  • POST /jobs/invoke
• Add new job
  • POST /jobs

Request safety limits:

• Bulk endpoints cap explicit jobIds arrays at 100 per request.
• Bulk retry can instead select statuses: failed, completed, or all; do not send both jobIds and statuses.
• State conflicts can produce partial results; inspect the response before retrying a bulk operation.

Scheduled/Repeat Job Removal Nuance

For repeat/scheduled jobs (jobId starts with repeat:):

• removing the job may require removing its scheduler
• UI/API support a "remove scheduler too" behavior to stop future runs