Queues (ctx.queue)

Run a function later, with retries. Queue the slow or unreliable part of a request, such as sending an email, processing an upload or calling a third-party API, and answer your app straight away.

Queue a job from a function

ctx.queue.enqueue(function, payload, options) runs another function in this project later. It returns the job straight away; the work happens in the background.

signup.ts

TypeScript

export async function handler(ctx) {
  const job = await ctx.queue.enqueue("send-welcome-email", { userId: "u_123" }, { delaySeconds: 60 })
  return { queued: job.id }
}

signup.dart

Dart

Future<Map<String, dynamic>> handler(Map<String, dynamic> ctx) async {
  final queue = ctx['queue'] as Map<String, dynamic>;
  final job = await (queue['enqueue'] as Function)('send-welcome-email', {'userId': 'u_123'}, {'delaySeconds': 60});
  return {'queued': job['id']};
}

functionThe name of a function deployed in this project

payloadAny JSON object, up to 256 KB. Optional.

delaySecondsHow long to wait before running it: 0 (default) to 604800 (7 days)

Receive the job

The queued function gets ctx.request.event set to "queue.job" and your payload in ctx.request.payload.

send-welcome-email.ts

TypeScript

export async function handler(ctx) {
  const { userId } = ctx.request.payload
  // ... send the email ...
  return { sent: true }
}

It runs with the project's own identity, like a trigger: ctx.db and ctx.env work, and ctx.db.asUser() throws, because no user is signed in to a queued job.

Timing and retries

A job starts within about 30 seconds of being due. If the function throws or fails, it runs again after 1, 2, 4 and 8 minutes: five runs in all. After the fifth failure it moves to the Dead Letter Queue.

Make queued functions safe to run twice

A job can run more than once, for example if a run fails after sending the email but before returning. Check first where it matters (was this receipt already sent?) so a repeat does no harm.

Who can queue jobs

Functions, with ctx.queue.
Your own server, with a secret key (sk_…).
Project owners and admins, from the API.

Apps cannot queue jobs directly: a publishable key or a signed-in app user is refused. To queue work from an app, call a function that does it, and check what the user is allowed to do there.

# From your server, with a secret key
curl -X POST https://api.koolbase.com/v1/sdk/queue/jobs \
  -H "x-api-key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"function":"send-welcome-email","payload":{"userId":"u_123"},"delay_seconds":60}'

See and cancel queued jobs

Owners and admins, or an admin-scoped API key:

# Pending jobs, soonest first
curl https://api.koolbase.com/v1/projects/PROJECT_ID/queue/jobs \
  -H "Authorization: Bearer YOUR_ADMIN_KEY"

# Queue one
curl -X POST https://api.koolbase.com/v1/projects/PROJECT_ID/queue/jobs \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{"function":"send-welcome-email","payload":{"userId":"u_123"},"delay_seconds":3600}'

# Cancel one before it runs
curl -X DELETE https://api.koolbase.com/v1/projects/PROJECT_ID/queue/jobs/JOB_ID \
  -H "Authorization: Bearer YOUR_ADMIN_KEY"

Each job shows its id, function, payload, attempt, max_attempts, run_at and, after a failure, last_error. A job leaves the list once it succeeds or moves to the Dead Letter Queue.

From the CLI

Owners and admins can queue, list and cancel jobs from a terminal (CLI v0.8.4 or later). --payload must be a JSON object; --delay is in seconds.

koolbase queue enqueue send-welcome-email --project PROJECT_ID \
  --payload '{"userId":"u_123"}' --delay 60

koolbase queue list --project PROJECT_ID
koolbase queue cancel JOB_ID --project PROJECT_ID

Limits

Delay0 seconds to 7 days

PayloadUp to 256 KB of JSON

Pending jobsUp to 10,000 per project; beyond that, queueing answers 429

TargetMust be a function deployed in the same project

In test mode, ctx.queue.enqueue returns a fake job and queues nothing.