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

await queue.setGlobalConcurrencyAsync(10);
await queue.removeGlobalConcurrencyAsync();
await queue.setGlobalRateLimitAsync(100);         // 100 jobs per second
await queue.setGlobalRateLimitAsync(100, 60_000); // 100 jobs per minute
await queue.removeGlobalRateLimitAsync();
await queue.rateLimit(5000); // Temporary throttle; cleared by the broker
const limit = await queue.getGlobalRateLimit();
const ttl = await queue.getRateLimitTtl();
const maxed = await queue.isMaxed();

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. Both TypeScript packages support the temporary rateLimit(ms) throttle and broker-authoritative limit getters.

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 (the PostgreSQL multi-broker backend returns 0 instead and ignores maxJobs); 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

Guide	What it covers
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