guide · queue

A ceiling on how fast.

Third-party APIs have quotas and databases have limits. These caps live on the queue, so they hold no matter how many workers you start.

Rate limiting and concurrency

Bun

// Cap parallel processing across ALL workers on this queue
queue.setGlobalConcurrency(10);
queue.removeGlobalConcurrency();
await queue.setGlobalConcurrencyAsync(10);   // same, but waits for the server

// Cap throughput: max jobs per window (default window: 1 second)
queue.setGlobalRateLimit(100);          // max 100 jobs per second
queue.setGlobalRateLimit(100, 60_000);  // max 100 jobs per minute
queue.removeGlobalRateLimit();
await queue.setGlobalRateLimitAsync(100, 60_000); // same, but waits for the server

// Temporary throttle to ~1 job/sec; the server clears it after 5s on its own
await queue.rateLimit(5000);

Node.js / Deno

// Cap parallel processing across ALL workers on this queue
await queue.setGlobalConcurrency(10);
await queue.removeGlobalConcurrency();

// Cap throughput: max jobs per window (default: 1 second)
await queue.setGlobalRateLimit(100);          // max 100 jobs per second
await queue.setGlobalRateLimit(100, 60_000);  // max 100 jobs per minute
await queue.removeGlobalRateLimit();

Python

# Cap parallel processing across ALL workers on this queue
queue.set_global_concurrency(10)
queue.remove_global_concurrency()

# Cap throughput: max jobs per window (default: 1 second)
queue.set_global_rate_limit(100)         # max 100 jobs per second
queue.set_global_rate_limit(100, 60000)  # max 100 jobs per minute
queue.remove_global_rate_limit()

PHP

// Cap throughput: max jobs per window (default window: 1 second)
$queue->setRateLimit(100);         // max 100 jobs per second
$queue->setRateLimit(100, 60000);  // max 100 jobs per minute
$queue->clearRateLimit();

Go

// Cap throughput: max jobs per window (default window: 1 second)
queue.SetRateLimit(100)                                               // max 100 jobs per second
queue.SetRateLimit(100, bunqueue.RateLimitOptions{DurationMs: 60000}) // max 100 jobs per minute
queue.ClearRateLimit()

Rust

// Cap throughput: max jobs per window (default window: 1 second)
queue.set_rate_limit(100, None, None)?;          // max 100 jobs per second
queue.set_rate_limit(100, Some(60_000), None)?;  // max 100 jobs per minute
queue.clear_rate_limit()?;

Elixir

# Cap parallel processing across ALL workers on this queue
:ok = Bunqueue.Queue.set_concurrency(queue, 10)
:ok = Bunqueue.Queue.clear_concurrency(queue)

# Cap throughput: max jobs per window (default window: 1 second)
:ok = Bunqueue.Queue.set_rate_limit(queue, 100)
:ok = Bunqueue.Queue.set_rate_limit(queue, 100, duration: 60_000)
:ok = Bunqueue.Queue.clear_rate_limit(queue)

Global concurrency helpers exist in TypeScript, Python, and Elixir; the temporary rateLimit(ms) throttle is available in the Bun bunqueue package only.

Read-back semantics

• rateLimit(ms) throws on non-positive or non-finite ms. The expiry lives on the server, so it also survives your process exiting.
• getGlobalConcurrency() and getGlobalRateLimit() return the live configured values in embedded and TCP modes.
• getRateLimitTtl(maxJobs?) returns -2 when no rate limit exists; otherwise it reports the temporary-limit lifetime or token wait.
• isMaxed() reports whether the queue’s global concurrency slots are all occupied.

See Rate Limiting for worker-side limiting too.

Where to go next

Queue API	Create a queue in embedded or TCP mode
Adding Jobs	add, addBulk, priorities, delays, durability
Deduplication and Idempotent Job Adds	Idempotent adds, dedup keys, custom job ids
Querying Jobs	Fetch jobs, states, counts and results
Queue Control and Maintenance	Pause, drain, obliterate, clean and repair
Progress, Job Logs and Dependencies	Progress, per-job logs and dependencies
Job Schedulers from the Queue	Named repeatable schedules from the queue
DLQ Operations from the Queue Object	Failed-job operations from the Queue object
Workers, Stats and Metrics from the Queue	Registered workers, stats and metrics windows
Namespaces, Auto-Batching and Store-and-Forward	Namespaces, auto-batching, store-and-forward
JobOptions Reference	Every JobOptions field, with defaults