Jobs

A job is one unit of work on a named queue: a payload plus status, attempts, and optional scheduling metadata.

Enqueue

const { jobId, status } = await rest.queues.enqueue(
  "emails",
  { to: "[email protected]" },
  {
    delay: "30s",
    idempotencyKey: "welcome-user-42",
    scheduleAt: "2026-07-16T12:00:00Z",
    metadata: { source: "signup" },
  }
);

HTTP:

POST /v1/queue/:queueName/jobs

{
  "payload": { "to": "[email protected]" },
  "idempotency_key": "welcome-user-42",
  "delay": "30s",
  "schedule_at": null,
  "metadata": {}
}

Response:

{ "job_id": "01J...", "status": "pending" }

Idempotency

When idempotency_key is set, repeating the same key for the same project and queue returns the existing job instead of creating a duplicate.

Inspect

const job = await rest.queues.getJob("emails", jobId);
const jobs = await rest.queues.listJobs("emails", { status: "pending" });

Cancel / retry

await rest.queues.cancelJob("emails", jobId);
await rest.queues.retryJob("emails", jobId);

DELETE /v1/queue/:queueName/jobs/:jobId
POST /v1/queue/:queueName/jobs/:jobId/retry

Queue config

Create a queue (if it does not exist) with:

PUT /v1/queue/:queueName

await rest.queues.updateConfig("emails", {
  maxAttempts: 25,
  webhookUrl: "https://example.com/hooks/qpub",
  webhookSecret: "whsec_...",
});

const config = await rest.queues.getConfig("emails");

Body fields applied on create: max_attempts, webhook_url, webhook_secret.

If the queue already exists, Ensure returns the current config — those request fields are not applied as updates today.

Read the full config (including platform defaults such as visibility timeout) with GET /v1/queue/:queueName or getConfig.

Durations in responses use Go-style strings such as "30s".

Edit this page on GitHub