Jobs
The jobs feature defines executable queue units derived from tasks and provider events. It gives you direct operational control over retries, manual triggering, and resolution when async work fails.
Why This Matters
This feature makes queue execution observable at per-job granularity, so failures are diagnosable and recoverable without guesswork. It supports deterministic operator recovery through explicit retry, trigger, and resolve actions while keeping cleanup operations deliberate and scoped.
Core Flow
Tasks or provider events produce jobs that workers execute and annotate with status, attempts, and failure detail. Operators review failed or stalled jobs in account queue views, run explicit retry/resolve/trigger actions, and use resulting job state to track task lifecycle and audit traces.
Operations
| Operation | Endpoint | Purpose |
|---|---|---|
| List jobs | GET /api/accounts/:account_id/jobs | Fetch account job queue |
| Search jobs | POST /api/accounts/:account_id/jobs/search | Query jobs by filter |
| Delete jobs by search | POST /api/accounts/:account_id/jobs/search-delete | Bulk delete matched jobs |
| Get job | GET /api/jobs/:job_id | Retrieve one job |
| Update job | PATCH /api/jobs/:job_id | Modify mutable job fields |
| Delete job | DELETE /api/jobs/:job_id | Remove one job |
| Retry job | POST /api/jobs/:job_id/retry | Requeue failed job |
| Resolve job | POST /api/jobs/:job_id/resolve | Mark terminal handling state |
| Trigger job | POST /api/jobs/:job_id/trigger | Force execution trigger |
Key Data and State
{
id: "job_...",
account_id: "acc_...",
task_id: "tsk_...",
action: "imap_sync_messages",
attempt_count: 2,
last_error_code: "provider_timeout",
last_error_detail: "IMAP connection timed out"
}Failure Modes and Controls
Failed executions preserve explicit error details for deterministic handling. Retry, trigger, and resolve are command-style operations rather than implicit read side effects, and account-scoped list/search boundaries prevent cross-account queue visibility.